diff options
Diffstat (limited to 'doc/driver-model')
| -rw-r--r-- | doc/driver-model/design.rst (renamed from doc/driver-model/README.txt) | 589 | ||||
| -rw-r--r-- | doc/driver-model/fdt-fixup.rst (renamed from doc/driver-model/fdt-fixup.txt) | 56 | ||||
| -rw-r--r-- | doc/driver-model/fs_firmware_loader.rst | 154 | ||||
| -rw-r--r-- | doc/driver-model/fs_firmware_loader.txt | 148 | ||||
| -rw-r--r-- | doc/driver-model/i2c-howto.rst (renamed from doc/driver-model/i2c-howto.txt) | 36 | ||||
| -rw-r--r-- | doc/driver-model/index.rst | 21 | ||||
| -rw-r--r-- | doc/driver-model/livetree.rst (renamed from doc/driver-model/livetree.txt) | 94 | ||||
| -rw-r--r-- | doc/driver-model/migration.rst (renamed from doc/driver-model/MIGRATION.txt) | 44 | ||||
| -rw-r--r-- | doc/driver-model/of-plat.rst (renamed from doc/driver-model/of-plat.txt) | 193 | ||||
| -rw-r--r-- | doc/driver-model/pci-info.rst (renamed from doc/driver-model/pci-info.txt) | 21 | ||||
| -rw-r--r-- | doc/driver-model/pmic-framework.rst (renamed from doc/driver-model/pmic-framework.txt) | 131 | ||||
| -rw-r--r-- | doc/driver-model/remoteproc-framework.rst (renamed from doc/driver-model/remoteproc-framework.txt) | 181 | ||||
| -rw-r--r-- | doc/driver-model/serial-howto.rst (renamed from doc/driver-model/serial-howto.txt) | 12 | ||||
| -rw-r--r-- | doc/driver-model/spi-howto.rst | 692 | ||||
| -rw-r--r-- | doc/driver-model/spi-howto.txt | 623 | ||||
| -rw-r--r-- | doc/driver-model/usb-info.rst (renamed from doc/driver-model/usb-info.txt) | 184 |
16 files changed, 1674 insertions, 1505 deletions
diff --git a/doc/driver-model/README.txt b/doc/driver-model/design.rst index 532a771f68..8fd28c0f52 100644 --- a/doc/driver-model/README.txt +++ b/doc/driver-model/design.rst @@ -1,40 +1,46 @@ -Driver Model -============ +.. SPDX-License-Identifier: GPL-2.0+ +.. sectionauthor:: Simon Glass <sjg@chromium.org> + +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: - Marek Vasut <marex@denx.de> - Pavel Herrmann <morpheus.ibis@gmail.com> - Viktor Křivák <viktor.krivak@gmail.com> - Tomas Hlavacek <tmshlvck@gmail.com> + * Marek Vasut <marex@denx.de> + * Pavel Herrmann <morpheus.ibis@gmail.com> + * Viktor Křivák <viktor.krivak@gmail.com> + * Tomas Hlavacek <tmshlvck@gmail.com> This has been both simplified and extended into the current implementation by: - Simon Glass <sjg@chromium.org> + * Simon Glass <sjg@chromium.org> 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. +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. +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. +Device + an instance of a driver, tied to a particular port or peripheral. How to try it ------------- -Build U-Boot sandbox and run it: +Build U-Boot sandbox and run it:: make sandbox_defconfig make @@ -56,31 +62,31 @@ provide good code coverage of them. It does have multiple drivers, it handles parameter data and platdata (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 -=> +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 @@ -88,139 +94,139 @@ 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: +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 =================== +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? ----------------- @@ -228,6 +234,8 @@ What is going on? Let's start at the top. The demo command is in common/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); @@ -245,6 +253,8 @@ 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' @@ -253,28 +263,32 @@ this particular device may use one or other of them. The code for demo_hello() is in drivers/demo/demo-uclass.c: -int demo_hello(struct udevice *dev, int ch) -{ - const struct demo_ops *ops = device_get_ops(dev); +.. code-block:: c - if (!ops->hello) - return -ENOSYS; + int demo_hello(struct udevice *dev, int ch) + { + const struct demo_ops *ops = device_get_ops(dev); - return ops->hello(dev, ch); -} + 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: -static int simple_hello(struct udevice *dev, int ch) -{ - const struct dm_demo_pdata *pdata = dev_get_platdata(dev); +.. code-block:: c + + static int simple_hello(struct udevice *dev, int ch) + { + const struct dm_demo_pdata *pdata = dev_get_platdata(dev); - printf("Hello from %08x: %s %d\n", map_to_sysmem(dev), - pdata->colour, pdata->sides); + printf("Hello from %08x: %s %d\n", map_to_sysmem(dev), + pdata->colour, pdata->sides); - return 0; -} + return 0; + } So that is a trip from top (command execution) to bottom (driver action) @@ -287,17 +301,19 @@ Declaring Drivers A driver declaration looks something like this (see drivers/demo/demo-shape.c): -static const struct demo_ops shape_ops = { - .hello = shape_hello, - .status = shape_status, -}; +.. code-block:: c -U_BOOT_DRIVER(demo_shape_drv) = { - .name = "demo_shape_drv", - .id = UCLASS_DEMO, - .ops = &shape_ops, - .priv_data_size = sizeof(struct shape_data), -}; + 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 @@ -315,11 +331,11 @@ 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 - ofdata_to_platdata - convert device tree data to platdata - see later - probe - make a device ready for use - remove - remove a device so it cannot be used until probed again + * bind - make the driver model aware of a device (bind it to its driver) + * unbind - make the driver model forget the device + * ofdata_to_platdata - convert device tree data to platdata - 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, ofdata_to_platdata (if using device tree) and probe. @@ -328,14 +344,14 @@ 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. +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. @@ -366,9 +382,9 @@ 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 + - 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 @@ -384,10 +400,13 @@ Drivers can access their data via dev->info->platdata. Here is the declaration for the platform data, which would normally appear in the board file. +.. code-block:: c + static const struct dm_demo_cdata red_square = { .colour = "red", .sides = 4. }; + static const struct driver_info info[] = { { .name = "demo_shape_drv", @@ -409,6 +428,8 @@ 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"; @@ -425,6 +446,8 @@ the board first!). The easiest way to make this work it to add a few members to the driver: +.. code-block:: c + .platdata_auto_alloc_size = sizeof(struct dm_test_pdata), .ofdata_to_platdata = testfdt_ofdata_to_platdata, @@ -464,9 +487,11 @@ Declaring Uclasses The demo uclass is declared like this: -U_BOOT_CLASS(demo) = { - .id = UCLASS_DEMO, -}; +.. code-block:: c + + U_BOOT_CLASS(demo) = { + .id = UCLASS_DEMO, + }; It is also possible to specify special methods for probe, etc. The uclass numbering comes from include/dm/uclass.h. To add a new uclass, add to the @@ -496,9 +521,11 @@ device will be automatically allocated the next available sequence number. To specify the sequence number in the device tree an alias is typically used. Make sure that the uclass has the DM_UC_FLAG_SEQ_ALIAS flag set. -aliases { - serial2 = "/serial@22230000"; -}; +.. 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 @@ -506,13 +533,15 @@ which requests serial device 2 will obtain this device. More commonly you can use node references, which expand to the full path: -aliases { - serial2 = &serial_2; -}; -... -serial_2: serial@22230000 { -... -}; +.. 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. @@ -547,7 +576,7 @@ 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: +up) uclass:: xhci_usb (UCLASS_USB) eth (UCLASS_ETHERNET) @@ -579,7 +608,7 @@ 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: +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 @@ -613,20 +642,21 @@ 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. -1. Bind stage +Bind stage +^^^^^^^^^^ U-Boot discovers devices using one of these two methods: - - Scan the U_BOOT_DEVICE() 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_DEVICE() -may provide platdata. +- Scan the U_BOOT_DEVICE() 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_DEVICE() + may provide platdata. - - 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 platdata cannot be provided until later. +- 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 platdata 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, @@ -653,45 +683,46 @@ 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. -2. Activation/probe +Activation/probe +^^^^^^^^^^^^^^^^ When a device needs to be used, U-Boot activates it, by following these steps (see device_probe()): - a. If priv_auto_alloc_size is non-zero, then the device-private space + 1. If priv_auto_alloc_size 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). - b. If platdata_auto_alloc_size is non-zero, then the platform data space + 2. If platdata_auto_alloc_size is non-zero, then the platform data space is allocated. This is only useful for device tree operation, since otherwise you would have to specific the platform data in the U_BOOT_DEVICE() declaration. The space is allocated for the device and zeroed. It will be accessible as dev->platdata. - c. If the device's uclass specifies a non-zero per_device_auto_alloc_size, + 3. If the device's uclass specifies a non-zero per_device_auto_alloc_size, 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. - d. If the device's immediate parent specifies a per_child_auto_alloc_size + 4. If the device's immediate parent specifies a per_child_auto_alloc_size 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. - e. All parent devices are probed. It is not possible to activate a device + 5. 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. - f. The device's sequence number is assigned, either the requested one + 6. The device's sequence number is assigned, either the requested one (assuming no conflicts) or the next available one if there is a conflict or nothing particular is requested. - g. If the driver provides an ofdata_to_platdata() method, then this is + 7. If the driver provides an ofdata_to_platdata() method, then this is called to convert the device tree data into platform data. This should do various calls like fdtdec_get_int(gd->fdt_blob, dev_of_offset(dev), ...) to access the node and store the resulting information into dev->platdata. @@ -707,7 +738,7 @@ steps (see device_probe()): data, one day it is possible that U-Boot will cache platform data for devices which are regularly de/activated). - h. The device's probe() method is called. This should do anything that + 8. 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 @@ -722,40 +753,42 @@ steps (see device_probe()): allocate the priv space here yourself. The same applies also to platdata_auto_alloc_size. Remember to free them in the remove() method. - i. The device is marked 'activated' + 9. The device is marked 'activated' - j. The uclass's post_probe() method is called, if one exists. This may + 10. 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. -3. Running stage +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. -4. Removal stage +Removal stage +^^^^^^^^^^^^^ When the device is no-longer required, you can call device_remove() to remove it. This performs the probe steps in reverse: - a. The uclass's pre_remove() method is called, if one exists. This may + 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. - b. All the device's children are removed. It is not permitted to have + 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. - c. The device's remove() method is called. At this stage nothing has been + 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. - d. The device memory is freed (platform data, private data, uclass data, + 4. The device memory is freed (platform data, private data, uclass data, parent data). Note: Because the platform data for a U_BOOT_DEVICE() is defined with a @@ -764,25 +797,26 @@ remove it. This performs the probe steps in reverse: be dynamically allocated, and thus needs to be deallocated during the remove() method, either: - 1. if the platdata_auto_alloc_size is non-zero, the deallocation - happens automatically within the driver model core; or + - if the platdata_auto_alloc_size is non-zero, the deallocation + happens automatically within the driver model core; or - 2. when platdata_auto_alloc_size is 0, both the allocation (in probe() - or preferably ofdata_to_platdata()) and the deallocation in remove() - are the responsibility of the driver author. + - when platdata_auto_alloc_size is 0, both the allocation (in probe() + or preferably ofdata_to_platdata()) and the deallocation in remove() + are the responsibility of the driver author. - e. The device sequence number is set to -1, meaning that it no longer + 5. The device sequence number is set to -1, meaning that it no longer has an allocated sequence. If the device is later reactivated and that sequence number is still free, it may well receive the name sequence number again. But from this point, the sequence number previously used by this device will no longer exist (think of SPI bus 2 being removed and bus 2 is no longer available for use). - f. The device is marked inactive. Note that it is still bound, so the + 6. 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. -5. Unbind stage +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 @@ -805,24 +839,24 @@ 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. + 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. + 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 platdata, etc.) + instead of struct instance, struct platdata, 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'. + 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. + This removes a level of indirection that doesn't seem necessary. - Built in device tree support, to avoid the need for platdata - 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. + 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 @@ -903,12 +937,3 @@ 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. - - -Simon Glass -sjg@chromium.org -April 2013 -Updated 7-May-13 -Updated 14-Jun-13 -Updated 18-Oct-13 -Updated 5-Nov-13 diff --git a/doc/driver-model/fdt-fixup.txt b/doc/driver-model/fdt-fixup.rst index 70344bd2c3..974c09031e 100644 --- a/doc/driver-model/fdt-fixup.txt +++ b/doc/driver-model/fdt-fixup.rst @@ -1,15 +1,11 @@ +.. SPDX-License-Identifier: GPL-2.0+ +.. 2017-01-06, Mario Six <mario.six@gdsys.cc> + Pre-relocation device tree manipulation ======================================= -Contents: - -1. Purpose -2. Implementation -3. Example -4. Work to be done - -1. Purpose ----------- +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 @@ -61,14 +57,16 @@ 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. -2. Implementation ------------------ +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: -int board_fix_fdt (void *rw_fdt_blob) +.. 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 @@ -79,10 +77,10 @@ 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: +to be called:: -Device Tree Control --> [*] Board-specific manipulation of Device Tree + Device Tree Control + -> [*] Board-specific manipulation of Device Tree +----------------------------------------------------------+ | WARNING: The actual manipulation of the device tree has | @@ -97,23 +95,27 @@ Device Tree Control Hence, the recommended layout of the board_fixup_fdt call-back function is the following: -int board_fix_fdt(void *rw_fdt_blob) -{ - /* Collect information about device's hardware and store them in e.g. - local variables */ +.. 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 */ + /* Do device tree manipulation using the values previously collected */ - /* Return 0 on successful manipulation and non-zero otherwise */ -} + /* 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. -3. Example ----------- +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 @@ -123,10 +125,8 @@ 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. -4. Work to be done ------------------- +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. - -2017-01-06, Mario Six <mario.six@gdsys.cc> diff --git a/doc/driver-model/fs_firmware_loader.rst b/doc/driver-model/fs_firmware_loader.rst new file mode 100644 index 0000000000..a44708cb4c --- /dev/null +++ b/doc/driver-model/fs_firmware_loader.rst @@ -0,0 +1,154 @@ +.. 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); diff --git a/doc/driver-model/fs_firmware_loader.txt b/doc/driver-model/fs_firmware_loader.txt deleted file mode 100644 index 8be6185371..0000000000 --- a/doc/driver-model/fs_firmware_loader.txt +++ /dev/null @@ -1,148 +0,0 @@ -# Copyright (C) 2018-2019 Intel Corporation <www.intel.com> -# -# SPDX-License-Identifier: GPL-2.0 - -Introduction -============ - -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: - 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 -------------------------------- - -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: - -1. struct udevice *dev - An instance of a driver - -2. const char *name - name of firmware file - -3. void *buf - address of buffer to load firmware into - -4. size_t size - size of buffer - -5. u32 offset - offset of a file for start reading into buffer - -return: - 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: - 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); diff --git a/doc/driver-model/i2c-howto.txt b/doc/driver-model/i2c-howto.rst index 8ba2f6e267..938b707d3d 100644 --- a/doc/driver-model/i2c-howto.txt +++ b/doc/driver-model/i2c-howto.rst @@ -1,21 +1,23 @@ -How to port a serial driver to driver model -=========================================== +.. 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 + * 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! @@ -27,14 +29,14 @@ model. Please feel free to update this file with your ideas and suggestions. - 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 + 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 + implementations can share most of the existing code - If you convert all existing users of the driver, remove the pre-driver-model - code + code In terms of patches a conversion series typically has these patches: - clean up / prepare the driver for conversion diff --git a/doc/driver-model/index.rst b/doc/driver-model/index.rst new file mode 100644 index 0000000000..ea32c36335 --- /dev/null +++ b/doc/driver-model/index.rst @@ -0,0 +1,21 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +Driver Model +============ + +.. toctree:: + :maxdepth: 2 + + design + fdt-fixup + fs_firmware_loader + i2c-howto + livetree + migration + of-plat + pci-info + pmic-framework + remoteproc-framework + serial-howto + spi-howto + usb-info diff --git a/doc/driver-model/livetree.txt b/doc/driver-model/livetree.rst index 01d4488c60..9f654f3b89 100644 --- a/doc/driver-model/livetree.txt +++ b/doc/driver-model/livetree.rst @@ -1,5 +1,8 @@ -Driver Model with Live Device Tree -================================== +.. SPDX-License-Identifier: GPL-2.0+ +.. sectionauthor:: Simon Glass <sjg@chromium.org> + +Live Device Tree +================ Introduction @@ -20,7 +23,7 @@ Motivation The flat device tree has several advantages: - it is the format produced by the device tree compiler, so no translation -is needed + is needed - it is fairly compact (e.g. there is no need for pointers) @@ -53,12 +56,12 @@ 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 +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. +'struct udevice \*', rather than having to obtain the ofnode first. -The 'dev_read_...()' interface provides this. It allows properties to be +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. @@ -85,6 +88,8 @@ 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); @@ -94,17 +99,21 @@ For example, the old code may be like this: 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 +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; @@ -115,6 +124,8 @@ back to using ofnode. For example, for old code like this: you should use: +.. code-block:: c + ofnode subnode; ofnode_for_each_subnode(subnode, dev_ofnode(dev)) { @@ -128,8 +139,8 @@ 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 + :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 @@ -149,20 +160,29 @@ 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 +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 +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) +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 @@ -199,13 +219,13 @@ the flat tree. Internal implementation ----------------------- -The dev_read_...() functions have two implementations. When +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 +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 @@ -225,7 +245,7 @@ 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 +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. @@ -236,23 +256,22 @@ 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 + - 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. + 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. + 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). + - 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 @@ -265,8 +284,3 @@ of work to do to flesh this out: - support for livetree modification - addition of more access functions as needed - support for livetree in SPL and before relocation (if desired) - - --- -Simon Glass <sjg@chromium.org> -5-Aug-17 diff --git a/doc/driver-model/MIGRATION.txt b/doc/driver-model/migration.rst index d38be3538a..a26e7ab7e1 100644 --- a/doc/driver-model/MIGRATION.txt +++ b/doc/driver-model/migration.rst @@ -1,5 +1,7 @@ +.. 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 @@ -8,8 +10,8 @@ features. CONFIG_DM_MMC ------------- -Status: In progress -Deadline: 2019.04 +* 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 @@ -18,8 +20,8 @@ time for inclusion in the 2019.04 rerelease. CONFIG_DM_USB ------------- -Status: In progress -Deadline: 2019.07 +* 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 @@ -28,8 +30,8 @@ other base driver model options in time for inclusion in the 2019.07 rerelease. CONFIG_SATA ----------- -Status: In progress -Deadline: 2019.07 +* 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 @@ -38,8 +40,8 @@ other base driver model options in time for inclusion in the 2019.07 rerelease. CONFIG_BLK ---------- -Status: In progress -Deadline: 2019.07 +* 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 @@ -48,14 +50,14 @@ 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 -------------------- +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. -No dm conversion yet: +No dm conversion yet:: + drivers/spi/cf_spi.c drivers/spi/fsl_espi.c drivers/spi/lpc32xx_ssp.c @@ -63,10 +65,11 @@ No dm conversion yet: drivers/spi/sh_spi.c drivers/spi/soft_spi_legacy.c - Status: In progress - Deadline: 2019.04 +* Status: In progress +* Deadline: 2019.04 + +Partially converted:: -Partially converted: drivers/spi/davinci_spi.c drivers/spi/fsl_dspi.c drivers/spi/kirkwood_spi.c @@ -74,13 +77,8 @@ Partially converted: drivers/spi/omap3_spi.c drivers/spi/sh_qspi.c - Status: In progress - Deadline: 2019.07 - --- -Jagan Teki <jagan@openedev.com> -12/24/2018 -03/14/2018 +* Status: In progress +* Deadline: 2019.07 CONFIG_DM_PCI diff --git a/doc/driver-model/of-plat.txt b/doc/driver-model/of-plat.rst index 0109ec56c3..0d3cd8c01e 100644 --- a/doc/driver-model/of-plat.txt +++ b/doc/driver-model/of-plat.rst @@ -1,5 +1,7 @@ -Driver Model Compiled-in Device Tree / Platform Data -==================================================== +.. SPDX-License-Identifier: GPL-2.0+ + +Compiled-in Device Tree / Platform Data +======================================= Introduction @@ -40,36 +42,36 @@ There are many problems with this features. It should only be used when strictly necessary. Notable problems 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 device tree file. + 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 device tree file. - Naming of nodes and properties is automatic. This means that they follow - the naming in the device tree, which may result in C identifiers that - look a bit strange. + the naming in the device tree, 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 device-tree changes. It also - makes it very unlikely that your driver code will be useful for more - than one SoC. Even if the code is common, each SoC will end up with - a different C struct name, and a likely a different format for the - platform data. + the associated C member variable directly in the code. This makes + the code less robust in the face of device-tree changes. It also + makes it very unlikely that your driver code will be useful for more + than one SoC. Even if the code is common, each SoC will end up with + a different C struct name, and a likely a different format for the + platform data. - 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 device tree it must use #ifdef to separate - out this code, since the structures are only available in SPL. + must use the same structure to access the data. Since a driver + normally also supports device tree it must use #ifdef to separate + out this code, since the structures are only available in SPL. - Correct relations between nodes are not implemented. This means that - parent/child relations (like bus device iteration) do not work yet. - Some phandles (those that are recognised as such) are converted into - a pointer to platform data. This pointer can potentially be used to - access the referenced device (by searching for the pointer value). - This feature is not yet implemented, however. + parent/child relations (like bus device iteration) do not work yet. + Some phandles (those that are recognised as such) are converted into + a pointer to platform data. This pointer can potentially be used to + access the referenced device (by searching for the pointer value). + This feature is not yet implemented, however. How it works @@ -78,30 +80,34 @@ How it works The feature is enabled by CONFIG OF_PLATDATA. This is only available in SPL/TPL and should be tested with: - #if CONFIG_IS_ENABLED(OF_PLATDATA) +.. code-block:: c + + #if CONFIG_IS_ENABLED(OF_PLATDATA) A new tool called 'dtoc' converts a device tree file either into a set of struct declarations, one for each compatible node, and a set of U_BOOT_DEVICE() declarations along with the actual platform data for each device. As an example, consider this MMC node: - 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>; +.. 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; @@ -112,52 +118,59 @@ 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: -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; -}; +.. 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 declaration: -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 = {{&dtv_clock_controller_at_ff760000, 456}, - {&dtv_clock_controller_at_ff760000, 68}, - {&dtv_clock_controller_at_ff760000, 114}, - {&dtv_clock_controller_at_ff760000, 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_DEVICE(dwmmc_at_ff0c0000) = { - .name = "rockchip_rk3288_dw_mshc", - .platdata = &dtv_dwmmc_at_ff0c0000, - .platdata_size = sizeof(dtv_dwmmc_at_ff0c0000), -}; +.. code-block:: c + + 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 = {{&dtv_clock_controller_at_ff760000, 456}, + {&dtv_clock_controller_at_ff760000, 68}, + {&dtv_clock_controller_at_ff760000, 114}, + {&dtv_clock_controller_at_ff760000, 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_DEVICE(dwmmc_at_ff0c0000) = { + .name = "rockchip_rk3288_dw_mshc", + .platdata = &dtv_dwmmc_at_ff0c0000, + .platdata_size = sizeof(dtv_dwmmc_at_ff0c0000), + }; The device is then instantiated at run-time and the platform data can be accessed using: - struct udevice *dev; - struct dtd_rockchip_rk3288_dw_mshc *plat = dev_get_platdata(dev); +.. code-block:: c + + struct udevice *dev; + struct dtd_rockchip_rk3288_dw_mshc *plat = dev_get_platdata(dev); This avoids the code overhead of converting the device tree data to platform data in the driver. The ofdata_to_platdata() method should @@ -173,7 +186,9 @@ each 'compatible' string. Where a node has multiple compatible strings, a #define is used to make them equivalent, e.g.: -#define dtd_rockchip_rk3299_dw_mshc dtd_rockchip_rk3288_dw_mshc +.. code-block:: c + + #define dtd_rockchip_rk3299_dw_mshc dtd_rockchip_rk3288_dw_mshc Converting of-platdata to a useful form @@ -204,6 +219,8 @@ ofdata_to_platdata() method and wrapped with #if. For example: +.. code-block:: c + #include <dt-structs.h> struct mmc_platdata { @@ -313,12 +330,12 @@ This is an implementation of an idea by Tom Rini <trini@konsulko.com>. Future work ----------- - Consider programmatically reading binding files instead of device tree - contents + contents - Complete the phandle feature - Move to using a full Python libfdt module --- -Simon Glass <sjg@chromium.org> -Google, Inc -6/6/16 -Updated Independence Day 2016 + +.. Simon Glass <sjg@chromium.org> +.. Google, Inc +.. 6/6/16 +.. Updated Independence Day 2016 diff --git a/doc/driver-model/pci-info.txt b/doc/driver-model/pci-info.rst index 14364c5c75..d93ab8b61d 100644 --- a/doc/driver-model/pci-info.txt +++ b/doc/driver-model/pci-info.rst @@ -1,3 +1,5 @@ +.. SPDX-License-Identifier: GPL-2.0+ + PCI with Driver Model ===================== @@ -7,8 +9,7 @@ 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: - +tree file will point to the correct device:: aliases { pci0 = &pci; @@ -45,7 +46,7 @@ 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: +their drivers accordingly. A working example like below:: pci { #address-cells = <3>; @@ -113,7 +114,7 @@ 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 a -driver. For example: +driver. For example:: pci@1f,0 { @@ -129,11 +130,11 @@ 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) -When this bus is scanned we will end up with something like this: +When this bus is scanned we will end up with something like this:: -`- * pci-controller @ 05c660c8, 0 - `- pci@1f,0 @ 05c661c8, 63488 - `- emul@1f,0 @ 05c662c8 + `- * pci-controller @ 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 child, the emulator. @@ -144,6 +145,8 @@ 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-controller1 { compatible = "sandbox,pci"; ... @@ -156,7 +159,7 @@ 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: +When this bus is scanned we will end up with something like this:: pci [ + ] pci_sandbo |-- pci-controller1 pci_emul [ ] sandbox_sw | |-- sandbox_swap_case_emul diff --git a/doc/driver-model/pmic-framework.txt b/doc/driver-model/pmic-framework.rst index 95b1a66bd5..d24a1badd6 100644 --- a/doc/driver-model/pmic-framework.txt +++ b/doc/driver-model/pmic-framework.rst @@ -1,63 +1,59 @@ -# -# (C) Copyright 2014-2015 Samsung Electronics -# Przemyslaw Marczak <p.marczak@samsung.com> -# -# SPDX-License-Identifier: GPL-2.0+ -# +.. SPDX-License-Identifier: GPL-2.0+ +.. (C) Copyright 2014-2015 Samsung Electronics +.. sectionauthor:: Przemyslaw Marczak <p.marczak@samsung.com> PMIC framework based on Driver Model ==================================== -TOC: -1. Introduction -2. How does it work -3. Pmic uclass -4. Regulator uclass - -1. Introduction -=============== + +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. + +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 + - drivers/power/pmic/pmic-uclass.c + - include/power/pmic.h UCLASS_REGULATOR: -- drivers/power/regulator/regulator-uclass.c -- include/power/regulator.h + - drivers/power/regulator/regulator-uclass.c + - include/power/regulator.h Commands: - common/cmd_pmic.c - common/cmd_regulator.c -2. How doees it work -==================== +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 - . +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, @@ -66,26 +62,27 @@ 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 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. +- 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. -3. Pmic uclass -============== +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' +* 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. @@ -109,20 +106,26 @@ for pmic I/O operations only. For more information, please refer to the core file. -4. Regulator uclass -=================== +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' + +* 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) + 'drivers/power/pmic/max77686.c' (required I/O driver for the above) + * Example: 'drivers/power/regulator/fixed.c' - config" 'CONFIG_DM_REGULATOR_FIXED' + (config 'CONFIG_DM_REGULATOR_FIXED') For detailed API description, please refer to the header file. diff --git a/doc/driver-model/remoteproc-framework.txt b/doc/driver-model/remoteproc-framework.rst index c6dc00dca3..f21de0a10f 100644 --- a/doc/driver-model/remoteproc-framework.txt +++ b/doc/driver-model/remoteproc-framework.rst @@ -1,19 +1,12 @@ -# SPDX-License-Identifier: GPL-2.0+ -# -# (C) Copyright 2015 -# Texas Instruments Incorporated - http://www.ti.com/ -# +.. SPDX-License-Identifier: GPL-2.0+ +.. (C) Copyright 2015 +.. Texas Instruments Incorporated - http://www.ti.com/ Remote Processor Framework ========================== -TOC: -1. Introduction -2. How does it work - The driver -3. Describing the device using platform data -4. Describing the device using device tree -1. Introduction -=============== +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 @@ -24,43 +17,44 @@ 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 + - drivers/remoteproc/rproc-uclass.c + - include/remoteproc.h Commands: -- common/cmd_remoteproc.c + - common/cmd_remoteproc.c Configuration: -CONFIG_REMOTEPROC is selected by drivers as needed -CONFIG_CMD_REMOTEPROC for the commands if required. - -2. 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) +---------+ + - 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. @@ -83,23 +77,25 @@ The driver follows a standard UCLASS DM. in the bare minimum form: -static const struct dm_rproc_ops sandbox_testproc_ops = { - .load = sandbox_testproc_load, - .start = sandbox_testproc_start, -}; +.. code-block:: c -static const struct udevice_id sandbox_ids[] = { - {.compatible = "sandbox,test-processor"}, - {} -}; + 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, -}; + 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. @@ -110,8 +106,8 @@ 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. -3. Describing the device using platform data -============================================ +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 @@ -121,16 +117,18 @@ TO DM/FDT. Considering that many platforms are yet to move to device-tree model, a simplified definition of a device is as follows: -struct dm_rproc_uclass_pdata proc_3_test = { - .name = "proc_3_legacy", - .mem_type = RPROC_INTERNAL_MEMORY_MAPPED, - .driver_plat_data = &mydriver_data; -}; +.. code-block:: c -U_BOOT_DEVICE(proc_3_demo) = { - .name = "sandbox_test_proc", - .platdata = &proc_3_test, -}; + 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_DEVICE(proc_3_demo) = { + .name = "sandbox_test_proc", + .platdata = &proc_3_test, + }; There can be additional data that may be desired depending on the remoteproc driver specific needs (for example: SoC integration @@ -138,30 +136,33 @@ 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. -3. Describing the device using device tree -========================================== -/ { - ... - aliases { +Describing the device using device tree +--------------------------------------- + +.. code-block: none + + / { ... - remoteproc0 = &rproc_1; - remoteproc1 = &rproc_2; + aliases { + ... + remoteproc0 = &rproc_1; + remoteproc1 = &rproc_2; - }; - ... + }; + ... - rproc_1: rproc@1 { - compatible = "sandbox,test-processor"; - remoteproc-name = "remoteproc-test-dev1"; - }; + 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"; + 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. diff --git a/doc/driver-model/serial-howto.txt b/doc/driver-model/serial-howto.rst index a0df9a7ec2..1469131124 100644 --- a/doc/driver-model/serial-howto.txt +++ b/doc/driver-model/serial-howto.rst @@ -1,11 +1,13 @@ +.. 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 + * 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! @@ -17,14 +19,14 @@ model. Please feel free to update this file with your ideas and suggestions. - 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 + 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 + implementations can share most of the existing code - If you convert all existing users of the driver, remove the pre-driver-model - code + code In terms of patches a conversion series typically has these patches: - clean up / prepare the driver for conversion diff --git a/doc/driver-model/spi-howto.rst b/doc/driver-model/spi-howto.rst new file mode 100644 index 0000000000..a538fdcb93 --- /dev/null +++ b/doc/driver-model/spi-howto.rst @@ -0,0 +1,692 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +How to port a SPI driver to driver model +======================================== + +Here is a rough step-by-step guide. It is based around converting the +exynos SPI driver to driver model (DM) and the example code is based +around U-Boot v2014.10-rc2 (commit be9f643). This has been updated for +v2015.04. + +It is quite long since it includes actual code examples. + +Before driver model, SPI drivers have their own private structure which +contains 'struct spi_slave'. With driver model, 'struct spi_slave' still +exists, but now it is 'per-child data' for the SPI bus. Each child of the +SPI bus is a SPI slave. The information that was stored in the +driver-specific slave structure can now be port in private data for the +SPI bus. + +For example, struct tegra_spi_slave looks like this: + +.. code-block:: c + + struct tegra_spi_slave { + struct spi_slave slave; + struct tegra_spi_ctrl *ctrl; + }; + +In this case 'slave' will be in per-child data, and 'ctrl' will be in the +SPI's buses private data. + + +How long does this take? +------------------------ + +You should be able to complete this within 2 hours, including testing but +excluding preparing the patches. The API is basically the same as before +with only minor changes: + +- methods to set speed and mode are separated out +- cs_info is used to get information on a chip select + + +Enable driver mode for SPI and SPI flash +---------------------------------------- + +Add these to your board config: + +* CONFIG_DM_SPI +* CONFIG_DM_SPI_FLASH + + +Add the skeleton +---------------- + +Put this code at the bottom of your existing driver file: + +.. code-block:: c + + struct spi_slave *spi_setup_slave(unsigned int busnum, unsigned int cs, + unsigned int max_hz, unsigned int mode) + { + return NULL; + } + + struct spi_slave *spi_setup_slave_fdt(const void *blob, int slave_node, + int spi_node) + { + return NULL; + } + + static int exynos_spi_ofdata_to_platdata(struct udevice *dev) + { + return -ENODEV; + } + + static int exynos_spi_probe(struct udevice *dev) + { + return -ENODEV; + } + + static int exynos_spi_remove(struct udevice *dev) + { + return -ENODEV; + } + + static int exynos_spi_claim_bus(struct udevice *dev) + { + + return -ENODEV; + } + + static int exynos_spi_release_bus(struct udevice *dev) + { + + return -ENODEV; + } + + static int exynos_spi_xfer(struct udevice *dev, unsigned int bitlen, + const void *dout, void *din, unsigned long flags) + { + + return -ENODEV; + } + + static int exynos_spi_set_speed(struct udevice *dev, uint speed) + { + return -ENODEV; + } + + static int exynos_spi_set_mode(struct udevice *dev, uint mode) + { + return -ENODEV; + } + + static int exynos_cs_info(struct udevice *bus, uint cs, + struct spi_cs_info *info) + { + return -ENODEV; + } + + static const struct dm_spi_ops exynos_spi_ops = { + .claim_bus = exynos_spi_claim_bus, + .release_bus = exynos_spi_release_bus, + .xfer = exynos_spi_xfer, + .set_speed = exynos_spi_set_speed, + .set_mode = exynos_spi_set_mode, + .cs_info = exynos_cs_info, + }; + + static const struct udevice_id exynos_spi_ids[] = { + { .compatible = "samsung,exynos-spi" }, + { } + }; + + U_BOOT_DRIVER(exynos_spi) = { + .name = "exynos_spi", + .id = UCLASS_SPI, + .of_match = exynos_spi_ids, + .ops = &exynos_spi_ops, + .ofdata_to_platdata = exynos_spi_ofdata_to_platdata, + .probe = exynos_spi_probe, + .remove = exynos_spi_remove, + }; + + +Replace 'exynos' in the above code with your driver name +-------------------------------------------------------- + + +#ifdef out all of the code in your driver except for the above +-------------------------------------------------------------- + +This will allow you to get it building, which means you can work +incrementally. Since all the methods return an error initially, there is +less chance that you will accidentally leave something in. + +Also, even though your conversion is basically a rewrite, it might help +reviewers if you leave functions in the same place in the file, +particularly for large drivers. + + +Add some includes +----------------- + +Add these includes to your driver: + +.. code-block:: c + + #include <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_platdata { + enum periph_id periph_id; + s32 frequency; /* Default clock frequency, -1 for none */ + struct exynos_spi *regs; + uint deactivate_delay_us; /* Delay to wait after deactivate */ + }; + + +Write ofdata_to_platdata() [for device tree only] +------------------------------------------------- + +This method will convert information in the device tree node into a C +structure in your driver (called platform data). If you are not using +device tree, go to 8b. + +DM will automatically allocate the struct for us when we are using device +tree, but we need to tell it the size: + +.. code-block:: c + + U_BOOT_DRIVER(spi_exynos) = { + ... + .platdata_auto_alloc_size = sizeof(struct exynos_spi_platdata), + + +Here is a sample function. It gets a pointer to the platform data and +fills in the fields from device tree. + +.. code-block:: c + + static int exynos_spi_ofdata_to_platdata(struct udevice *bus) + { + struct exynos_spi_platdata *plat = bus->platdata; + const void *blob = gd->fdt_blob; + int node = dev_of_offset(bus); + + plat->regs = (struct exynos_spi *)fdtdec_get_addr(blob, node, "reg"); + plat->periph_id = pinmux_decode_periph_id(blob, node); + + if (plat->periph_id == PERIPH_ID_NONE) { + debug("%s: Invalid peripheral ID %d\n", __func__, + plat->periph_id); + return -FDT_ERR_NOTFOUND; + } + + /* Use 500KHz as a suitable default */ + plat->frequency = fdtdec_get_int(blob, node, "spi-max-frequency", + 500000); + plat->deactivate_delay_us = fdtdec_get_int(blob, node, + "spi-deactivate-delay", 0); + debug("%s: regs=%p, periph_id=%d, max-frequency=%d, deactivate_delay=%d\n", + __func__, plat->regs, plat->periph_id, plat->frequency, + plat->deactivate_delay_us); + + return 0; + } + + +Add the platform data [non-device-tree only] +-------------------------------------------- + +Specify this data in a U_BOOT_DEVICE() declaration in your board file: + +.. code-block:: c + + struct exynos_spi_platdata platdata_spi0 = { + .periph_id = ... + .frequency = ... + .regs = ... + .deactivate_delay_us = ... + }; + + U_BOOT_DEVICE(board_spi0) = { + .name = "exynos_spi", + .platdata = &platdata_spi0, + }; + +You will unfortunately need to put the struct definition into a header file +in this case so that your board file can use it. + + +Add the device private data +--------------------------- + +Most devices have some private data which they use to keep track of things +while active. This is the run-time information and needs to be stored in +a structure. There is probably a structure in the driver that includes a +'struct spi_slave', so you can use that. + +.. code-block:: c + + struct exynos_spi_slave { + struct spi_slave slave; + struct exynos_spi *regs; + unsigned int freq; /* Default frequency */ + unsigned int mode; + enum periph_id periph_id; /* Peripheral ID for this device */ + unsigned int fifo_size; + int skip_preamble; + struct spi_bus *bus; /* Pointer to our SPI bus info */ + ulong last_transaction_us; /* Time of last transaction end */ + }; + + +We should rename this to make its purpose more obvious, and get rid of +the slave structure, so we have: + +.. code-block:: c + + struct exynos_spi_priv { + struct exynos_spi *regs; + unsigned int freq; /* Default frequency */ + unsigned int mode; + enum periph_id periph_id; /* Peripheral ID for this device */ + unsigned int fifo_size; + int skip_preamble; + ulong last_transaction_us; /* Time of last transaction end */ + }; + + +DM can auto-allocate this also: + +.. code-block:: c + + U_BOOT_DRIVER(spi_exynos) = { + ... + .priv_auto_alloc_size = sizeof(struct exynos_spi_priv), + + +Note that this is created before the probe method is called, and destroyed +after the remove method is called. It will be zeroed when the probe +method is called. + + +Add the probe() and remove() methods +------------------------------------ + +Note: It's a good idea to build repeatedly as you are working, to avoid a +huge amount of work getting things compiling at the end. + +The probe method is supposed to set up the hardware. U-Boot used to use +spi_setup_slave() to do this. So take a look at this function and see +what you can copy out to set things up. + +.. code-block:: c + + static int exynos_spi_probe(struct udevice *bus) + { + struct exynos_spi_platdata *plat = dev_get_platdata(bus); + struct exynos_spi_priv *priv = dev_get_priv(bus); + + priv->regs = plat->regs; + if (plat->periph_id == PERIPH_ID_SPI1 || + plat->periph_id == PERIPH_ID_SPI2) + priv->fifo_size = 64; + else + priv->fifo_size = 256; + + priv->skip_preamble = 0; + priv->last_transaction_us = timer_get_us(); + priv->freq = plat->frequency; + priv->periph_id = plat->periph_id; + + return 0; + } + +This implementation doesn't actually touch the hardware, which is somewhat +unusual for a driver. In this case we will do that when the device is +claimed by something that wants to use the SPI bus. + +For remove we could shut down the clocks, but in this case there is +nothing to do. DM frees any memory that it allocated, so we can just +remove exynos_spi_remove() and its reference in U_BOOT_DRIVER. + + +Implement set_speed() +--------------------- + +This should set up clocks so that the SPI bus is running at the right +speed. With the old API spi_claim_bus() would normally do this and several +of the following functions, so let's look at that function: + +.. code-block:: c + + int spi_claim_bus(struct spi_slave *slave) + { + struct exynos_spi_slave *spi_slave = to_exynos_spi(slave); + struct exynos_spi *regs = spi_slave->regs; + u32 reg = 0; + int ret; + + ret = set_spi_clk(spi_slave->periph_id, + spi_slave->freq); + if (ret < 0) { + debug("%s: Failed to setup spi clock\n", __func__); + return ret; + } + + exynos_pinmux_config(spi_slave->periph_id, PINMUX_FLAG_NONE); + + spi_flush_fifo(slave); + + reg = readl(®s->ch_cfg); + reg &= ~(SPI_CH_CPHA_B | SPI_CH_CPOL_L); + + if (spi_slave->mode & SPI_CPHA) + reg |= SPI_CH_CPHA_B; + + if (spi_slave->mode & SPI_CPOL) + reg |= SPI_CH_CPOL_L; + + writel(reg, ®s->ch_cfg); + writel(SPI_FB_DELAY_180, ®s->fb_clk); + + return 0; + } + + +It sets up the speed, mode, pinmux, feedback delay and clears the FIFOs. +With DM these will happen in separate methods. + + +Here is an example for the speed part: + +.. code-block:: c + + static int exynos_spi_set_speed(struct udevice *bus, uint speed) + { + struct exynos_spi_platdata *plat = bus->platdata; + struct exynos_spi_priv *priv = dev_get_priv(bus); + int ret; + + if (speed > plat->frequency) + speed = plat->frequency; + ret = set_spi_clk(priv->periph_id, speed); + if (ret) + return ret; + priv->freq = speed; + debug("%s: regs=%p, speed=%d\n", __func__, priv->regs, priv->freq); + + return 0; + } + + +Implement set_mode() +-------------------- + +This should adjust the SPI mode (polarity, etc.). Again this code probably +comes from the old spi_claim_bus(). Here is an example: + +.. code-block:: c + + static int exynos_spi_set_mode(struct udevice *bus, uint mode) + { + struct exynos_spi_priv *priv = dev_get_priv(bus); + uint32_t reg; + + reg = readl(&priv->regs->ch_cfg); + reg &= ~(SPI_CH_CPHA_B | SPI_CH_CPOL_L); + + if (mode & SPI_CPHA) + reg |= SPI_CH_CPHA_B; + + if (mode & SPI_CPOL) + reg |= SPI_CH_CPOL_L; + + writel(reg, &priv->regs->ch_cfg); + priv->mode = mode; + debug("%s: regs=%p, mode=%d\n", __func__, priv->regs, priv->mode); + + return 0; + } + + +Implement claim_bus() +--------------------- + +This is where a client wants to make use of the bus, so claims it first. +At this point we need to make sure everything is set up ready for data +transfer. Note that this function is wholly internal to the driver - at +present the SPI uclass never calls it. + +Here again we look at the old claim function and see some code that is +needed. It is anything unrelated to speed and mode: + +.. code-block:: c + + static int exynos_spi_claim_bus(struct udevice *bus) + { + struct exynos_spi_priv *priv = dev_get_priv(bus); + + exynos_pinmux_config(priv->periph_id, PINMUX_FLAG_NONE); + spi_flush_fifo(priv->regs); + + writel(SPI_FB_DELAY_180, &priv->regs->fb_clk); + + return 0; + } + +The spi_flush_fifo() function is in the removed part of the code, so we +need to expose it again (perhaps with an #endif before it and '#if 0' +after it). It only needs access to priv->regs which is why we have +passed that in: + +.. code-block:: c + + /** + * Flush spi tx, rx fifos and reset the SPI controller + * + * @param regs Pointer to SPI registers + */ + static void spi_flush_fifo(struct exynos_spi *regs) + { + clrsetbits_le32(®s->ch_cfg, SPI_CH_HS_EN, SPI_CH_RST); + clrbits_le32(®s->ch_cfg, SPI_CH_RST); + setbits_le32(®s->ch_cfg, SPI_TX_CH_ON | SPI_RX_CH_ON); + } + + +Implement release_bus() +----------------------- + +This releases the bus - in our example the old code in spi_release_bus() +is a call to spi_flush_fifo, so we add: + +.. code-block:: c + + static int exynos_spi_release_bus(struct udevice *bus) + { + struct exynos_spi_priv *priv = dev_get_priv(bus); + + spi_flush_fifo(priv->regs); + + return 0; + } + + +Implement xfer() +---------------- + +This is the final method that we need to create, and it is where all the +work happens. The method parameters are the same as the old spi_xfer() with +the addition of a 'struct udevice' so conversion is pretty easy. Start +by copying the contents of spi_xfer() to your new xfer() method and proceed +from there. + +If (flags & SPI_XFER_BEGIN) is non-zero then xfer() normally calls an +activate function, something like this: + +.. code-block:: c + + void spi_cs_activate(struct spi_slave *slave) + { + struct exynos_spi_slave *spi_slave = to_exynos_spi(slave); + + /* If it's too soon to do another transaction, wait */ + if (spi_slave->bus->deactivate_delay_us && + spi_slave->last_transaction_us) { + ulong delay_us; /* The delay completed so far */ + delay_us = timer_get_us() - spi_slave->last_transaction_us; + if (delay_us < spi_slave->bus->deactivate_delay_us) + udelay(spi_slave->bus->deactivate_delay_us - delay_us); + } + + clrbits_le32(&spi_slave->regs->cs_reg, SPI_SLAVE_SIG_INACT); + debug("Activate CS, bus %d\n", spi_slave->slave.bus); + spi_slave->skip_preamble = spi_slave->mode & SPI_PREAMBLE; + } + +The new version looks like this: + +.. code-block:: c + + static void spi_cs_activate(struct udevice *dev) + { + struct udevice *bus = dev->parent; + struct exynos_spi_platdata *pdata = dev_get_platdata(bus); + struct exynos_spi_priv *priv = dev_get_priv(bus); + + /* If it's too soon to do another transaction, wait */ + if (pdata->deactivate_delay_us && + priv->last_transaction_us) { + ulong delay_us; /* The delay completed so far */ + delay_us = timer_get_us() - priv->last_transaction_us; + if (delay_us < pdata->deactivate_delay_us) + udelay(pdata->deactivate_delay_us - delay_us); + } + + clrbits_le32(&priv->regs->cs_reg, SPI_SLAVE_SIG_INACT); + debug("Activate CS, bus '%s'\n", bus->name); + priv->skip_preamble = priv->mode & SPI_PREAMBLE; + } + +All we have really done here is change the pointers and print the device name +instead of the bus number. Other local static functions can be treated in +the same way. + + +Set up the per-child data and child pre-probe function +------------------------------------------------------ + +To minimise the pain and complexity of the SPI subsystem while the driver +model change-over is in place, struct spi_slave is used to reference a +SPI bus slave, even though that slave is actually a struct udevice. In fact +struct spi_slave is the device's child data. We need to make sure this space +is available. It is possible to allocate more space that struct spi_slave +needs, but this is the minimum. + +.. code-block:: c + + U_BOOT_DRIVER(exynos_spi) = { + ... + .per_child_auto_alloc_size = sizeof(struct spi_slave), + } + + +Optional: Set up cs_info() if you want it +----------------------------------------- + +Sometimes it is useful to know whether a SPI chip select is valid, but this +is not obvious from outside the driver. In this case you can provide a +method for cs_info() to deal with this. If you don't provide it, then the +device tree will be used to determine what chip selects are valid. + +Return -ENODEV if the supplied chip select is invalid, or 0 if it is valid. +If you don't provide the cs_info() method, -ENODEV is assumed for all +chip selects that do not appear in the device tree. + + +Test it +------- + +Now that you have the code written and it compiles, try testing it using +the 'sf test' command. You may need to enable CONFIG_CMD_SF_TEST for your +board. + + +Prepare patches and send them to the mailing lists +-------------------------------------------------- + +You can use 'tools/patman/patman' to prepare, check and send patches for +your work. See the README for details. + +A little note about SPI uclass features +--------------------------------------- + +The SPI uclass keeps some information about each device 'dev' on the bus: + + struct dm_spi_slave_platdata: + This is device_get_parent_platdata(dev). + This is where the chip select number is stored, along with + the default bus speed and mode. It is automatically read + from the device tree in spi_child_post_bind(). It must not + be changed at run-time after being set up because platform + data is supposed to be immutable at run-time. + struct spi_slave: + This is device_get_parentdata(dev). + Already mentioned above. It holds run-time information about + the device. + +There are also some SPI uclass methods that get called behind the scenes: + + spi_post_bind(): + Called when a new bus is bound. + This scans the device tree for devices on the bus, and binds + each one. This in turn causes spi_child_post_bind() to be + called for each, which reads the device tree information + into the parent (per-child) platform data. + spi_child_post_bind(): + Called when a new child is bound. + As mentioned above this reads the device tree information + into the per-child platform data + spi_child_pre_probe(): + Called before a new child is probed. + This sets up the mode and speed in struct spi_slave by + copying it from the parent's platform data for this child. + It also sets the 'dev' pointer, needed to permit passing + 'struct spi_slave' around the place without needing a + separate 'struct udevice' pointer. + +The above housekeeping makes it easier to write your SPI driver. diff --git a/doc/driver-model/spi-howto.txt b/doc/driver-model/spi-howto.txt deleted file mode 100644 index 38c26f642b..0000000000 --- a/doc/driver-model/spi-howto.txt +++ /dev/null @@ -1,623 +0,0 @@ -How to port a SPI driver to driver model -======================================== - -Here is a rough step-by-step guide. It is based around converting the -exynos SPI driver to driver model (DM) and the example code is based -around U-Boot v2014.10-rc2 (commit be9f643). This has been updated for -v2015.04. - -It is quite long since it includes actual code examples. - -Before driver model, SPI drivers have their own private structure which -contains 'struct spi_slave'. With driver model, 'struct spi_slave' still -exists, but now it is 'per-child data' for the SPI bus. Each child of the -SPI bus is a SPI slave. The information that was stored in the -driver-specific slave structure can now be port in private data for the -SPI bus. - -For example, struct tegra_spi_slave looks like this: - -struct tegra_spi_slave { - struct spi_slave slave; - struct tegra_spi_ctrl *ctrl; -}; - -In this case 'slave' will be in per-child data, and 'ctrl' will be in the -SPI's buses private data. - - -0. How long does this take? - -You should be able to complete this within 2 hours, including testing but -excluding preparing the patches. The API is basically the same as before -with only minor changes: - -- methods to set speed and mode are separated out -- cs_info is used to get information on a chip select - - -1. Enable driver mode for SPI and SPI flash - -Add these to your board config: - -CONFIG_DM_SPI -CONFIG_DM_SPI_FLASH - - -2. Add the skeleton - -Put this code at the bottom of your existing driver file: - -struct spi_slave *spi_setup_slave(unsigned int busnum, unsigned int cs, - unsigned int max_hz, unsigned int mode) -{ - return NULL; -} - -struct spi_slave *spi_setup_slave_fdt(const void *blob, int slave_node, - int spi_node) -{ - return NULL; -} - -static int exynos_spi_ofdata_to_platdata(struct udevice *dev) -{ - return -ENODEV; -} - -static int exynos_spi_probe(struct udevice *dev) -{ - return -ENODEV; -} - -static int exynos_spi_remove(struct udevice *dev) -{ - return -ENODEV; -} - -static int exynos_spi_claim_bus(struct udevice *dev) -{ - - return -ENODEV; -} - -static int exynos_spi_release_bus(struct udevice *dev) -{ - - return -ENODEV; -} - -static int exynos_spi_xfer(struct udevice *dev, unsigned int bitlen, - const void *dout, void *din, unsigned long flags) -{ - - return -ENODEV; -} - -static int exynos_spi_set_speed(struct udevice *dev, uint speed) -{ - return -ENODEV; -} - -static int exynos_spi_set_mode(struct udevice *dev, uint mode) -{ - return -ENODEV; -} - -static int exynos_cs_info(struct udevice *bus, uint cs, - struct spi_cs_info *info) -{ - return -ENODEV; -} - -static const struct dm_spi_ops exynos_spi_ops = { - .claim_bus = exynos_spi_claim_bus, - .release_bus = exynos_spi_release_bus, - .xfer = exynos_spi_xfer, - .set_speed = exynos_spi_set_speed, - .set_mode = exynos_spi_set_mode, - .cs_info = exynos_cs_info, -}; - -static const struct udevice_id exynos_spi_ids[] = { - { .compatible = "samsung,exynos-spi" }, - { } -}; - -U_BOOT_DRIVER(exynos_spi) = { - .name = "exynos_spi", - .id = UCLASS_SPI, - .of_match = exynos_spi_ids, - .ops = &exynos_spi_ops, - .ofdata_to_platdata = exynos_spi_ofdata_to_platdata, - .probe = exynos_spi_probe, - .remove = exynos_spi_remove, -}; - - -3. Replace 'exynos' in the above code with your driver name - - -4. #ifdef out all of the code in your driver except for the above - -This will allow you to get it building, which means you can work -incrementally. Since all the methods return an error initially, there is -less chance that you will accidentally leave something in. - -Also, even though your conversion is basically a rewrite, it might help -reviewers if you leave functions in the same place in the file, -particularly for large drivers. - - -5. Add some includes - -Add these includes to your driver: - -#include <dm.h> -#include <errno.h> - - -6. Build - -At this point you should be able to build U-Boot for your board with the -empty SPI driver. You still have empty methods in your driver, but we will -write these one by one. - -7. Set up your platform data structure - -This will hold the information your driver to operate, like its hardware -address or maximum frequency. - -You may already have a struct like this, or you may need to create one -from some of the #defines or global variables in the driver. - -Note that this information is not the run-time information. It should not -include state that changes. It should be fixed throughout the live of -U-Boot. Run-time information comes later. - -Here is what was in the exynos spi driver: - -struct spi_bus { - enum periph_id periph_id; - s32 frequency; /* Default clock frequency, -1 for none */ - struct exynos_spi *regs; - int inited; /* 1 if this bus is ready for use */ - int node; - uint deactivate_delay_us; /* Delay to wait after deactivate */ -}; - -Of these, inited is handled by DM and node is the device tree node, which -DM tells you. The name is not quite right. So in this case we would use: - -struct exynos_spi_platdata { - enum periph_id periph_id; - s32 frequency; /* Default clock frequency, -1 for none */ - struct exynos_spi *regs; - uint deactivate_delay_us; /* Delay to wait after deactivate */ -}; - - -8a. Write ofdata_to_platdata() [for device tree only] - -This method will convert information in the device tree node into a C -structure in your driver (called platform data). If you are not using -device tree, go to 8b. - -DM will automatically allocate the struct for us when we are using device -tree, but we need to tell it the size: - -U_BOOT_DRIVER(spi_exynos) = { -... - .platdata_auto_alloc_size = sizeof(struct exynos_spi_platdata), - - -Here is a sample function. It gets a pointer to the platform data and -fills in the fields from device tree. - -static int exynos_spi_ofdata_to_platdata(struct udevice *bus) -{ - struct exynos_spi_platdata *plat = bus->platdata; - const void *blob = gd->fdt_blob; - int node = dev_of_offset(bus); - - plat->regs = (struct exynos_spi *)fdtdec_get_addr(blob, node, "reg"); - plat->periph_id = pinmux_decode_periph_id(blob, node); - - if (plat->periph_id == PERIPH_ID_NONE) { - debug("%s: Invalid peripheral ID %d\n", __func__, - plat->periph_id); - return -FDT_ERR_NOTFOUND; - } - - /* Use 500KHz as a suitable default */ - plat->frequency = fdtdec_get_int(blob, node, "spi-max-frequency", - 500000); - plat->deactivate_delay_us = fdtdec_get_int(blob, node, - "spi-deactivate-delay", 0); - debug("%s: regs=%p, periph_id=%d, max-frequency=%d, deactivate_delay=%d\n", - __func__, plat->regs, plat->periph_id, plat->frequency, - plat->deactivate_delay_us); - - return 0; -} - - -8b. Add the platform data [non-device-tree only] - -Specify this data in a U_BOOT_DEVICE() declaration in your board file: - -struct exynos_spi_platdata platdata_spi0 = { - .periph_id = ... - .frequency = ... - .regs = ... - .deactivate_delay_us = ... -}; - -U_BOOT_DEVICE(board_spi0) = { - .name = "exynos_spi", - .platdata = &platdata_spi0, -}; - -You will unfortunately need to put the struct definition into a header file -in this case so that your board file can use it. - - -9. Add the device private data - -Most devices have some private data which they use to keep track of things -while active. This is the run-time information and needs to be stored in -a structure. There is probably a structure in the driver that includes a -'struct spi_slave', so you can use that. - -struct exynos_spi_slave { - struct spi_slave slave; - struct exynos_spi *regs; - unsigned int freq; /* Default frequency */ - unsigned int mode; - enum periph_id periph_id; /* Peripheral ID for this device */ - unsigned int fifo_size; - int skip_preamble; - struct spi_bus *bus; /* Pointer to our SPI bus info */ - ulong last_transaction_us; /* Time of last transaction end */ -}; - - -We should rename this to make its purpose more obvious, and get rid of -the slave structure, so we have: - -struct exynos_spi_priv { - struct exynos_spi *regs; - unsigned int freq; /* Default frequency */ - unsigned int mode; - enum periph_id periph_id; /* Peripheral ID for this device */ - unsigned int fifo_size; - int skip_preamble; - ulong last_transaction_us; /* Time of last transaction end */ -}; - - -DM can auto-allocate this also: - -U_BOOT_DRIVER(spi_exynos) = { -... - .priv_auto_alloc_size = sizeof(struct exynos_spi_priv), - - -Note that this is created before the probe method is called, and destroyed -after the remove method is called. It will be zeroed when the probe -method is called. - - -10. Add the probe() and remove() methods - -Note: It's a good idea to build repeatedly as you are working, to avoid a -huge amount of work getting things compiling at the end. - -The probe method is supposed to set up the hardware. U-Boot used to use -spi_setup_slave() to do this. So take a look at this function and see -what you can copy out to set things up. - - -static int exynos_spi_probe(struct udevice *bus) -{ - struct exynos_spi_platdata *plat = dev_get_platdata(bus); - struct exynos_spi_priv *priv = dev_get_priv(bus); - - priv->regs = plat->regs; - if (plat->periph_id == PERIPH_ID_SPI1 || - plat->periph_id == PERIPH_ID_SPI2) - priv->fifo_size = 64; - else - priv->fifo_size = 256; - - priv->skip_preamble = 0; - priv->last_transaction_us = timer_get_us(); - priv->freq = plat->frequency; - priv->periph_id = plat->periph_id; - - return 0; -} - -This implementation doesn't actually touch the hardware, which is somewhat -unusual for a driver. In this case we will do that when the device is -claimed by something that wants to use the SPI bus. - -For remove we could shut down the clocks, but in this case there is -nothing to do. DM frees any memory that it allocated, so we can just -remove exynos_spi_remove() and its reference in U_BOOT_DRIVER. - - -11. Implement set_speed() - -This should set up clocks so that the SPI bus is running at the right -speed. With the old API spi_claim_bus() would normally do this and several -of the following functions, so let's look at that function: - -int spi_claim_bus(struct spi_slave *slave) -{ - struct exynos_spi_slave *spi_slave = to_exynos_spi(slave); - struct exynos_spi *regs = spi_slave->regs; - u32 reg = 0; - int ret; - - ret = set_spi_clk(spi_slave->periph_id, - spi_slave->freq); - if (ret < 0) { - debug("%s: Failed to setup spi clock\n", __func__); - return ret; - } - - exynos_pinmux_config(spi_slave->periph_id, PINMUX_FLAG_NONE); - - spi_flush_fifo(slave); - - reg = readl(®s->ch_cfg); - reg &= ~(SPI_CH_CPHA_B | SPI_CH_CPOL_L); - - if (spi_slave->mode & SPI_CPHA) - reg |= SPI_CH_CPHA_B; - - if (spi_slave->mode & SPI_CPOL) - reg |= SPI_CH_CPOL_L; - - writel(reg, ®s->ch_cfg); - writel(SPI_FB_DELAY_180, ®s->fb_clk); - - return 0; -} - - -It sets up the speed, mode, pinmux, feedback delay and clears the FIFOs. -With DM these will happen in separate methods. - - -Here is an example for the speed part: - -static int exynos_spi_set_speed(struct udevice *bus, uint speed) -{ - struct exynos_spi_platdata *plat = bus->platdata; - struct exynos_spi_priv *priv = dev_get_priv(bus); - int ret; - - if (speed > plat->frequency) - speed = plat->frequency; - ret = set_spi_clk(priv->periph_id, speed); - if (ret) - return ret; - priv->freq = speed; - debug("%s: regs=%p, speed=%d\n", __func__, priv->regs, priv->freq); - - return 0; -} - - -12. Implement set_mode() - -This should adjust the SPI mode (polarity, etc.). Again this code probably -comes from the old spi_claim_bus(). Here is an example: - - -static int exynos_spi_set_mode(struct udevice *bus, uint mode) -{ - struct exynos_spi_priv *priv = dev_get_priv(bus); - uint32_t reg; - - reg = readl(&priv->regs->ch_cfg); - reg &= ~(SPI_CH_CPHA_B | SPI_CH_CPOL_L); - - if (mode & SPI_CPHA) - reg |= SPI_CH_CPHA_B; - - if (mode & SPI_CPOL) - reg |= SPI_CH_CPOL_L; - - writel(reg, &priv->regs->ch_cfg); - priv->mode = mode; - debug("%s: regs=%p, mode=%d\n", __func__, priv->regs, priv->mode); - - return 0; -} - - -13. Implement claim_bus() - -This is where a client wants to make use of the bus, so claims it first. -At this point we need to make sure everything is set up ready for data -transfer. Note that this function is wholly internal to the driver - at -present the SPI uclass never calls it. - -Here again we look at the old claim function and see some code that is -needed. It is anything unrelated to speed and mode: - -static int exynos_spi_claim_bus(struct udevice *bus) -{ - struct exynos_spi_priv *priv = dev_get_priv(bus); - - exynos_pinmux_config(priv->periph_id, PINMUX_FLAG_NONE); - spi_flush_fifo(priv->regs); - - writel(SPI_FB_DELAY_180, &priv->regs->fb_clk); - - return 0; -} - -The spi_flush_fifo() function is in the removed part of the code, so we -need to expose it again (perhaps with an #endif before it and '#if 0' -after it). It only needs access to priv->regs which is why we have -passed that in: - -/** - * Flush spi tx, rx fifos and reset the SPI controller - * - * @param regs Pointer to SPI registers - */ -static void spi_flush_fifo(struct exynos_spi *regs) -{ - clrsetbits_le32(®s->ch_cfg, SPI_CH_HS_EN, SPI_CH_RST); - clrbits_le32(®s->ch_cfg, SPI_CH_RST); - setbits_le32(®s->ch_cfg, SPI_TX_CH_ON | SPI_RX_CH_ON); -} - - -14. Implement release_bus() - -This releases the bus - in our example the old code in spi_release_bus() -is a call to spi_flush_fifo, so we add: - -static int exynos_spi_release_bus(struct udevice *bus) -{ - struct exynos_spi_priv *priv = dev_get_priv(bus); - - spi_flush_fifo(priv->regs); - - return 0; -} - - -15. Implement xfer() - -This is the final method that we need to create, and it is where all the -work happens. The method parameters are the same as the old spi_xfer() with -the addition of a 'struct udevice' so conversion is pretty easy. Start -by copying the contents of spi_xfer() to your new xfer() method and proceed -from there. - -If (flags & SPI_XFER_BEGIN) is non-zero then xfer() normally calls an -activate function, something like this: - -void spi_cs_activate(struct spi_slave *slave) -{ - struct exynos_spi_slave *spi_slave = to_exynos_spi(slave); - - /* If it's too soon to do another transaction, wait */ - if (spi_slave->bus->deactivate_delay_us && - spi_slave->last_transaction_us) { - ulong delay_us; /* The delay completed so far */ - delay_us = timer_get_us() - spi_slave->last_transaction_us; - if (delay_us < spi_slave->bus->deactivate_delay_us) - udelay(spi_slave->bus->deactivate_delay_us - delay_us); - } - - clrbits_le32(&spi_slave->regs->cs_reg, SPI_SLAVE_SIG_INACT); - debug("Activate CS, bus %d\n", spi_slave->slave.bus); - spi_slave->skip_preamble = spi_slave->mode & SPI_PREAMBLE; -} - -The new version looks like this: - -static void spi_cs_activate(struct udevice *dev) -{ - struct udevice *bus = dev->parent; - struct exynos_spi_platdata *pdata = dev_get_platdata(bus); - struct exynos_spi_priv *priv = dev_get_priv(bus); - - /* If it's too soon to do another transaction, wait */ - if (pdata->deactivate_delay_us && - priv->last_transaction_us) { - ulong delay_us; /* The delay completed so far */ - delay_us = timer_get_us() - priv->last_transaction_us; - if (delay_us < pdata->deactivate_delay_us) - udelay(pdata->deactivate_delay_us - delay_us); - } - - clrbits_le32(&priv->regs->cs_reg, SPI_SLAVE_SIG_INACT); - debug("Activate CS, bus '%s'\n", bus->name); - priv->skip_preamble = priv->mode & SPI_PREAMBLE; -} - -All we have really done here is change the pointers and print the device name -instead of the bus number. Other local static functions can be treated in -the same way. - - -16. Set up the per-child data and child pre-probe function - -To minimise the pain and complexity of the SPI subsystem while the driver -model change-over is in place, struct spi_slave is used to reference a -SPI bus slave, even though that slave is actually a struct udevice. In fact -struct spi_slave is the device's child data. We need to make sure this space -is available. It is possible to allocate more space that struct spi_slave -needs, but this is the minimum. - -U_BOOT_DRIVER(exynos_spi) = { -... - .per_child_auto_alloc_size = sizeof(struct spi_slave), -} - - -17. Optional: Set up cs_info() if you want it - -Sometimes it is useful to know whether a SPI chip select is valid, but this -is not obvious from outside the driver. In this case you can provide a -method for cs_info() to deal with this. If you don't provide it, then the -device tree will be used to determine what chip selects are valid. - -Return -ENODEV if the supplied chip select is invalid, or 0 if it is valid. -If you don't provide the cs_info() method, -ENODEV is assumed for all -chip selects that do not appear in the device tree. - - -18. Test it - -Now that you have the code written and it compiles, try testing it using -the 'sf test' command. You may need to enable CONFIG_CMD_SF_TEST for your -board. - - -19. Prepare patches and send them to the mailing lists - -You can use 'tools/patman/patman' to prepare, check and send patches for -your work. See the README for details. - -20. A little note about SPI uclass features: - -The SPI uclass keeps some information about each device 'dev' on the bus: - - struct dm_spi_slave_platdata - this is device_get_parent_platdata(dev) - This is where the chip select number is stored, along with - the default bus speed and mode. It is automatically read - from the device tree in spi_child_post_bind(). It must not - be changed at run-time after being set up because platform - data is supposed to be immutable at run-time. - struct spi_slave - this is device_get_parentdata(dev) - Already mentioned above. It holds run-time information about - the device. - -There are also some SPI uclass methods that get called behind the scenes: - - spi_post_bind() - called when a new bus is bound - This scans the device tree for devices on the bus, and binds - each one. This in turn causes spi_child_post_bind() to be - called for each, which reads the device tree information - into the parent (per-child) platform data. - spi_child_post_bind() - called when a new child is bound - As mentioned above this reads the device tree information - into the per-child platform data - spi_child_pre_probe() - called before a new child is probed - This sets up the mode and speed in struct spi_slave by - copying it from the parent's platform data for this child. - It also sets the 'dev' pointer, needed to permit passing - 'struct spi_slave' around the place without needing a - separate 'struct udevice' pointer. - -The above housekeeping makes it easier to write your SPI driver. diff --git a/doc/driver-model/usb-info.txt b/doc/driver-model/usb-info.rst index e07e5ba261..1817df420f 100644 --- a/doc/driver-model/usb-info.txt +++ b/doc/driver-model/usb-info.rst @@ -1,3 +1,5 @@ +.. SPDX-License-Identifier: GPL-2.0+ + How USB works with driver model =============================== @@ -24,25 +26,27 @@ 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: -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, - .ofdata_to_platdata = ehci_usb_ofdata_to_platdata, - .probe = tegra_ehci_usb_probe, - .remove = tegra_ehci_usb_remove, - .ops = &ehci_usb_ops, - .platdata_auto_alloc_size = sizeof(struct usb_platdata), - .priv_auto_alloc_size = sizeof(struct fdt_usb), - .flags = DM_FLAG_ALLOC_PRIV_DMA, -}; +.. 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, + .ofdata_to_platdata = ehci_usb_ofdata_to_platdata, + .probe = tegra_ehci_usb_probe, + .remove = tegra_ehci_usb_remove, + .ops = &ehci_usb_ops, + .platdata_auto_alloc_size = sizeof(struct usb_platdata), + .priv_auto_alloc_size = 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. @@ -80,7 +84,7 @@ Data structures The following primary data structures are in use: -- struct usb_device +- 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 @@ -89,19 +93,19 @@ The following primary data structures are in use: handles that). Once the device is set up, you can find the device descriptor and current configuration descriptor in this structure. -- struct usb_platdata +- struct usb_platdata: 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_platdata +- struct usb_dev_platdata: This holds platform data for a device. You can access it for a device 'dev' with dev_get_parent_platdata(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 +- 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. @@ -197,49 +201,49 @@ Device initialisation happens roughly like this: - 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 + (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(), 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 + 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 + 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 + 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() 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. + 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. + 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 + 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. + 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 + 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 + 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 + 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. + 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), @@ -250,25 +254,25 @@ 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() + 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. + 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) + 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 + 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 + 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 @@ -279,9 +283,9 @@ 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)) + 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 + devices Example - Mass Storage @@ -290,20 +294,22 @@ 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: -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, -}; +.. code-block:: c -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 */ -}; + 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); + 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 @@ -347,6 +353,8 @@ 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 { @@ -369,13 +377,13 @@ 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: +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 + 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 @@ -393,12 +401,12 @@ 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 + 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). + 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. @@ -410,6 +418,6 @@ Other things that need doing: - Implement USB PHYs in driver model - Work out a clever way to provide lazy init for USB devices --- -Simon Glass <sjg@chromium.org> -23-Mar-15 + +.. Simon Glass <sjg@chromium.org> +.. 23-Mar-15 |