diff options
Diffstat (limited to 'roms/u-boot/doc')
691 files changed, 72501 insertions, 0 deletions
diff --git a/roms/u-boot/doc/.gitignore b/roms/u-boot/doc/.gitignore new file mode 100644 index 000000000..53752db25 --- /dev/null +++ b/roms/u-boot/doc/.gitignore @@ -0,0 +1 @@ +output diff --git a/roms/u-boot/doc/I2C_Edge_Conditions b/roms/u-boot/doc/I2C_Edge_Conditions new file mode 100644 index 000000000..f4a996870 --- /dev/null +++ b/roms/u-boot/doc/I2C_Edge_Conditions @@ -0,0 +1,46 @@ +I2C Edge Conditions: +==================== + + I2C devices may be left in a write state if a read was occuring + and the CPU was reset. This may result in EEPROM data corruption. + + The edge condition is as follows: + 1) A read operation begins. + 2) I2C controller issues a start command. + 3) The I2C writes the device address. + 4) The CPU is reset at this point. + + Once the CPU reinitializes and the read is tried again: + 1) The I2C controller issues a start command. + 2) The I2C controller writes the device address. + 3) The I2C controller writes the offset. + + The EEPROM sees: + 1) START + 2) device address + 3) START "this start is ignored by most EEPROMs" + 4) device address "EEPROM interprets this as offset" + 5) Offset in device, "EEPROM interprets this as data to write" + + The device will interpret this sequence as a WRITE command and + write rubbish into itself, i.e. the "offset" will be interpreted + as data to be written in location "device address". + +Notes +----- +!!!THIS IS AN UNDOCUMENTED I2C BUS BUG, NOT A AMCC 4xx BUG!!! + +This reset edge condition could possibly be present in every I2C +controller and device available. For boards where a I2C bus reset +function can be implemented a i2c_init_board() function should be +provided and enabled by #define'ing CONFIG_SYS_I2C_INIT_BOARD in your +board's config file. Note that this is NOT necessary when using the +bit-banging I2C driver (common/soft_i2c.c) as this already includes +the I2C bus reset sequence. + + +Many thanks to Bill Hunter for finding this serious BUG. +email to: <williamhunter@attbi.com> + +Erik Theisen <etheisen@mindspring.com> +Tue, 5 Mar 2002 23:02:19 -0500 (Wed 05:02 MET) diff --git a/roms/u-boot/doc/Makefile b/roms/u-boot/doc/Makefile new file mode 100644 index 000000000..683e4b560 --- /dev/null +++ b/roms/u-boot/doc/Makefile @@ -0,0 +1,124 @@ +# -*- makefile -*- +# Makefile for Sphinx documentation +# + +subdir-y := + +# You can set these variables from the command line. +SPHINXBUILD = sphinx-build +SPHINXOPTS = +SPHINXDIRS = . +_SPHINXDIRS = $(patsubst $(srctree)/doc/%/conf.py,%,$(wildcard $(srctree)/doc/*/conf.py)) +SPHINX_CONF = conf.py +PAPER = +BUILDDIR = $(obj)/output +PDFLATEX = xelatex +LATEXOPTS = -interaction=batchmode + +# User-friendly check for sphinx-build +HAVE_SPHINX := $(shell if which $(SPHINXBUILD) >/dev/null 2>&1; then echo 1; else echo 0; fi) + +ifeq ($(HAVE_SPHINX),0) + +.DEFAULT: + $(warning The '$(SPHINXBUILD)' command was not found. Make sure you have Sphinx installed and in PATH, or set the SPHINXBUILD make variable to point to the full path of the '$(SPHINXBUILD)' executable.) + @echo + @./scripts/sphinx-pre-install + @echo " SKIP Sphinx $@ target." + +else # HAVE_SPHINX + +# User-friendly check for pdflatex +HAVE_PDFLATEX := $(shell if which $(PDFLATEX) >/dev/null 2>&1; then echo 1; else echo 0; fi) + +# Internal variables. +PAPEROPT_a4 = -D latex_paper_size=a4 +PAPEROPT_letter = -D latex_paper_size=letter +KERNELDOC = $(srctree)/scripts/kernel-doc +KERNELDOC_CONF = -D kerneldoc_srctree=$(srctree) -D kerneldoc_bin=$(KERNELDOC) +ALLSPHINXOPTS = $(KERNELDOC_CONF) $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) +# the i18n builder cannot share the environment and doctrees with the others +I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) . + +# commands; the 'cmd' from scripts/Kbuild.include is not *loopable* +loop_cmd = $(echo-cmd) $(cmd_$(1)) || exit; + +# $2 sphinx builder e.g. "html" +# $3 name of the build subfolder / e.g. "media", used as: +# * dest folder relative to $(BUILDDIR) and +# * cache folder relative to $(BUILDDIR)/.doctrees +# $4 dest subfolder e.g. "man" for man pages at media/man +# $5 reST source folder relative to $(srctree)/$(src), +# e.g. "media" for the linux-tv book-set at ./doc/media + +quiet_cmd_sphinx = SPHINX $@ --> file://$(abspath $(BUILDDIR)/$3/$4) + cmd_sphinx = $(MAKE) BUILDDIR=$(abspath $(BUILDDIR)) $(build)=doc/media $2 && \ + PYTHONDONTWRITEBYTECODE=1 \ + BUILDDIR=$(abspath $(BUILDDIR)) SPHINX_CONF=$(abspath $(srctree)/$(src)/$5/$(SPHINX_CONF)) \ + $(SPHINXBUILD) \ + -b $2 \ + -c $(abspath $(srctree)/$(src)) \ + -d $(abspath $(BUILDDIR)/.doctrees/$3) \ + -D version=$(KERNELVERSION) -D release=$(KERNELRELEASE) \ + $(ALLSPHINXOPTS) \ + $(abspath $(srctree)/$(src)/$5) \ + $(abspath $(BUILDDIR)/$3/$4) + +htmldocs: + @+$(foreach var,$(SPHINXDIRS),$(call loop_cmd,sphinx,html,$(var),,$(var))) + +linkcheckdocs: + @$(foreach var,$(SPHINXDIRS),$(call loop_cmd,sphinx,linkcheck,$(var),,$(var))) + +latexdocs: + @+$(foreach var,$(SPHINXDIRS),$(call loop_cmd,sphinx,latex,$(var),latex,$(var))) + +ifeq ($(HAVE_PDFLATEX),0) + +pdfdocs: + $(warning The '$(PDFLATEX)' command was not found. Make sure you have it installed and in PATH to produce PDF output.) + @echo " SKIP Sphinx $@ target." + +else # HAVE_PDFLATEX + +pdfdocs: latexdocs + $(foreach var,$(SPHINXDIRS), $(MAKE) PDFLATEX=$(PDFLATEX) LATEXOPTS="$(LATEXOPTS)" -C $(BUILDDIR)/$(var)/latex || exit;) + +endif # HAVE_PDFLATEX + +epubdocs: + @+$(foreach var,$(SPHINXDIRS),$(call loop_cmd,sphinx,epub,$(var),epub,$(var))) + +xmldocs: + @+$(foreach var,$(SPHINXDIRS),$(call loop_cmd,sphinx,xml,$(var),xml,$(var))) + +endif # HAVE_SPHINX + +# The following targets are independent of HAVE_SPHINX, and the rules should +# work or silently pass without Sphinx. + +refcheckdocs: + $(Q)cd $(srctree);scripts/documentation-file-ref-check + +cleandocs: + $(Q)rm -rf $(BUILDDIR) + $(Q)$(MAKE) BUILDDIR=$(abspath $(BUILDDIR)) $(build)=doc/media clean + +dochelp: + @echo ' U-Boot documentation in different formats from ReST:' + @echo ' htmldocs - HTML' + @echo ' latexdocs - LaTeX' + @echo ' pdfdocs - PDF' + @echo ' epubdocs - EPUB' + @echo ' xmldocs - XML' + @echo ' linkcheckdocs - check for broken external links (will connect to external hosts)' + @echo ' refcheckdocs - check for references to non-existing files under Documentation' + @echo ' cleandocs - clean all generated files' + @echo + @echo ' make SPHINXDIRS="s1 s2" [target] Generate only docs of folder s1, s2' + @echo ' valid values for SPHINXDIRS are: $(_SPHINXDIRS)' + @echo + @echo ' make SPHINX_CONF={conf-file} [target] use *additional* sphinx-build' + @echo ' configuration. This is e.g. useful to build with nit-picking config.' + @echo + @echo ' Default location for the generated documents is doc/output' diff --git a/roms/u-boot/doc/README.440-DDR-performance b/roms/u-boot/doc/README.440-DDR-performance new file mode 100644 index 000000000..66b97bc9b --- /dev/null +++ b/roms/u-boot/doc/README.440-DDR-performance @@ -0,0 +1,90 @@ +AMCC suggested to set the PMU bit to 0 for best performace on the +PPC440 DDR controller. The 440er common DDR setup files (sdram.c & +spd_sdram.c) are changed accordingly. So all 440er boards using +these setup routines will automatically receive this performance +increase. + +Please see below some benchmarks done by AMCC to demonstrate this +performance changes: + + +---------------------------------------- +SDRAM0_CFG0[PMU] = 1 (U-Boot default for Bamboo, Yosemite and Yellowstone) +---------------------------------------- +Stream benchmark results +------------------------------------------------------------- +This system uses 8 bytes per DOUBLE PRECISION word. +------------------------------------------------------------- +Array size = 2000000, Offset = 0 +Total memory required = 45.8 MB. +Each test is run 10 times, but only +the *best* time for each is used. +------------------------------------------------------------- +Your clock granularity/precision appears to be 1 microseconds. +Each test below will take on the order of 112345 microseconds. + (= 112345 clock ticks) +Increase the size of the arrays if this shows that you are not getting +at least 20 clock ticks per test. +------------------------------------------------------------- +WARNING -- The above is only a rough guideline. +For best results, please be sure you know the precision of your system +timer. +------------------------------------------------------------- +Function Rate (MB/s) RMS time Min time Max time +Copy: 256.7683 0.1248 0.1246 0.1250 +Scale: 246.0157 0.1302 0.1301 0.1302 +Add: 255.0316 0.1883 0.1882 0.1885 +Triad: 253.1245 0.1897 0.1896 0.1899 + + +TTCP Benchmark Results +ttcp-t: socket +ttcp-t: connect +ttcp-t: buflen=8192, nbuf=2048, align=16384/0, port=5000 tcp -> +localhost +ttcp-t: 16777216 bytes in 0.28 real seconds = 454.29 Mbit/sec +++ +ttcp-t: 2048 I/O calls, msec/call = 0.14, calls/sec = 7268.57 +ttcp-t: 0.0user 0.1sys 0:00real 60% 0i+0d 0maxrss 0+2pf 3+1506csw + +---------------------------------------- +SDRAM0_CFG0[PMU] = 0 (Suggested modification) +Setting PMU = 0 provides a noticeable performance improvement *2% to +5% improvement in memory performance. +*Improves the Mbit/sec for TTCP benchmark by almost 76%. +---------------------------------------- +Stream benchmark results +------------------------------------------------------------- +This system uses 8 bytes per DOUBLE PRECISION word. +------------------------------------------------------------- +Array size = 2000000, Offset = 0 +Total memory required = 45.8 MB. +Each test is run 10 times, but only +the *best* time for each is used. +------------------------------------------------------------- +Your clock granularity/precision appears to be 1 microseconds. +Each test below will take on the order of 120066 microseconds. + (= 120066 clock ticks) +Increase the size of the arrays if this shows that you are not getting +at least 20 clock ticks per test. +------------------------------------------------------------- +WARNING -- The above is only a rough guideline. +For best results, please be sure you know the precision of your system +timer. +------------------------------------------------------------- +Function Rate (MB/s) RMS time Min time Max time +Copy: 262.5167 0.1221 0.1219 0.1223 +Scale: 258.4856 0.1238 0.1238 0.1240 +Add: 262.5404 0.1829 0.1828 0.1831 +Triad: 266.8594 0.1800 0.1799 0.1802 + +TTCP Benchmark Results +ttcp-t: socket +ttcp-t: connect +ttcp-t: buflen=8192, nbuf=2048, align=16384/0, port=5000 tcp -> +localhost +ttcp-t: 16777216 bytes in 0.16 real seconds = 804.06 Mbit/sec +++ +ttcp-t: 2048 I/O calls, msec/call = 0.08, calls/sec = 12864.89 +ttcp-t: 0.0user 0.0sys 0:00real 46% 0i+0d 0maxrss 0+2pf 120+1csw + + +2006-07-28, Stefan Roese <sr@denx.de> diff --git a/roms/u-boot/doc/README.AMCC-eval-boards-cleanup b/roms/u-boot/doc/README.AMCC-eval-boards-cleanup new file mode 100644 index 000000000..901bd875c --- /dev/null +++ b/roms/u-boot/doc/README.AMCC-eval-boards-cleanup @@ -0,0 +1,31 @@ +--------------------------------------------------------------------- +Cleanup of AMCC eval boards (Walnut/Sycamore, Bubinga, Ebony, Ocotea) +--------------------------------------------------------------------- + +Changes to all AMCC eval boards: +-------------------------------- + +o Changed u-boot image size to 256 kBytes instead of 512 kBytes on most + boards. + +o Use 115200 baud as default console baudrate. + +o Added config option to use redundant environment in flash. This is also + the default setting. Option for environment in nvram is still available + for backward compatibility. + +o Merged board specific flash drivers to common flash driver: + board/amcc/common/flash.c + + +Sycamore/Walnut (one port supporting both eval boards): +------------------------------------------------------- + +o Cleanup to allow easier "cloning" for different (custom) boards: + + o Moved EBC configuration from board specific asm-file "init.S" + using defines in board configuration file. No board specific + asm file needed anymore. + + +August 01 2005, Stefan Roese <sr@denx.de> diff --git a/roms/u-boot/doc/README.Heterogeneous-SoCs b/roms/u-boot/doc/README.Heterogeneous-SoCs new file mode 100644 index 000000000..9da652e45 --- /dev/null +++ b/roms/u-boot/doc/README.Heterogeneous-SoCs @@ -0,0 +1,105 @@ +DSP side awareness for Freescale heterogeneous multicore chips based on +StarCore and Power Architecture +=============================================================== +powerpc/mpc85xx code ve APIs and function to get the number, +configuration and frequencies of all PowerPC cores and devices +connected to them, but it didnt have the similar code ofr HEterogeneous +SC3900/DSP cores and such devices like CPRI, MAPLE, MAPLE-ULB etc. + +Code for DSP side awareness provides such functionality for Freescale +Heterogeneous SoCs which are chasis-2 compliant like B4860 and B4420 + +As part of this feature, following changes have been made: +========================================================== + +1. Changed files: +================= +- arch/powerpc/cpu/mpc85xx/cpu.c + +Code added in this file to print the DSP cores and other device's(CPRI, +MAPLE etc) frequencies + +- arch/powerpc/cpu/mpc85xx/speed.c + +Added Defines and code to extract the frequncy information for all +required cores and devices from RCW and System frequency + +- arch/powerpc/cpu/mpc8xxx/cpu.c + +Added API to get the number of SC cores in running system and Their BIT +MASK, similar to the code written for PowerPC + +- arch/powerpc/include/asm/config_mpc85xx.h + +Added top level CONFIG to identify presence of HETEROGENUOUS clusters +in the system and CONFIGS for SC3900/DSP components + +- arch/powerpc/include/asm/processor.h +- include/common.h + +Added newly added Functions Declaration + +- include/e500.h + +Global structure updated for dsp cores and other components + +2. CONFIGs ADDED +================ + +CONFIG_HETROGENOUS_CLUSTERS - Define for checking the presence of + DSP/SC3900 core clusters + +CONFIG_SYS_FSL_NUM_CC_PLLS - Define for number of PLLs + +Though there are only 4 PLLs in B4, but in sequence of PLLs from PLL1 - +PLL5, PLL3 is Reserved(as mentioned in RM), so this define contains the +value as 5 not 4, to iterate over all PLLs while coding + +CONFIG_SYS_MAPLE - Define for MAPLE Baseband Accelerator +CONFIG_SYS_CPRI - Define for CPRI Interface +CONFIG_PPC_CLUSTER_START - Start index of ppc clusters +CONFIG_DSP_CLUSTER_START - Start index of dsp clusters + +Following are the defines for PLL's index that provide the Clocking to +CPRI, ULB and ETVE components + +CONFIG_SYS_CPRI_CLK - Define PLL index for CPRI clock +CONFIG_SYS_ULB_CLK - Define PLL index for ULB clock +CONFIG_SYS_ETVPE_CLK - Define PLL index for ETVPE clock + +3. Changes in MPC85xx_SYS_INFO Global structure +=============================================== + +DSP cores and other device's components have been added in this structure. + +freq_processor_dsp[CONFIG_MAX_DSP_CPUS] - Array to contain the DSP core's frequencies +freq_cpri - To store CPRI frequency +freq_maple - To store MAPLE frequency +freq_maple_ulb - To store MAPLE-ULB frequency +freq_maple_etvpe - To store MAPLE-eTVPE frequency + +4. U-BOOT LOGS +============== +4.1 B4860QDS board + Boot from NOR flash + +U-Boot 2014.07-00222-g70587a8-dirty (Aug 07 2014 - 13:15:47) + +CPU0: B4860E, Version: 2.0, (0x86880020) +Core: e6500, Version: 2.0, (0x80400020) Clock Configuration: + CPU0:1600 MHz, CPU1:1600 MHz, CPU2:1600 MHz, CPU3:1600 MHz, + DSP CPU0:1200 MHz, DSP CPU1:1200 MHz, DSP CPU2:1200 MHz, DSP CPU3:1200 MHz, + DSP CPU4:1200 MHz, DSP CPU5:1200 MHz, + CCB:666.667 MHz, + DDR:933.333 MHz (1866.667 MT/s data rate) (Asynchronous), IFC:166.667 MHz + CPRI:600 MHz + MAPLE:600 MHz, MAPLE-ULB:800 MHz, MAPLE-eTVPE:1000 MHz + FMAN1: 666.667 MHz + QMAN: 333.333 MHz + +CPUn - PowerPC core +DSP CPUn - SC3900 core + +Shaveta Leekha(shaveta@freescale.com) +Created August 7, 2014 +=========================================== diff --git a/roms/u-boot/doc/README.JFFS2 b/roms/u-boot/doc/README.JFFS2 new file mode 100644 index 000000000..0245da048 --- /dev/null +++ b/roms/u-boot/doc/README.JFFS2 @@ -0,0 +1,40 @@ +JFFS2 options and usage. +----------------------- + +JFFS2 in U-Boot is a read only implementation of the file system in +Linux with the same name. To use JFFS2 define CONFIG_CMD_JFFS2. + +The module adds three new commands. +fsload - load binary file from a file system image +fsinfo - print information about file systems +ls - list files in a directory +chpart - change active partition + +If you do now need the commands, you can enable the filesystem separately +with CONFIG_FS_JFFS2 and call the jffs2 functions yourself. + +If you boot from a partition which is mounted writable, and you +update your boot environment by replacing single files on that +partition, you should also define CONFIG_SYS_JFFS2_SORT_FRAGMENTS. Scanning +the JFFS2 filesystem takes *much* longer with this feature, though. +Sorting is done while inserting into the fragment list, which is +more or less a bubble sort. That algorithm is known to be O(n^2), +thus you should really consider if you can avoid it! + + +There only one way for JFFS2 to find the disk. It uses the flash_info +structure to find the start of a JFFS2 disk (called partition in the code) +and you can change where the partition is with two defines. + +CONFIG_SYS_JFFS2_FIRST_BANK + defined the first flash bank to use + +CONFIG_SYS_JFFS2_FIRST_SECTOR + defines the first sector to use +--- + +TODO. + + Remove the assumption that JFFS can dereference a pointer + into the disk. The current code do not work with memory holes + or hardware with a sliding window (PCMCIA). diff --git a/roms/u-boot/doc/README.JFFS2_NAND b/roms/u-boot/doc/README.JFFS2_NAND new file mode 100644 index 000000000..92fa0f6ea --- /dev/null +++ b/roms/u-boot/doc/README.JFFS2_NAND @@ -0,0 +1,8 @@ +JFFS2 NAND support: + +To enable, use the following #define in the board configuration file: + +#define CONFIG_JFFS2_NAND + +Configuration of partitions is similar to how this is done in U-Boot +for JFFS2 on top NOR flash. diff --git a/roms/u-boot/doc/README.LED b/roms/u-boot/doc/README.LED new file mode 100644 index 000000000..c21c9d53e --- /dev/null +++ b/roms/u-boot/doc/README.LED @@ -0,0 +1,77 @@ +Status LED +======================================== + +This README describes the status LED API. + +The API is defined by the include file include/status_led.h + +The first step is to enable CONFIG_LED_STATUS in menuconfig: +> Device Drivers > LED Support. + +If the LED support is only for specific board, enable +CONFIG_LED_STATUS_BOARD_SPECIFIC in the menuconfig. + +Status LEDS 0 to 5 are enabled by the following configurations at menuconfig: +CONFIG_STATUS_LED0, CONFIG_STATUS_LED1, ... CONFIG_STATUS_LED5 + +The following should be configured for each of the enabled LEDs: +CONFIG_STATUS_LED_BIT<n> +CONFIG_STATUS_LED_STATE<n> +CONFIG_STATUS_LED_FREQ<n> +Where <n> is an integer 1 through 5 (empty for 0). + +CONFIG_STATUS_LED_BIT is passed into the __led_* functions to identify which LED +is being acted on. As such, the value choose must be unique with with respect to +the other CONFIG_STATUS_LED_BIT's. Mapping the value to a physical LED is the +reponsiblity of the __led_* function. + +CONFIG_STATUS_LED_STATE is the initial state of the LED. It should be set to one +of these values: CONFIG_LED_STATUS_OFF or CONFIG_LED_STATUS_ON. + +CONFIG_STATUS_LED_FREQ determines the LED blink frequency. +Values range from 2 to 10. + +Some other LED macros +--------------------- + +CONFIG_STATUS_LED_BOOT is the LED to light when the board is booting. +This must be a valid LED number (0-5). + +CONFIG_STATUS_LED_RED is the red LED. It is used to signal errors. This must be +a valid LED number (0-5). Other similar color LED's macros are +CONFIG_STATUS_LED_GREEN, CONFIG_STATUS_LED_YELLOW and CONFIG_STATUS_LED_BLUE. + +General LED functions +--------------------- +The following functions should be defined: + +__led_init is called once to initialize the LED to CONFIG_STATUS_LED_STATE. +One time start up code should be placed here. + +__led_set is called to change the state of the LED. + +__led_toggle is called to toggle the current state of the LED. + +Colour LED +======================================== + +Colour LED's are at present only used by ARM. + +The functions names explain their purpose. + +coloured_LED_init +red_LED_on +red_LED_off +green_LED_on +green_LED_off +yellow_LED_on +yellow_LED_off +blue_LED_on +blue_LED_off + +These are weakly defined in arch/arm/lib/board.c to noops. Where applicable, define +these functions in the board specific source. + +TBD : Describe older board dependent macros similar to what is done for + +TBD : Describe general support via asm/status_led.h diff --git a/roms/u-boot/doc/README.OFT b/roms/u-boot/doc/README.OFT new file mode 100644 index 000000000..dd1c632bc --- /dev/null +++ b/roms/u-boot/doc/README.OFT @@ -0,0 +1,28 @@ +Open Firmware Flat Tree and usage. +---------------------------------- + +As part of the ongoing cleanup of the Linux PPC trees, the preferred +way to pass bootloader and board setup information is the open +firmware flat tree. + +Please take a look at the following email discussion for some +background. + + http://ozlabs.org/pipermail/linuxppc-dev/2005-August/019408.html + http://ozlabs.org/pipermail/linuxppc-dev/2005-August/019362.html + +The generated tree is part static and part dynamic. + +There is a static part which is compiled in with DTC and a dynamic +part which is programmatically appended. + +You'll need a fairly recent DTC tool, which is available by git at + + rsync://ozlabs.org/dtc/dtc.git + +The xxd binary dumper is needed too which I got from + + ftp://ftp.uni-erlangen.de/pub/utilities/etc/xxd-1.10.tar.gz + + +Pantelis Antoniou, 13 Oct 2005 diff --git a/roms/u-boot/doc/README.POST b/roms/u-boot/doc/README.POST new file mode 100644 index 000000000..1d1c25bdf --- /dev/null +++ b/roms/u-boot/doc/README.POST @@ -0,0 +1,732 @@ +Power-On-Self-Test support in U-Boot +------------------------------------ + +This project is to support Power-On-Self-Test (POST) in U-Boot. + +1. High-level requirements + +The key requirements for this project are as follows: + +1) The project shall develop a flexible framework for implementing + and running Power-On-Self-Test in U-Boot. This framework shall + possess the following features: + + o) Extensibility + + The framework shall allow adding/removing/replacing POST tests. + Also, standalone POST tests shall be supported. + + o) Configurability + + The framework shall allow run-time configuration of the lists + of tests running on normal/power-fail booting. + + o) Controllability + + The framework shall support manual running of the POST tests. + +2) The results of tests shall be saved so that it will be possible to + retrieve them from Linux. + +3) The following POST tests shall be developed for MPC823E-based + boards: + + o) CPU test + o) Cache test + o) Memory test + o) Ethernet test + o) Serial channels test + o) Watchdog timer test + o) RTC test + o) I2C test + o) SPI test + o) USB test + +4) The LWMON board shall be used for reference. + +2. Design + +This section details the key points of the design for the project. +The whole project can be divided into two independent tasks: +enhancing U-Boot/Linux to provide a common framework for running POST +tests and developing such tests for particular hardware. + +2.1. Hardware-independent POST layer + +A new optional module will be added to U-Boot, which will run POST +tests and collect their results at boot time. Also, U-Boot will +support running POST tests manually at any time by executing a +special command from the system console. + +The list of available POST tests will be configured at U-Boot build +time. The POST layer will allow the developer to add any custom POST +tests. All POST tests will be divided into the following groups: + + 1) Tests running on power-on booting only + + This group will contain those tests that run only once on + power-on reset (e.g. watchdog test) + + 2) Tests running on normal booting only + + This group will contain those tests that do not take much + time and can be run on the regular basis (e.g. CPU test) + + 3) Tests running in special "slow test mode" only + + This group will contain POST tests that consume much time + and cannot be run regularly (e.g. strong memory test, I2C test) + + 4) Manually executed tests + + This group will contain those tests that can be run manually. + +If necessary, some tests may belong to several groups simultaneously. +For example, SDRAM test may run in both normal and "slow test" mode. +In normal mode, SDRAM test may perform a fast superficial memory test +only, while running in slow test mode it may perform a full memory +check-up. + +Also, all tests will be discriminated by the moment they run at. +Specifically, the following groups will be singled out: + + 1) Tests running before relocating to RAM + + These tests will run immediately after initializing RAM + as to enable modifying it without taking care of its + contents. Basically, this group will contain memory tests + only. + + 2) Tests running after relocating to RAM + + These tests will run immediately before entering the main + loop as to guarantee full hardware initialization. + +The POST layer will also distinguish a special group of tests that +may cause system rebooting (e.g. watchdog test). For such tests, the +layer will automatically detect rebooting and will notify the test +about it. + +2.1.1. POST layer interfaces + +This section details the interfaces between the POST layer and the +rest of U-Boot. + +The following flags will be defined: + +#define POST_POWERON 0x01 /* test runs on power-on booting */ +#define POST_NORMAL 0x02 /* test runs on normal booting */ +#define POST_SLOWTEST 0x04 /* test is slow, enabled by key press */ +#define POST_POWERTEST 0x08 /* test runs after watchdog reset */ +#define POST_ROM 0x100 /* test runs in ROM */ +#define POST_RAM 0x200 /* test runs in RAM */ +#define POST_MANUAL 0x400 /* test can be executed manually */ +#define POST_REBOOT 0x800 /* test may cause rebooting */ +#define POST_PREREL 0x1000 /* test runs before relocation */ + +The POST layer will export the following interface routines: + + o) int post_run(struct bd_info *bd, char *name, int flags); + + This routine will run the test (or the group of tests) specified + by the name and flag arguments. More specifically, if the name + argument is not NULL, the test with this name will be performed, + otherwise all tests running in ROM/RAM (depending on the flag + argument) will be executed. This routine will be called at least + twice with name set to NULL, once from board_init_f() and once + from board_init_r(). The flags argument will also specify the + mode the test is executed in (power-on, normal, power-fail, + manual). + + o) void post_reloc(ulong offset); + + This routine will be called from board_init_r() and will + relocate the POST test table. + + o) int post_info(char *name); + + This routine will print the list of all POST tests that can be + executed manually if name is NULL, and the description of a + particular test if name is not NULL. + + o) int post_log(char *format, ...); + + This routine will be called from POST tests to log their + results. Basically, this routine will print the results to + stderr. The format of the arguments and the return value + will be identical to the printf() routine. + +Also, the following board-specific routines will be called from the +U-Boot common code: + + o) int post_hotkeys_pressed(gd_t *gd) + + This routine will scan the keyboard to detect if a magic key + combination has been pressed, or otherwise detect if the + power-on long-running tests shall be executed or not ("normal" + versus "slow" test mode). + +The list of available POST tests be kept in the post_tests array +filled at U-Boot build time. The format of entry in this array will +be as follows: + +struct post_test { + char *name; + char *cmd; + char *desc; + int flags; + int (*test)(struct bd_info *bd, int flags); +}; + + o) name + + This field will contain a short name of the test, which will be + used in logs and on listing POST tests (e.g. CPU test). + + o) cmd + + This field will keep a name for identifying the test on manual + testing (e.g. cpu). For more information, refer to section + "Command line interface". + + o) desc + + This field will contain a detailed description of the test, + which will be printed on user request. For more information, see + section "Command line interface". + + o) flags + + This field will contain a combination of the bit flags described + above, which will specify the mode the test is running in + (power-on, normal, power-fail or manual mode), the moment it + should be run at (before or after relocating to RAM), whether it + can cause system rebooting or not. + + o) test + + This field will contain a pointer to the routine that will + perform the test, which will take 2 arguments. The first + argument will be a pointer to the board info structure, while + the second will be a combination of bit flags specifying the + mode the test is running in (POST_POWERON, POST_NORMAL, + POST_SLOWTEST, POST_MANUAL) and whether the last execution of + the test caused system rebooting (POST_REBOOT). The routine will + return 0 on successful execution of the test, and 1 if the test + failed. + +The lists of the POST tests that should be run at power-on/normal/ +power-fail booting will be kept in the environment. Namely, the +following environment variables will be used: post_poweron, +powet_normal, post_slowtest. + +2.1.2. Test results + +The results of tests will be collected by the POST layer. The POST +log will have the following format: + +... +-------------------------------------------- +START <name> +<test-specific output> +[PASSED|FAILED] +-------------------------------------------- +... + +Basically, the results of tests will be printed to stderr. This +feature may be enhanced in future to spool the log to a serial line, +save it in non-volatile RAM (NVRAM), transfer it to a dedicated +storage server and etc. + +2.1.3. Integration issues + +All POST-related code will be #ifdef'ed with the CONFIG_POST macro. +This macro will be defined in the config_<board>.h file for those +boards that need POST. The CONFIG_POST macro will contain the list of +POST tests for the board. The macro will have the format of array +composed of post_test structures: + +#define CONFIG_POST \ + { + "On-board peripherals test", "board", \ + " This test performs full check-up of the " \ + "on-board hardware.", \ + POST_RAM | POST_SLOWTEST, \ + &board_post_test \ + } + +A new file, post.h, will be created in the include/ directory. This +file will contain common POST declarations and will define a set of +macros that will be reused for defining CONFIG_POST. As an example, +the following macro may be defined: + +#define POST_CACHE \ + { + "Cache test", "cache", \ + " This test verifies the CPU cache operation.", \ + POST_RAM | POST_NORMAL, \ + &cache_post_test \ + } + +A new subdirectory will be created in the U-Boot root directory. It +will contain the source code of the POST layer and most of POST +tests. Each POST test in this directory will be placed into a +separate file (it will be needed for building standalone tests). Some +POST tests (mainly those for testing peripheral devices) will be +located in the source files of the drivers for those devices. This +way will be used only if the test subtantially uses the driver. + +2.1.4. Standalone tests + +The POST framework will allow to develop and run standalone tests. A +user-space library will be developed to provide the POST interface +functions to standalone tests. + +2.1.5. Command line interface + +A new command, diag, will be added to U-Boot. This command will be +used for listing all available hardware tests, getting detailed +descriptions of them and running these tests. + +More specifically, being run without any arguments, this command will +print the list of all available hardware tests: + +=> diag +Available hardware tests: + cache - cache test + cpu - CPU test + enet - SCC/FCC ethernet test +Use 'diag [<test1> [<test2>]] ... ' to get more info. +Use 'diag run [<test1> [<test2>]] ... ' to run tests. +=> + +If the first argument to the diag command is not 'run', detailed +descriptions of the specified tests will be printed: + +=> diag cpu cache +cpu - CPU test + This test verifies the arithmetic logic unit of CPU. +cache - cache test + This test verifies the CPU cache operation. +=> + +If the first argument to diag is 'run', the specified tests will be +executed. If no tests are specified, all available tests will be +executed. + +It will be prohibited to execute tests running in ROM manually. The +'diag' command will not display such tests and/or run them. + +2.1.6. Power failure handling + +The Linux kernel will be modified to detect power failures and +automatically reboot the system in such cases. It will be assumed +that the power failure causes a system interrupt. + +To perform correct system shutdown, the kernel will register a +handler of the power-fail IRQ on booting. Being called, the handler +will run /sbin/reboot using the call_usermodehelper() routine. +/sbin/reboot will automatically bring the system down in a secure +way. This feature will be configured in/out from the kernel +configuration file. + +The POST layer of U-Boot will check whether the system runs in +power-fail mode. If it does, the system will be powered off after +executing all hardware tests. + +2.1.7. Hazardous tests + +Some tests may cause system rebooting during their execution. For +some tests, this will indicate a failure, while for the Watchdog +test, this means successful operation of the timer. + +In order to support such tests, the following scheme will be +implemented. All the tests that may cause system rebooting will have +the POST_REBOOT bit flag set in the flag field of the correspondent +post_test structure. Before starting tests marked with this bit flag, +the POST layer will store an identification number of the test in a +location in IMMR. On booting, the POST layer will check the value of +this variable and if it is set will skip over the tests preceding the +failed one. On second execution of the failed test, the POST_REBOOT +bit flag will be set in the flag argument to the test routine. This +will allow to detect system rebooting on the previous iteration. For +example, the watchdog timer test may have the following +declaration/body: + +... +#define POST_WATCHDOG \ + { + "Watchdog timer test", "watchdog", \ + " This test checks the watchdog timer.", \ + POST_RAM | POST_POWERON | POST_REBOOT, \ + &watchdog_post_test \ + } +... + +... +int watchdog_post_test(struct bd_info *bd, int flags) +{ + unsigned long start_time; + + if (flags & POST_REBOOT) { + /* Test passed */ + return 0; + } else { + /* disable interrupts */ + disable_interrupts(); + /* 10-second delay */ + ... + /* if we've reached this, the watchdog timer does not work */ + enable_interrupts(); + return 1; + } +} +... + +2.2. Hardware-specific details + +This project will also develop a set of POST tests for MPC8xx- based +systems. This section provides technical details of how it will be +done. + +2.2.1. Generic PPC tests + +The following generic POST tests will be developed: + + o) CPU test + + This test will check the arithmetic logic unit (ALU) of CPU. The + test will take several milliseconds and will run on normal + booting. + + o) Cache test + + This test will verify the CPU cache (L1 cache). The test will + run on normal booting. + + o) Memory test + + This test will examine RAM and check it for errors. The test + will always run on booting. On normal booting, only a limited + amount of RAM will be checked. On power-fail booting a fool + memory check-up will be performed. + +2.2.1.1. CPU test + +This test will verify the following ALU instructions: + + o) Condition register istructions + + This group will contain: mtcrf, mfcr, mcrxr, crand, crandc, + cror, crorc, crxor, crnand, crnor, creqv, mcrf. + + The mtcrf/mfcr instructions will be tested by loading different + values into the condition register (mtcrf), moving its value to + a general-purpose register (mfcr) and comparing this value with + the expected one. The mcrxr instruction will be tested by + loading a fixed value into the XER register (mtspr), moving XER + value to the condition register (mcrxr), moving it to a + general-purpose register (mfcr) and comparing the value of this + register with the expected one. The rest of instructions will be + tested by loading a fixed value into the condition register + (mtcrf), executing each instruction several times to modify all + 4-bit condition fields, moving the value of the conditional + register to a general-purpose register (mfcr) and comparing it + with the expected one. + + o) Integer compare instructions + + This group will contain: cmp, cmpi, cmpl, cmpli. + + To verify these instructions the test will run them with + different combinations of operands, read the condition register + value and compare it with the expected one. More specifically, + the test will contain a pre-built table containing the + description of each test case: the instruction, the values of + the operands, the condition field to save the result in and the + expected result. + + o) Arithmetic instructions + + This group will contain: add, addc, adde, addme, addze, subf, + subfc, subfe, subme, subze, mullw, mulhw, mulhwu, divw, divwu, + extsb, extsh. + + The test will contain a pre-built table of instructions, + operands, expected results and expected states of the condition + register. For each table entry, the test will cyclically use + different sets of operand registers and result registers. For + example, for instructions that use 3 registers on the first + iteration r0/r1 will be used as operands and r2 for result. On + the second iteration, r1/r2 will be used as operands and r3 as + for result and so on. This will enable to verify all + general-purpose registers. + + o) Logic instructions + + This group will contain: and, andc, andi, andis, or, orc, ori, + oris, xor, xori, xoris, nand, nor, neg, eqv, cntlzw. + + The test scheme will be identical to that from the previous + point. + + o) Shift instructions + + This group will contain: slw, srw, sraw, srawi, rlwinm, rlwnm, + rlwimi + + The test scheme will be identical to that from the previous + point. + + o) Branch instructions + + This group will contain: b, bl, bc. + + The first 2 instructions (b, bl) will be verified by jumping to + a fixed address and checking whether control was transferred to + that very point. For the bl instruction the value of the link + register will be checked as well (using mfspr). To verify the bc + instruction various combinations of the BI/BO fields, the CTR + and the condition register values will be checked. The list of + such combinations will be pre-built and linked in U-Boot at + build time. + + o) Load/store instructions + + This group will contain: lbz(x)(u), lhz(x)(u), lha(x)(u), + lwz(x)(u), stb(x)(u), sth(x)(u), stw(x)(u). + + All operations will be performed on a 16-byte array. The array + will be 4-byte aligned. The base register will point to offset + 8. The immediate offset (index register) will range in [-8 ... + +7]. The test cases will be composed so that they will not cause + alignment exceptions. The test will contain a pre-built table + describing all test cases. For store instructions, the table + entry will contain: the instruction opcode, the value of the + index register and the value of the source register. After + executing the instruction, the test will verify the contents of + the array and the value of the base register (it must change for + "store with update" instructions). For load instructions, the + table entry will contain: the instruction opcode, the array + contents, the value of the index register and the expected value + of the destination register. After executing the instruction, + the test will verify the value of the destination register and + the value of the base register (it must change for "load with + update" instructions). + + o) Load/store multiple/string instructions + + +The CPU test will run in RAM in order to allow run-time modification +of the code to reduce the memory footprint. + +2.2.1.2 Special-Purpose Registers Tests + +TBD. + +2.2.1.3. Cache test + +To verify the data cache operation the following test scenarios will +be used: + + 1) Basic test #1 + + - turn on the data cache + - switch the data cache to write-back or write-through mode + - invalidate the data cache + - write the negative pattern to a cached area + - read the area + + The negative pattern must be read at the last step + + 2) Basic test #2 + + - turn on the data cache + - switch the data cache to write-back or write-through mode + - invalidate the data cache + - write the zero pattern to a cached area + - turn off the data cache + - write the negative pattern to the area + - turn on the data cache + - read the area + + The negative pattern must be read at the last step + + 3) Write-through mode test + + - turn on the data cache + - switch the data cache to write-through mode + - invalidate the data cache + - write the zero pattern to a cached area + - flush the data cache + - write the negative pattern to the area + - turn off the data cache + - read the area + + The negative pattern must be read at the last step + + 4) Write-back mode test + + - turn on the data cache + - switch the data cache to write-back mode + - invalidate the data cache + - write the negative pattern to a cached area + - flush the data cache + - write the zero pattern to the area + - invalidate the data cache + - read the area + + The negative pattern must be read at the last step + +To verify the instruction cache operation the following test +scenarios will be used: + + 1) Basic test #1 + + - turn on the instruction cache + - unlock the entire instruction cache + - invalidate the instruction cache + - lock a branch instruction in the instruction cache + - replace the branch instruction with "nop" + - jump to the branch instruction + - check that the branch instruction was executed + + 2) Basic test #2 + + - turn on the instruction cache + - unlock the entire instruction cache + - invalidate the instruction cache + - jump to a branch instruction + - check that the branch instruction was executed + - replace the branch instruction with "nop" + - invalidate the instruction cache + - jump to the branch instruction + - check that the "nop" instruction was executed + +The CPU test will run in RAM in order to allow run-time modification +of the code. + +2.2.1.4. Memory test + +The memory test will verify RAM using sequential writes and reads +to/from RAM. Specifically, there will be several test cases that will +use different patterns to verify RAM. Each test case will first fill +a region of RAM with one pattern and then read the region back and +compare its contents with the pattern. The following patterns will be +used: + + 1) zero pattern (0x00000000) + 2) negative pattern (0xffffffff) + 3) checkerboard pattern (0x55555555, 0xaaaaaaaa) + 4) bit-flip pattern ((1 << (offset % 32)), ~(1 << (offset % 32))) + 5) address pattern (offset, ~offset) + +Patterns #1, #2 will help to find unstable bits. Patterns #3, #4 will +be used to detect adherent bits, i.e. bits whose state may randomly +change if adjacent bits are modified. The last pattern will be used +to detect far-located errors, i.e. situations when writing to one +location modifies an area located far from it. Also, usage of the +last pattern will help to detect memory controller misconfigurations +when RAM represents a cyclically repeated portion of a smaller size. + +Being run in normal mode, the test will verify only small 4Kb regions +of RAM around each 1Mb boundary. For example, for 64Mb RAM the +following areas will be verified: 0x00000000-0x00000800, +0x000ff800-0x00100800, 0x001ff800-0x00200800, ..., 0x03fff800- +0x04000000. If the test is run in power-fail mode, it will verify the +whole RAM. + +The memory test will run in ROM before relocating U-Boot to RAM in +order to allow RAM modification without saving its contents. + +2.2.2. Common tests + +This section describes tests that are not based on any hardware +peculiarities and use common U-Boot interfaces only. These tests do +not need any modifications for porting them to another board/CPU. + +2.2.2.1. I2C test + +For verifying the I2C bus, a full I2C bus scanning will be performed +using the i2c_probe() routine. If a board defines +CONFIG_SYS_POST_I2C_ADDRS the I2C test will pass if all devices +listed in CONFIG_SYS_POST_I2C_ADDRS are found, and no additional +devices are detected. If CONFIG_SYS_POST_I2C_ADDRS is not defined +the test will pass if any I2C device is found. + +The CONFIG_SYS_POST_I2C_IGNORES define can be used to list I2C +devices which may or may not be present when using +CONFIG_SYS_POST_I2C_ADDRS. The I2C POST test will pass regardless +if the devices in CONFIG_SYS_POST_I2C_IGNORES are found or not. +This is useful in cases when I2C devices are optional (eg on a +daughtercard that may or may not be present) or not critical +to board operation. + +2.2.2.2. Watchdog timer test + +To test the watchdog timer the scheme mentioned above (refer to +section "Hazardous tests") will be used. Namely, this test will be +marked with the POST_REBOOT bit flag. On the first iteration, the +test routine will make a 10-second delay. If the system does not +reboot during this delay, the watchdog timer is not operational and +the test fails. If the system reboots, on the second iteration the +POST_REBOOT bit will be set in the flag argument to the test routine. +The test routine will check this bit and report a success if it is +set. + +2.2.2.3. RTC test + +The RTC test will use the rtc_get()/rtc_set() routines. The following +features will be verified: + + o) Time uniformity + + This will be verified by reading RTC in polling within a short + period of time (5-10 seconds). + + o) Passing month boundaries + + This will be checked by setting RTC to a second before a month + boundary and reading it after its passing the boundary. The test + will be performed for both leap- and nonleap-years. + +2.2.3. MPC8xx peripherals tests + +This project will develop a set of tests verifying the peripheral +units of MPC8xx processors. Namely, the following controllers of the +MPC8xx communication processor module (CPM) will be tested: + + o) Serial Management Controllers (SMC) + + o) Serial Communication Controllers (SCC) + +2.2.3.1. Ethernet tests (SCC) + +The internal (local) loopback mode will be used to test SCC. To do +that the controllers will be configured accordingly and several +packets will be transmitted. These tests may be enhanced in future to +use external loopback for testing. That will need appropriate +reconfiguration of the physical interface chip. + +The test routines for the SCC ethernet tests will be located in +arch/powerpc/cpu/mpc8xx/scc.c. + +2.2.3.2. UART tests (SMC/SCC) + +To perform these tests the internal (local) loopback mode will be +used. The SMC/SCC controllers will be configured to connect the +transmitter output to the receiver input. After that, several bytes +will be transmitted. These tests may be enhanced to make to perform +"external" loopback test using a loopback cable. In this case, the +test will be executed manually. + +The test routine for the SMC/SCC UART tests will be located in +arch/powerpc/cpu/mpc8xx/serial.c. + +2.2.3.3. USB test + +TBD + +2.2.3.4. SPI test + +TBD diff --git a/roms/u-boot/doc/README.SNTP b/roms/u-boot/doc/README.SNTP new file mode 100644 index 000000000..da9ec459a --- /dev/null +++ b/roms/u-boot/doc/README.SNTP @@ -0,0 +1,17 @@ +To use SNTP support, add define CONFIG_CMD_SNTP to the +configuration file of the board. + +The "sntp" command gets network time from NTP time server and +syncronize RTC of the board. This command needs the command line +parameter of server's IP address or environment variable +"ntpserverip". The network time is sent as UTC. So if you want to +set local time to RTC, set the offset in second from UTC to the +environment variable "time offset". + +If the DHCP server provides time server's IP or time offset, you +don't need to set the above environment variables yourself. + +Current limitations of SNTP support: +1. The roundtrip time is ignored. +2. Only the 1st NTP server IP, in the option ntp-servers of DHCP, will + be used. diff --git a/roms/u-boot/doc/README.SPL b/roms/u-boot/doc/README.SPL new file mode 100644 index 000000000..2beb6d8f1 --- /dev/null +++ b/roms/u-boot/doc/README.SPL @@ -0,0 +1,113 @@ +Generic SPL framework +===================== + +Overview +-------- + +To unify all existing implementations for a secondary program loader (SPL) +and to allow simply adding of new implementations this generic SPL framework +has been created. With this framework almost all source files for a board +can be reused. No code duplication or symlinking is necessary anymore. + + +How it works +------------ + +The object files for SPL are built separately and placed in the "spl" directory. +The final binaries which are generated are u-boot-spl, u-boot-spl.bin and +u-boot-spl.map. + +A config option named CONFIG_SPL_BUILD is enabled by Kconfig for SPL. +Source files can therefore be compiled for SPL with different settings. + +For example: + +ifeq ($(CONFIG_SPL_BUILD),y) +obj-y += board_spl.o +else +obj-y += board.o +endif + +obj-$(CONFIG_SPL_BUILD) += foo.o + +#ifdef CONFIG_SPL_BUILD + foo(); +#endif + + +The building of SPL images can be enabled by CONFIG_SPL option in Kconfig. + +Because SPL images normally have a different text base, one has to be +configured by defining CONFIG_SPL_TEXT_BASE. The linker script has to be +defined with CONFIG_SPL_LDSCRIPT. + +To support generic U-Boot libraries and drivers in the SPL binary one can +optionally define CONFIG_SPL_XXX_SUPPORT. Currently following options +are supported: + +CONFIG_SPL_LIBCOMMON_SUPPORT (common/libcommon.o) +CONFIG_SPL_LIBDISK_SUPPORT (disk/libdisk.o) +CONFIG_SPL_I2C_SUPPORT (drivers/i2c/libi2c.o) +CONFIG_SPL_GPIO_SUPPORT (drivers/gpio/libgpio.o) +CONFIG_SPL_MMC_SUPPORT (drivers/mmc/libmmc.o) +CONFIG_SPL_SERIAL_SUPPORT (drivers/serial/libserial.o) +CONFIG_SPL_SPI_FLASH_SUPPORT (drivers/mtd/spi/libspi_flash.o) +CONFIG_SPL_SPI_SUPPORT (drivers/spi/libspi.o) +CONFIG_SPL_FS_FAT (fs/fat/libfat.o) +CONFIG_SPL_FS_EXT4 +CONFIG_SPL_LIBGENERIC_SUPPORT (lib/libgeneric.o) +CONFIG_SPL_POWER_SUPPORT (drivers/power/libpower.o) +CONFIG_SPL_NAND_SUPPORT (drivers/mtd/nand/raw/libnand.o) +CONFIG_SPL_DRIVERS_MISC_SUPPORT (drivers/misc) +CONFIG_SPL_DMA (drivers/dma/libdma.o) +CONFIG_SPL_POST_MEM_SUPPORT (post/drivers/memory.o) +CONFIG_SPL_NAND_LOAD (drivers/mtd/nand/raw/nand_spl_load.o) +CONFIG_SPL_SPI_LOAD (drivers/mtd/spi/spi_spl_load.o) +CONFIG_SPL_RAM_DEVICE (common/spl/spl.c) +CONFIG_SPL_WATCHDOG_SUPPORT (drivers/watchdog/libwatchdog.o) + +Device tree +----------- +The U-Boot device tree is filtered by the fdtgrep tools during the build +process to generate a much smaller device tree used in SPL (spl/u-boot-spl.dtb) +with: +- the mandatory nodes (/alias, /chosen, /config) +- the nodes with one pre-relocation property: + 'u-boot,dm-pre-reloc' or 'u-boot,dm-spl' + +fdtgrep is also used to remove: +- the properties defined in CONFIG_OF_SPL_REMOVE_PROPS +- all the pre-relocation properties + ('u-boot,dm-pre-reloc', 'u-boot,dm-spl' and 'u-boot,dm-tpl') + +All the nodes remaining in the SPL devicetree are bound +(see doc/driver-model/design.rst). + +Debugging +--------- + +When building SPL with DEBUG set you may also need to set CONFIG_PANIC_HANG +as in most cases do_reset is not defined within SPL. + + +Estimating stack usage +---------------------- + +With gcc 4.6 (and later) and the use of GNU cflow it is possible to estimate +stack usage at various points in run sequence of SPL. The -fstack-usage option +to gcc will produce '.su' files (such as arch/arm/cpu/armv7/syslib.su) that +will give stack usage information and cflow can construct program flow. + +Must have gcc 4.6 or later, which supports -fstack-usage + +1) Build normally +2) Perform the following shell command to generate a list of C files used in +SPL: +$ find spl -name '*.su' | sed -e 's:^spl/::' -e 's:[.]su$:.c:' > used-spl.list +3) Execute cflow: +$ cflow --main=board_init_r `cat used-spl.list` 2>&1 | $PAGER + +cflow will spit out a number of warnings as it does not parse +the config files and picks functions based on #ifdef. Parsing the '.i' +files instead introduces another set of headaches. These warnings are +not usually important to understanding the flow, however. diff --git a/roms/u-boot/doc/README.TPL b/roms/u-boot/doc/README.TPL new file mode 100644 index 000000000..72027fd69 --- /dev/null +++ b/roms/u-boot/doc/README.TPL @@ -0,0 +1,49 @@ +Generic TPL framework +===================== + +Overview +-------- + +TPL---Third Program Loader. + +Due to the SPL on some boards(powerpc mpc85xx) has a size limit and cannot +be compatible with all the external device(e.g. DDR). So add a tertiary +program loader (TPL) to enable a loader stub loaded by the code from the +SPL. It loads the final uboot image into DDR, then jump to it to begin +execution. Now, only the powerpc mpc85xx has this requirement and will +implemente it. + +Keep consistent with SPL, with this framework almost all source files for a +board can be reused. No code duplication or symlinking is necessary anymore. + +How it works +------------ + +There has been a directory $(srctree)/spl which contains only a Makefile. The +Makefile is shared by SPL and TPL. + +The object files are built separately for SPL/TPL and placed in the +directory spl/tpl. The final binaries which are generated are +u-boot-{spl|tpl}, u-boot-{spl|tpl}.bin and u-boot-{spl|tpl}.map. + +During the TPL build a variable named CONFIG_TPL_BUILD is exported in the +make environment and also appended to CPPFLAGS with -DCONFIG_TPL_BUILD. + +The SPL options are shared by SPL and TPL, the board config file should +determine which SPL options to choose based on whether CONFIG_TPL_BUILD +is set. Source files can be compiled for TPL with options chosen in the +board config file. + +TPL use a small device tree (u-boot-tpl.dtb), containing only the nodes with +the pre-relocation properties: 'u-boot,dm-pre-reloc' and 'u-boot,dm-tpl' +(see README.SPL for details). + +For example: + +spl/Makefile: +LIBS-$(CONFIG_SPL_LIBCOMMON_SUPPORT) += common/libcommon.o + +CONFIG_SPL_LIBCOMMON_SUPPORT is defined in board config file: +#ifdef CONFIG_TPL_BUILD +#define CONFIG_SPL_LIBCOMMON_SUPPORT +#endif diff --git a/roms/u-boot/doc/README.VLAN b/roms/u-boot/doc/README.VLAN new file mode 100644 index 000000000..4f86d55ea --- /dev/null +++ b/roms/u-boot/doc/README.VLAN @@ -0,0 +1,15 @@ +U-Boot has networking support for VLANs (802.1q), and CDP (Cisco +Discovery Protocol). + +You control the sending/receiving of VLAN tagged packets with the +"vlan" environmental variable. When not present no tagging is +performed. + +CDP is used mainly to discover your device VLAN(s) when connected to +a Cisco switch. + +Note: In order to enable CDP support a small change is needed in the +networking driver. You have to enable reception of the +01:00:0c:cc:cc:cc MAC address which is a multicast address. + +Various defines control CDP; see the README section. diff --git a/roms/u-boot/doc/README.VSC3316-3308 b/roms/u-boot/doc/README.VSC3316-3308 new file mode 100644 index 000000000..925663ba5 --- /dev/null +++ b/roms/u-boot/doc/README.VSC3316-3308 @@ -0,0 +1,43 @@ +This file contains API information of the initialization code written for +Vitesse cross-point devices, VSC3316 and VSC3308 for board B4860QDS + +Author: Shaveta Leekha <shaveta@freescale.com> + +About Device: +============= +VSC 3316/3308 is a low-power, low-cost asynchronous crosspoint switch capable of data rates upto 11.5Gbps. + +VSC3316 has 16 input and 16 output ports whereas VSC3308 has 8 input and 8 output ports. Programming of these devices are performed by two-wire or four-wire serial interface. + +Initialization: +=============== +On reset, VSC devices are in low-power state with all inputs, outputs and connections in an off state. +First thing required is to program it to interface with either two-wire or four-wire interface. +In our case the interface is two-wire I2C serial interface. So the value in Interface mode register at address 79.h to be written is 0x02 for two-wire interface. Also for crosspoint connections to be activated, 01.h value need to be written in 75.h (core configuration register). + +API Overview: +============= + + vsc_if_enable(u8 vsc_addr): + -------------------------- + This API programs VSC to interface with either two-wire or four-wire interface. In our case the interface is two-wire I2C serial interface. So the value in Interface mode register at address 79.h to be written is 0x02 for two-wire interface. + Parameters: + vsc_addr - Address of the VSC device on board. + + + vsc3316_config(u8 vsc_addr, int con_arr[][2], u8 num_con): + --------------------------------------------------------- + This API configures the VSC3316 device for required connections. Connection through the VSC device requires the inputs and outputs to be properly configured. + Connection registers are on page 00. It Configures the selected input and output correctly and join them to make a connection. It also program Input state register, Global input ISE, Global input LOS, Global core control, Output mode register and core control registers etc. + vsc3308_config(u8 vsc_addr, int con_arr[][2], u8 num_con) does the essential configurations for VSC3308. + + Parameters: + vsc_addr - Address of the VSC device on board. + con_arr - connection array + num_con - number of connections to be configured + + vsc_wp_config(u8 vsc_addr): + -------------------------- + For crosspoint connections to be activated, 01.h value need to be written in 75.h (core configuration register), which is done by this API. + Parameters: + vsc_addr - Address of the VSC device on board. diff --git a/roms/u-boot/doc/README.arm-caches b/roms/u-boot/doc/README.arm-caches new file mode 100644 index 000000000..dbb6190b9 --- /dev/null +++ b/roms/u-boot/doc/README.arm-caches @@ -0,0 +1,53 @@ +Disabling I-cache: +- Set CONFIG_SYS_ICACHE_OFF + +Disabling D-cache: +- Set CONFIG_SYS_DCACHE_OFF + +Enabling I-cache: +- Make sure CONFIG_SYS_ICACHE_OFF is not set and call icache_enable(). + +Enabling D-cache: +- Make sure CONFIG_SYS_DCACHE_OFF is not set and call dcache_enable(). + +Enabling Caches at System Startup: +- Implement enable_caches() for your platform and enable the I-cache and + D-cache from this function. This function is called immediately + after relocation. + +Guidelines for Working with D-cache: + +Memory to Peripheral DMA: +- Flush the buffer after the MPU writes the data and before the DMA is + initiated. + +Peripheral to Memory DMA: +- Invalidate the buffer before starting the DMA. In case there are any dirty + lines from the DMA buffer in the cache, subsequent cache-line replacements + may corrupt the buffer in memory while the DMA is still going on. Cache-line + replacement can happen if the CPU tries to bring some other memory locations + into the cache while the DMA is going on. +- Invalidate the buffer after the DMA is complete and before the MPU reads + it. This may be needed in addition to the invalidation before the DMA + mentioned above, because in some processors memory contents can spontaneously + come to the cache due to speculative memory access by the CPU. If this + happens with the DMA buffer while DMA is going on we have a coherency problem. + +Buffer Requirements: +- Any buffer that is invalidated(that is, typically the peripheral to + memory DMA buffer) should be aligned to cache-line boundary both at + at the beginning and at the end of the buffer. +- If the buffer is not cache-line aligned invalidation will be restricted + to the aligned part. That is, one cache-line at the respective boundary + may be left out while doing invalidation. +- A suitable buffer can be alloced on the stack using the + ALLOC_CACHE_ALIGN_BUFFER macro. + +Cleanup Before Linux: +- cleanup_before_linux() should flush the D-cache, invalidate I-cache, and + disable MMU and caches. +- The following sequence is advisable while disabling d-cache: + 1. dcache_disable() - flushes and disables d-cache + 2. invalidate_dcache_all() - invalid any entry that came to the cache + in the short period after the cache was flushed but before the + cache got disabled. diff --git a/roms/u-boot/doc/README.arm-relocation b/roms/u-boot/doc/README.arm-relocation new file mode 100644 index 000000000..bc6644911 --- /dev/null +++ b/roms/u-boot/doc/README.arm-relocation @@ -0,0 +1,193 @@ +To make relocation on arm working, the following changes are done: + +At arch level: add linker flag -pie + + This causes the linker to generate fixup tables .rel.dyn and .dynsym, + which must be applied to the relocated image before transferring + control to it. + + These fixups are described in the ARM ELF documentation as type 23 + (program-base-relative) and 2 (symbol-relative) + +At cpu level: modify linker file and add a relocation and fixup loop + + the linker file must be modified to include the .rel.dyn and .dynsym + tables in the binary image, and to provide symbols for the relocation + code to access these tables + + The relocation and fixup loop must be executed after executing + board_init_f at initial location and before executing board_init_r + at final location. + +At board level: + + dram_init(): bd pointer is now at this point not accessible, so only + detect the real dramsize, and store it in gd->ram_size. Bst detected + with get_ram_size(). + +TODO: move also dram initialization there on boards where it is possible. + + Setup of the bd_info dram bank info is done in the new function + dram_init_banksize() called after bd is accessible. + +At lib level: + + Board.c code is adapted from ppc code + +* WARNING ** WARNING ** WARNING ** WARNING ** WARNING ** WARNING ** WARNING * + +Boards which are not fixed to support relocation will be REMOVED! + +----------------------------------------------------------------------------- + +For boards which boot from spl, it is possible to save one copy +if CONFIG_SYS_TEXT_BASE == relocation address! This prevents that uboot code +is copied again in relocate_code(). + +example for the tx25 board booting from NAND Flash: + +a) cpu starts +b) it copies the first page in nand to internal ram + (spl code) +c) end executes this code +d) this initialize CPU, RAM, ... and copy itself to RAM + (this bin must fit in one page, so board_init_f() + don;t fit in it ... ) +e) there it copy u-boot to CONFIG_SYS_NAND_U_BOOT_DST and + starts this image @ CONFIG_SYS_NAND_U_BOOT_START +f) u-boot code steps through board_init_f() and calculates + the relocation address and copy itself to it + +If CONFIG_SYS_TEXT_BASE == relocation address, the copying of u-boot +in f) could be saved. + +----------------------------------------------------------------------------- + +TODO + +- fill in struct bd_info infos (check) +- adapt all boards + +- maybe adapt CONFIG_SYS_TEXT_BASE (this must be checked from board maintainers) + This *must* be done for boards, which boot from NOR flash + + on other boards if CONFIG_SYS_TEXT_BASE = relocation baseaddr, this saves + one copying from u-boot code. + +- new function dram_init_banksize() is actual board specific. Maybe + we make a weak default function in arch/arm/lib/board.c ? + +----------------------------------------------------------------------------- + +Relocation with SPL (example for the tx25 booting from NAND Flash): + +- cpu copies the first page from NAND to 0xbb000000 (IMX_NFC_BASE) + and start with code execution on this address. + +- The First page contains u-boot code from drivers/mtd/nand/raw/mxc_nand_spl.c + which inits the dram, cpu registers, reloacte itself to CONFIG_SPL_TEXT_BASE and loads + the "real" u-boot to CONFIG_SYS_NAND_U_BOOT_DST and starts execution + @CONFIG_SYS_NAND_U_BOOT_START + +- This u-boot does no RAM init, nor CPU register setup. Just look + where it has to copy and relocate itself to this address. If + relocate address = CONFIG_SYS_TEXT_BASE (not the same, as the + CONFIG_SPL_TEXT_BASE from the spl code), then there is no need + to copy, just go on with bss clear and jump to board_init_r. + +----------------------------------------------------------------------------- + +How ELF relocations 23 and 2 work. + +TBC + +------------------------------------------------------------------------------------- + +Debugging u-boot in RAM: +(example on the qong board) + +----------------- + +a) start debugger + +arm-linux-gdb u-boot + +[hs@pollux u-boot]$ arm-linux-gdb u-boot +GNU gdb Red Hat Linux (6.7-2rh) +Copyright (C) 2007 Free Software Foundation, Inc. +License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html> +This is free software: you are free to change and redistribute it. +There is NO WARRANTY, to the extent permitted by law. Type "show copying" +and "show warranty" for details. +This GDB was configured as "--host=i686-pc-linux-gnu --target=arm-linux". +The target architecture is set automatically (currently arm) +.. +(gdb) + +----------------- + +b) connect to target + +target remote bdi10:2001 + +(gdb) target remote bdi10:2001 +Remote debugging using bdi10:2001 +0x8ff17f10 in ?? () +(gdb) + +----------------- + +c) discard symbol-file + +(gdb) symbol-file +Discard symbol table from `/home/hs/celf/u-boot/u-boot'? (y or n) y +No symbol file now. +(gdb) + +----------------- + +d) load new symbol table: + +(gdb) add-symbol-file u-boot 0x8ff08000 +add symbol table from file "u-boot" at + .text_addr = 0x8ff08000 +(y or n) y +Reading symbols from /home/hs/celf/u-boot/u-boot...done. +(gdb) c +Continuing. +^C +Program received signal SIGSTOP, Stopped (signal). +0x8ff17f18 in serial_getc () at serial_mxc.c:192 +192 while (__REG(UART_PHYS + UTS) & UTS_RXEMPTY); +(gdb) + +add-symbol-file u-boot 0x8ff08000 + ^^^^^^^^^^ + get this address from u-boot bdinfo command + or get it from gd->relocaddr in gdb + + => bdinfo +rch_number = XXXXXXXXXX +boot_params = XXXXXXXXXX +DRAM bank = XXXXXXXXXX +-> start = XXXXXXXXXX +-> size = XXXXXXXXXX +ethaddr = XXXXXXXXXX +ip_addr = XXXXXXXXXX +baudrate = XXXXXXXXXX +TLB addr = XXXXXXXXXX +relocaddr = 0x8ff08000 + ^^^^^^^^^^ +reloc off = XXXXXXXXXX +irq_sp = XXXXXXXXXX +sp start = XXXXXXXXXX +FB base = XXXXXXXXXX + +or interrupt execution by any means and re-load the symbols at the location +specified by gd->relocaddr -- this is only valid after board_init_f. + +(gdb) set $s = gd->relocaddr +(gdb) symbol-file +(gdb) add-symbol-file u-boot $s + +Now you can use gdb as usual :-) diff --git a/roms/u-boot/doc/README.armada-secureboot b/roms/u-boot/doc/README.armada-secureboot new file mode 100644 index 000000000..157cb5a23 --- /dev/null +++ b/roms/u-boot/doc/README.armada-secureboot @@ -0,0 +1,373 @@ +The trusted boot framework on Marvell Armada 38x +================================================ + +Contents: + +1. Overview of the trusted boot +2. Terminology +3. Boot image layout +4. The secured header +5. The secured boot flow +6. Usage example +7. Work to be done +8. Bibliography + +1. Overview of the trusted boot +------------------------------- + +The Armada's trusted boot framework enables the SoC to cryptographically verify +a specially prepared boot image. This can be used to establish a chain of trust +from the boot firmware all the way to the OS. + +To achieve this, the Armada SoC requires a specially prepared boot image, which +contains the relevant cryptographic data, as well as other information +pertaining to the boot process. Furthermore, a eFuse structure (a +one-time-writeable memory) need to be configured in the correct way. + +Roughly, the secure boot process works as follows: + +* Load the header block of the boot image, extract a special "root" public RSA + key from it, and verify its SHA-256 hash against a SHA-256 stored in a eFuse + field. +* Load an array of code signing public RSA keys from the header block, and + verify its RSA signature (contained in the header block as well) using the + "root" RSA key. +* Choose a code signing key, and use it to verify the header block (excluding + the key array). +* Verify the binary image's signature (contained in the header block) using the + code signing key. +* If all checks pass successfully, boot the image. + +The chain of trust is thus as follows: + +* The SHA-256 value in the eFuse field verifies the "root" public key. +* The "root" public key verifies the code signing key array. +* The selected code signing key verifies the header block and the binary image. + +In the special case of building a boot image containing U-Boot as the binary +image, which employs this trusted boot framework, the following tasks need to +be addressed: + +1. Creation of the needed cryptographic key material. +2. Creation of a conforming boot image containing the U-Boot image as binary + image. +3. Burning the necessary eFuse values. + +(1) will be addressed later, (2) will be taken care of by U-Boot's build +system (some user configuration is required, though), and for (3) the necessary +data (essentially a series of U-Boot commands to be entered at the U-Boot +command prompt) will be created by the build system as well. + +The documentation of the trusted boot mode is contained in part 1, chapter +7.2.5 in the functional specification [1], and in application note [2]. + +2. Terminology +-------------- + + CSK - Code Signing Key(s): An array of RSA key pairs, which + are used to sign and verify the secured header and the + boot loader image. + KAK - Key Authentication Key: A RSA key pair, which is used + to sign and verify the array of CSKs. + Header block - The first part of the boot image, which contains the + image's headers (also known as "headers block", "boot + header", and "image header") + eFuse - A one-time-writeable memory. + BootROM - The Armada's built-in boot firmware, which is + responsible for verifying and starting secure images. + Boot image - The complete image the SoC's boot firmware loads + (contains the header block and the binary image) + Main header - The header in the header block containing information + and data pertaining to the boot process (used for both + the regular and secured boot processes) + Binary image - The binary code payload of the boot image; in this + case the U-Boot's code (also known as "source image", + or just "image") + Secured header - The specialized header in the header block that + contains information and data pertaining to the + trusted boot (also known as "security header") + Secured boot mode - A special boot mode of the Armada SoC in which secured + images are verified (non-secure images won't boot); + the mode is activated by setting a eFuse field. + Trusted debug mode - A special mode for the trusted boot that allows + debugging of devices employing the trusted boot + framework in a secure manner (untested in the current + implementation). +Trusted boot framework - The ARMADA SoC's implementation of a secure verified + boot process. + +3. Boot image layout +-------------------- + ++-- Boot image --------------------------------------------+ +| | +| +-- Header block --------------------------------------+ | +| | Main header | | +| +------------------------------------------------------+ | +| | Secured header | | +| +------------------------------------------------------+ | +| | BIN header(s) | | +| +------------------------------------------------------+ | +| | REG header(s) | | +| +------------------------------------------------------+ | +| | Padding | | +| +------------------------------------------------------+ | +| | +| +------------------------------------------------------+ | +| | Binary image + checksum | | +| +------------------------------------------------------+ | ++----------------------------------------------------------+ + +4. The secured header +--------------------- + +For the trusted boot framework, a additional header is added to the boot image. +The following data are relevant for the secure boot: + + KAK: The KAK is contained in the secured header in the form + of a RSA-2048 public key in DER format with a length of + 524 bytes. +Header block signature: The RSA signature of the header block (excluding the + CSK array), created using the selected CSK. +Binary image signature: The RSA signature of the binary image, created using + the selected CSK. + CSK array: The array of the 16 CSKs as RSA-2048 public keys in DER + format with a length of 8384 = 16 * 524 bytes. + CSK block signature: The RSA signature of the CSK array, created using the + KAK. + +NOTE: The JTAG delay, Box ID, and Flash ID header fields do play a role in the +trusted boot process to enable and configure secure debugging, but they were +not tested in the current implementation of the trusted boot in U-Boot. + +5. The secured boot flow +------------------------ + +The steps in the boot flow that are relevant for the trusted boot framework +proceed as follows: + +1) Check if trusted boot is enabled, and perform regular boot if it is not. +2) Load the secured header, and verify its checksum. +3) Select the lowest valid CSK from CSK0 to CSK15. +4) Verify the SHA-256 hash of the KAK embedded in the secured header. +5) Verify the RSA signature of the CSK block from the secured header with the + KAK. +6) Verify the header block signature (which excludes the CSK block) from the + secured header with the selected CSK. +7) Load the binary image to the main memory and verify its checksum. +8) Verify the binary image's RSA signature from the secured header with the + selected CSK. +9) Continue the boot process as in the case of the regular boot. + +NOTE: All RSA signatures are verified according to the PKCS #1 v2.1 standard +described in [3]. + +NOTE: The Box ID and Flash ID are checked after step 6, and the trusted debug +mode may be entered there, but since this mode is untested in the current +implementation, it is not described further. + +6. Usage example +---------------- + +### Create key material + +To employ the trusted boot framework, cryptographic key material needs to be +created. In the current implementation, two keys are needed to build a valid +secured boot image: The KAK private key and a CSK private key (both have to be +2048 bit RSA keys in PEM format). Note that the usage of more than one CSK is +currently not supported. + +NOTE: Since the public key can be generated from the private key, it is +sufficient to store the private key for each key pair. + +OpenSSL can be used to generate the needed files kwb_kak.key and kwb_csk.key +(the names of these files have to be configured, see the next section on +kwbimage.cfg settings): + +openssl genrsa -out kwb_kak.key 2048 +openssl genrsa -out kwb_csk.key 2048 + +The generated files have to be placed in the U-Boot root directory. + +Alternatively, instead of copying the files, symlinks to the private keys can +be placed in the U-Boot root directory. + +WARNING: Knowledge of the KAK or CSK private key would enable an attacker to +generate secured boot images containing arbitrary code. Hence, the private keys +should be carefully guarded. + +### Create/Modifiy kwbimage.cfg + +The Kirkwook architecture in U-Boot employs a special board-specific +configuration file (kwbimage.cfg), which controls various boot image settings +that are interpreted by the BootROM, such as the boot medium. The support the +trusted boot framework, several new options were added to faciliate +configuration of the secured boot. + +The configuration file's layout has been retained, only the following new +options were added: + + KAK - The name of the KAK RSA private key file in the U-Boot + root directory, without the trailing extension of ".key". + CSK - The name of the (active) CSK RSA private key file in the + U-Boot root directory, without the trailing extension of + ".key". + BOX_ID - The BoxID to be used for trusted debugging (a integer + value). + FLASH_ID - The FlashID to be used for trusted debugging (a integer + value). + JTAG_DELAY - The JTAG delay to be used for trusted debugging (a + integer value). + CSK_INDEX - The index of the active CSK (a integer value). +SEC_SPECIALIZED_IMG - Flag to indicate whether to include the BoxID and FlashID + in the image (that is, whether to use the trusted debug + mode or not); no parameters. + SEC_BOOT_DEV - The boot device from which the trusted boot is allowed to + proceed, identified via a numeric ID. The tested values + are 0x34 = NOR flash, 0x31 = SDIO/MMC card; for + additional ID values, consult the documentation in [1]. + SEC_FUSE_DUMP - Dump the "fuse prog" commands necessary for writing the + correct eFuse values to a text file in the U-Boot root + directory. The parameter is the architecture for which to + dump the commands (currently only "a38x" is supported). + +The parameter values may be hardcoded into the file, but it is also possible to +employ a dynamic approach of creating a Autoconf-like kwbimage.cfg.in, then +reading configuration values from Kconfig options or from the board config +file, and generating the actual kwbimage.cfg from this template using Makefile +mechanisms (see board/gdsys/a38x/Makefile as an example for this approach). + +### Set config options + +To enable the generation of trusted boot images, the corresponding support +needs to be activated, and a index for the active CSK needs to be selected as +well. + +Furthermore, eFuse writing support has to be activated in order to burn the +eFuse structure's values (this option is just needed for programming the eFuse +structure; production boot images may disable it). + +ARM architecture + -> [*] Build image for trusted boot + (0) Index of active CSK + -> [*] Enable eFuse support + [ ] Fake eFuse access (dry run) + +### Build and test boot image + +The creation of the boot image is done via the usual invocation of make (with a +suitably set CROSS_COMPILE environment variable, of course). The resulting boot +image u-boot-spl.kwb can then be tested, if so desired. The hdrparser from [5] +can be used for this purpose. To build the tool, invoke make in the +'tools/marvell/doimage_mv' directory of [5], which builds a stand-alone +hdrparser executable. A test can be conducted by calling hdrparser with the +produced boot image and the following (mandatory) parameters: + +./hdrparser -k 0 -t u-boot-spl.kwb + +Here we assume that the CSK index is 0 and the boot image file resides in the +same directory (adapt accordingly if needed). The tool should report that all +checksums are valid ("GOOD"), that all signature verifications succeed +("PASSED"), and, finally, that the overall test was successful +("T E S T S U C C E E D E D" in the last line of output). + +### Burn eFuse structure + ++----------------------------------------------------------+ +| WARNING: Burning the eFuse structure is a irreversible | +| operation! Should wrong or corrupted values be used, the | +| board won't boot anymore, and recovery is likely | +| impossible! | ++----------------------------------------------------------+ + +After the build process has finished, and the SEC_FUSE_DUMP option was set in +the kwbimage.cfg was set, a text file kwb_fuses_a38x.txt should be present in +the U-Boot top-level directory. It contains all the necessary commands to set +the eFuse structure to the values needed for the used KAK digest, as well as +the CSK index, Flash ID and Box ID that were selected in kwbimage.cfg. + +Sequentially executing the commands in this file at the U-Boot command prompt +will write these values to the eFuse structure. + +If the SEC_FUSE_DUMP option was not set, the commands needed to burn the fuses +have to be crafted by hand. The needed fuse lines can be looked up in [1]; a +rough overview of the process is: + +* Burn the KAK public key hash. The hash itself can be found in the file + pub_kak_hash.txt in the U-Boot top-level directory; be careful to account for + the endianness! +* Burn the CSK selection, BoxID, and FlashID +* Enable trusted boot by burning the corresponding fuse (WARNING: this must be + the last fuse line written!) +* Lock the unused fuse lines + +The command to employ is the "fuse prog" command previously enabled by setting +the corresponding configuration option. + +For the trusted boot, the fuse prog command has a special syntax, since the +ARMADA SoC demands that whole fuse lines (64 bit values) have to be written as +a whole. The fuse prog command itself allows lists of 32 bit words to be +written at a time, but this is translated to a series of single 32 bit write +operations to the fuse line, where the individual 32 bit words are identified +by a "word" counter that is increased for each write. + +To work around this restriction, we interpret each line to have three "words" +(0-2): The first and second words are the values to be written to the fuse +line, and the third is a lock flag, which is supposed to lock the fuse line +when set to 1. Writes to the first and second words are memoized between +function calls, and the fuse line is only really written and locked (on writing +the third word) if both words were previously set, so that "incomplete" writes +are prevented. An exception to this is a single write to the third word (index +2) without previously writing neither the first nor the second word, which +locks the fuse line without setting any value; this is needed to lock the +unused fuse lines. + +As an example, to write the value 0011223344556677 to fuse line 10, we would +use the following command: + +fuse prog -y 10 0 00112233 44556677 1 + +Here 10 is the fuse line number, 0 is the index of the first word to be +written, 00112233 and 44556677 are the values to be written to the fuse line +(first and second word) and the trailing 1 is the value for the third word +responsible for locking the line. + +A "lock-only" command would look like this: + +fuse prog -y 11 2 1 + +Here 11 is the fuse number, 2 is the index of the first word to be written +(notice that we only write to word 2 here; the third word for fuse line +locking), and the 1 is the value for the word we are writing to. + +WARNING: According to application note [4], the VHV pin of the SoC must be +connected to a 1.8V source during eFuse programming, but *must* be disconnected +for normal operation. The AN [4] describes a software-controlled circuit (based +on a N-channel or P-channel FET and a free GPIO pin of the SoC) to achieve +this, but a jumper-based circuit should suffice as well. Regardless of the +chosen circuit, the issue needs to be addressed accordingly! + +7. Work to be done +------------------ + +* Add the ability to populate more than one CSK +* Test secure debug +* Test on Armada XP + +8. Bibliography +--------------- + +[1] ARMADA(R) 38x Family High-Performance Single/Dual CPU System on Chip + Functional Specification; MV-S109094-00, Rev. C; August 2, 2015, + Preliminary +[2] AN-383: ARMADA(R) 38x Families Secure Boot Mode Support; MV-S302501-00 + Rev. A; March 11, 2015, Preliminary +[3] Public-Key Cryptography Standards (PKCS) #1: RSA Cryptography + Specifications Version 2.1; February 2003; + https://www.ietf.org/rfc/rfc3447.txt +[4] AN-389: ARMADA(R) VHV Power; MV-S302545-00 Rev. B; January 28, 2016, + Released +[5] Marvell Armada 38x U-Boot support; November 25, 2015; + https://github.com/MarvellEmbeddedProcessors/u-boot-marvell + +2017-01-05, Mario Six <mario.six@gdsys.cc> diff --git a/roms/u-boot/doc/README.asn1 b/roms/u-boot/doc/README.asn1 new file mode 100644 index 000000000..1359b93ae --- /dev/null +++ b/roms/u-boot/doc/README.asn1 @@ -0,0 +1,40 @@ +ASN1 +==== + +Abstract Syntax Notation One (or ASN1) is a standard by ITU-T and ISO/IEC +and used as a description language for defining data structure in +an independent manner. +Any data described in ASN1 notation can be serialized (or encoded) and +de-serialized (or decoded) with well-defined encoding rules. + +A combination of ASN1 compiler and ASN1 decoder library function will +provide a function interface for parsing encoded binary into specific +data structure: +1) define data structure in a text file (*.asn1) +2) define "action" routines for specific "tags" defined in (1) +3) generate bytecode as a C file (*.asn1.[ch]) from *.asn1 file + with ASN1 compiler (tools/asn1_compiler) +4) call a ASN1 decoder (asn1_ber_decoder()) with bytecode and data + +Usage of ASN1 compiler +---------------------- + asn1_compiler [-v] [-d] <grammar-file> <c-file> <hdr-file> + + <grammar-file>: ASN1 input file + <c-file>: generated C file + <hdr-file>: generated include file + +Usage of ASN1 decoder +--------------------- + int asn1_ber_decoder(const struct asn1_decoder *decoder, void *context, + const unsigned char *data, size_t datalen); + + @decoder: bytecode binary + @context: context for decoder + @data: data to be parsed + @datalen: size of data + + +As of writing this, ASN1 compiler and decoder are used to implement +X509 certificate parser, pcks7 message parser and RSA public key parser +for UEFI secure boot. diff --git a/roms/u-boot/doc/README.atmel_mci b/roms/u-boot/doc/README.atmel_mci new file mode 100644 index 000000000..00e64ba0c --- /dev/null +++ b/roms/u-boot/doc/README.atmel_mci @@ -0,0 +1,74 @@ +How to use SD/MMC cards with Atmel SoCs having MCI hardware +----------------------------------------------------------- +2010-08-16 Reinhard Meyer <reinhard.meyer@emk-elektronik.de> + +This is a new approach to use Atmel MCI hardware with the +general MMC framework. Therefore it benefits from that +framework's abilities to handle SDHC Cards and the ability +to write blocks. + +- AT91SAM9XE512 (tested, will definitely work with XE128 and XE256) +- AT91SAM9260 (not tested, but MCI is to AT91SAM9XE) +- AT91SAM9G20 (not tested, should work) + +It should work with all other ATMEL devices that have MCI. + +The generic driver does NOT assign port pins to the MCI block +nor does it start the MCI clock. This has to be handled in a +board/SoC specific manner before the driver is initialized: + +example: this is added to at91sam9260_devices.c: + +#if defined(CONFIG_GENERIC_ATMEL_MCI) +void at91_mci_hw_init(void) +{ + at91_set_a_periph(AT91_PIO_PORTA, 8, PUP); /* MCCK */ +#if defined(CONFIG_ATMEL_MCI_PORTB) + at91_set_b_periph(AT91_PIO_PORTA, 1, PUP); /* MCCDB */ + at91_set_b_periph(AT91_PIO_PORTA, 0, PUP); /* MCDB0 */ + at91_set_b_periph(AT91_PIO_PORTA, 5, PUP); /* MCDB1 */ + at91_set_b_periph(AT91_PIO_PORTA, 4, PUP); /* MCDB2 */ + at91_set_b_periph(AT91_PIO_PORTA, 3, PUP); /* MCDB3 */ +#else + at91_set_a_periph(AT91_PIO_PORTA, 7, PUP); /* MCCDA */ + at91_set_a_periph(AT91_PIO_PORTA, 6, PUP); /* MCDA0 */ + at91_set_a_periph(AT91_PIO_PORTA, 9, PUP); /* MCDA1 */ + at91_set_a_periph(AT91_PIO_PORTA, 10, PUP); /* MCDA2 */ + at91_set_a_periph(AT91_PIO_PORTA, 11, PUP); /* MCDA3 */ +#endif +} +#endif + +the board specific file need added: +... +#ifdef CONFIG_GENERIC_ATMEL_MCI +# include <mmc.h> +#endif +... +#ifdef CONFIG_GENERIC_ATMEL_MCI +/* this is a weak define that we are overriding */ +int board_mmc_init(struct bd_info *bd) +{ + /* Enable clock */ + at91_sys_write(AT91_PMC_PCER, 1 << AT91SAM9260_ID_MCI); + at91_mci_hw_init(); + + /* This calls the atmel_mci_init in gen_atmel_mci.c */ + return atmel_mci_init((void *)AT91_BASE_MCI); +} + +/* this is a weak define that we are overriding */ +int board_mmc_getcd(struct mmc *mmc) +{ + return !at91_get_gpio_value(CONFIG_SYS_MMC_CD_PIN); +} + +#endif + +and the board definition files needs: + +/* SD/MMC card */ +#define CONFIG_GENERIC_ATMEL_MCI 1 +#define CONFIG_ATMEL_MCI_PORTB 1 /* Atmel XE-EK uses port B */ +#define CONFIG_SYS_MMC_CD_PIN AT91_PIN_PC9 +#define CONFIG_CMD_MMC 1 diff --git a/roms/u-boot/doc/README.atmel_pmecc b/roms/u-boot/doc/README.atmel_pmecc new file mode 100644 index 000000000..c86d08577 --- /dev/null +++ b/roms/u-boot/doc/README.atmel_pmecc @@ -0,0 +1,49 @@ +How to enable PMECC(Programmable Multibit ECC) for nand on Atmel SoCs +----------------------------------------------------------- +2012-08-22 Josh Wu <josh.wu@atmel.com> + +The Programmable Multibit ECC (PMECC) controller is a programmable binary +BCH(Bose, Chaudhuri and Hocquenghem) encoder and decoder. This controller +can be used to support both SLC and MLC NAND Flash devices. It supports to +generate ECC to correct 2, 4, 8, 12 or 24 bits of error per sector (512 or +1024 bytes) of data. + +Following Atmel AT91 products support PMECC. +- AT91SAM9X25, X35, G25, G15, G35 (tested) +- AT91SAM9N12 (not tested, Should work) + +As soon as your nand flash software ECC works, you can enable PMECC. + +To use PMECC in this driver, the user needs to set: + 1. the PMECC correction error bits capability: CONFIG_PMECC_CAP. + It can be 2, 4, 8, 12 or 24. + 2. The PMECC sector size: CONFIG_PMECC_SECTOR_SIZE. + It only can be 512 or 1024. + +Take 'configs/at91sam9x5ek_nandflash_defconfig' as an example, the board +configuration file has the following entries: + + CONFIG_PMECC_CAP=2 + CONFIG_PMECC_SECTOR_SIZE=512 + CONFIG_SPL_GENERATE_ATMEL_PMECC_HEADER=y + +How to enable PMECC header for direct programmable boot.bin +----------------------------------------------------------- +2014-05-19 Andreas Bießmann <andreas@biessmann.org> + +The usual way to program SPL into NAND flash is to use the SAM-BA Atmel tool. +This however is often not usable when doing field updates. To be able to +program a SPL binary into NAND flash we need to add the PMECC header to the +binary before. Chapter '12.4.4.1 NAND Flash Boot: NAND Flash Detection' in +sama5d3 SoC spec (as of 03. April 2014) defines how this PMECC header has to +look like. In order to do so we have a new image type added to mkimage to +generate this PMECC header and integrated this into the build process of SPL. + +To enable the generation of atmel PMECC header for SPL one needs to define +CONFIG_SPL_GENERATE_ATMEL_PMECC_HEADER. The required parameters are taken from +board configuration and compiled into the host tools atmel_pmecc_params. This +tool will be called in build process to parametrize mkimage for atmelimage +type. The mkimage tool has intentionally _not_ compiled in those parameters. + +The mkimage image type atmelimage also set the 6'th interrupt vector to the +correct value. This feature can also be used to setup a boot.bin for MMC boot. diff --git a/roms/u-boot/doc/README.autoboot b/roms/u-boot/doc/README.autoboot new file mode 100644 index 000000000..5e9a5e1cf --- /dev/null +++ b/roms/u-boot/doc/README.autoboot @@ -0,0 +1,162 @@ +SPDX-License-Identifier: GPL-2.0+ +/* + * (C) Copyright 2001 + * Dave Ellis, SIXNET, dge@sixnetio.com + * + */ + +Using autoboot configuration options +==================================== + +The basic autoboot configuration options are documented in the main +U-Boot README. See it for details. They are: + + bootdelay + bootcmd + CONFIG_BOOTDELAY + CONFIG_BOOTCOMMAND + +Some additional options that make autoboot safer in a production +product are documented here. + +Why use them? +------------- + +The basic autoboot feature allows a system to automatically boot to +the real application (such as Linux) without a user having to enter +any commands. If any key is pressed before the boot delay time +expires, U-Boot stops the autoboot process, gives a U-Boot prompt +and waits forever for a command. That's a good thing if you pressed a +key because you wanted to get the prompt. + +It's not so good if the key press was a stray character on the +console serial port, say because a user who knows nothing about +U-Boot pressed a key before the system had time to boot. It's even +worse on an embedded product that doesn't have a console during +normal use. The modem plugged into that console port sends a +character at the wrong time and the system hangs, with no clue as to +why it isn't working. + +You might want the system to autoboot to recover after an external +configuration program stops autoboot. If the configuration program +dies or loses its connection (modems can disconnect at the worst +time) U-Boot will patiently wait forever for it to finish. + +These additional configuration options can help provide a system that +boots when it should, but still allows access to U-Boot. + +What they do +------------ + + CONFIG_BOOT_RETRY_TIME + CONFIG_BOOT_RETRY_MIN + + "bootretry" environment variable + + These options determine what happens after autoboot is + stopped and U-Boot is waiting for commands. + + CONFIG_BOOT_RETRY_TIME must be defined to enable the boot + retry feature. If the environment variable "bootretry" is + found then its value is used, otherwise the retry timeout is + CONFIG_BOOT_RETRY_TIME. CONFIG_BOOT_RETRY_MIN is optional and + defaults to CONFIG_BOOT_RETRY_TIME. All times are in seconds. + + If the retry timeout is negative, the U-Boot command prompt + never times out. Otherwise it is forced to be at least + CONFIG_BOOT_RETRY_MIN seconds. If no valid U-Boot command is + entered before the specified time the boot delay sequence is + restarted. Each command that U-Boot executes restarts the + timeout. + + If CONFIG_BOOT_RETRY_TIME < 0 the feature is there, but + doesn't do anything unless the environment variable + "bootretry" is >= 0. + + CONFIG_AUTOBOOT_KEYED + CONFIG_AUTOBOOT_KEYED_CTRLC + CONFIG_AUTOBOOT_PROMPT + CONFIG_AUTOBOOT_DELAY_STR + CONFIG_AUTOBOOT_STOP_STR + + "bootdelaykey" environment variable + "bootstopkey" environment variable + + These options give more control over stopping autoboot. When + they are used a specific character or string is required to + stop or delay autoboot. + + Define CONFIG_AUTOBOOT_KEYED (no value required) to enable + this group of options. CONFIG_AUTOBOOT_DELAY_STR, + CONFIG_AUTOBOOT_STOP_STR or both should be specified (or + specified by the corresponding environment variable), + otherwise there is no way to stop autoboot. + + CONFIG_AUTOBOOT_PROMPT is displayed before the boot delay + selected by CONFIG_BOOTDELAY starts. If it is not defined + there is no output indicating that autoboot is in progress. + + Note that CONFIG_AUTOBOOT_PROMPT is used as the (only) + argument to a printf() call, so it may contain '%' format + specifications, provided that it also includes, sepearated by + commas exactly like in a printf statement, the required + arguments. It is the responsibility of the user to select only + such arguments that are valid in the given context. A + reasonable prompt could be defined as + + #define CONFIG_AUTOBOOT_PROMPT \ + "autoboot in %d seconds\n",bootdelay + + If CONFIG_AUTOBOOT_DELAY_STR or "bootdelaykey" is specified + and this string is received from console input before + autoboot starts booting, U-Boot gives a command prompt. The + U-Boot prompt will time out if CONFIG_BOOT_RETRY_TIME is + used, otherwise it never times out. + + If CONFIG_AUTOBOOT_STOP_STR or "bootstopkey" is specified and + this string is received from console input before autoboot + starts booting, U-Boot gives a command prompt. The U-Boot + prompt never times out, even if CONFIG_BOOT_RETRY_TIME is + used. + + The string recognition is not very sophisticated. If a + partial match is detected, the first non-matching character + is checked to see if starts a new match. There is no check + for a shorter partial match, so it's best if the first + character of a key string does not appear in the rest of the + string. + + The CONFIG_AUTOBOOT_KEYED_CTRLC #define allows for the boot + sequence to be interrupted by ctrl-c, in addition to the + "bootdelaykey" and "bootstopkey". Setting this variable + provides an escape sequence from the limited "password" + strings. + + CONFIG_AUTOBOOT_ENCRYPTION + + "bootstopkeysha256" environment variable + + - Hash value of the input which unlocks the device and + stops autoboot. + + This option allows a string to be entered into U-Boot to stop the + autoboot. The string itself is hashed and compared against the hash + in the environment variable 'bootstopkeysha256'. If it matches then + boot stops and a command-line prompt is presented. + + This provides a way to ship a secure production device which can also + be accessed at the U-Boot command line. + + CONFIG_RESET_TO_RETRY + + (Only effective when CONFIG_BOOT_RETRY_TIME is also set) + After the countdown timed out, the board will be reset to restart + again. + + CONFIG_AUTOBOOT_USE_MENUKEY + CONFIG_AUTOBOOT_MENUKEY + + If this key is pressed to stop autoboot, then the commands in the + environment variable 'menucmd' will be executed before boot starts. + For example, 33 means "!" in ASCII, so pressing ! at boot would take + this action. diff --git a/roms/u-boot/doc/README.bcm7xxx b/roms/u-boot/doc/README.bcm7xxx new file mode 100644 index 000000000..9b5eae474 --- /dev/null +++ b/roms/u-boot/doc/README.bcm7xxx @@ -0,0 +1,150 @@ +Summary +======= + +This document describes how to use U-Boot on the Broadcom 7445 SoC, as +a third stage bootloader loaded by Broadcom's BOLT bootloader. + +BOLT loads U-Boot as a generic ELF binary. Some U-Boot features such +as networking are not yet available but other important features are, +including: + + - ext4 file system traversal + + - support for loading FIT images + + - advanced scripting + + - support for FIT-provided DTBs instead of relying on the + BOLT-provided DTB + +A customized version of this port has been used in production. The +same approach may work on other BCM7xxx boards, with some +configuration adjustments and memory layout experimentation. + +Build +===== + +make bcm7445_defconfig +make +${CROSS_COMPILE}strip u-boot + +Run +=== + +Flash the u-boot binary into board storage, then invoke it from BOLT. +For example: + +BOLT> boot -bsu -elf flash0.u-boot1 + +This port assumes that I-cache and D-cache are already enabled when +U-Boot is entered. + +Flattened Image Tree Support +============================ + +What follows is an example FIT image source file. Build it with: + +mkimage -f image.its image.itb + +Booting the resulting image.itb was tested on BOLT v1.20, with the +following kernels: + +https://github.com/Broadcom/stblinux-3.14 +https://github.com/Broadcom/stblinux-4.1 +https://github.com/Broadcom/stblinux-4.9 + +and with a generic ARMv7 root file system. + +image.its: +/dts-v1/; +/ { + description = "BCM7445 FIT"; + images { + kernel@1 { + description = "Linux kernel"; + /* + * This kernel image output format can be + * generated with: + * + * make vmlinux + * ${CROSS_COMPILE}objcopy -O binary -S vmlinux vmlinux.bin + * gzip -9 vmlinux.bin + * + * For stblinux-3.14, the specific Broadcom + * board type should be configured in the + * kernel, for example CONFIG_BCM7445D0=y. + */ + data = /incbin/("<vmlinux.bin.gz>"); + type = "kernel"; + arch = "arm"; + os = "linux"; + compression = "gzip"; + load = <0x8000>; + entry = <0x8000>; + hash@1 { + algo = "sha256"; + }; + }; + ramdisk@1 { + description = "Initramfs root file system"; + data = /incbin/("<initramfs.cpio.gz>"); + type = "ramdisk"; + arch = "arm"; + os = "linux"; + compression = "gzip"; + /* + * Set the environment variable initrd_high to + * 0xffffffff, and set "load" and "entry" here + * to 0x0 to keep initramfs in-place and to + * accommodate stblinux bmem/CMA reservations. + */ + load = <0x0>; + entry = <0x0>; + hash@1 { + algo = "sha256"; + }; + }; + fdt@1 { + description = "Device tree dumped from BOLT"; + /* + * This DTB should be similar to the + * BOLT-generated device tree, after BOLT has + * done its runtime modifications to it. For + * example, it can be dumped from within + * U-Boot (at ${fdtcontroladdr}), after BOLT + * has loaded U-Boot. The result can be added + * to the Linux source tree as a .dts file. + * + * To support modifications to the device tree + * in-place in U-Boot, add to Linux's + * arch/arm/boot/dts/Makefile: + * + * DTC_FLAGS ?= -p 4096 + * + * This will leave some padding in the DTB and + * thus reserve room for node additions. + * + * Also, set the environment variable fdt_high + * to 0xffffffff to keep the DTB in-place and + * to accommodate stblinux bmem/CMA + * reservations. + */ + data = /incbin/("<bolt-<version>.dtb"); + type = "flat_dt"; + arch = "arm"; + compression = "none"; + hash@1 { + algo = "sha256"; + }; + }; + }; + configurations { + default = "conf@bcm7445"; + conf@bcm7445 { + description = "BCM7445 configuration"; + kernel = "kernel@1"; + ramdisk = "ramdisk@1"; + fdt = "fdt@1"; + }; + }; +}; diff --git a/roms/u-boot/doc/README.bcmns3 b/roms/u-boot/doc/README.bcmns3 new file mode 100644 index 000000000..c51f91471 --- /dev/null +++ b/roms/u-boot/doc/README.bcmns3 @@ -0,0 +1,74 @@ +BCMNS3 QSPI memory layout +========================= + +BCMNS3 has total 8MB non-volatile SPI flash memory. It is used to store +different images like fip.bin, nitro firmware, DDR shmo value and other backup +images. + +Following is the QSPI flash memory layout. + +/* QSPI layout + * |---------------------------|->0x000000 + * | | + * | | + * | fip.bin | + * | 2MB | + * | | + * ~ ~ + * ~ ~ + * | | + * | | + * | | + * |---------------------------|->0x200000 + * | | + * | | + * | | + * | fip.bin (Mirror) | + * | 2MB | + * ~ ~ + * ~ ~ + * | | + * | | + * | | + * |---------------------------|->0x400000 + * | | + * | Nitro NS3 Config | + * | 1.5M | + * | | + * ~ ~ + * ~ ~ + * | | + * |---------------------------|->0x580000 + * | Nitro NS3 Config | + * | 1.5M | + * | (Mirror) | + * ~ ~ + * ~ ~ + * | | + * |---------------------------|->0x700000 + * | Nitro NS3 bspd Config | + * | 64KB | + * ~ ~ + * ~ ~ + * | | + * |---------------------------|->0x710000 + * | Nitro NS3 bspd Config | + * | 64KB | + * ~ (Mirror) ~ + * ~ ~ + * | | + * |---------------------------|->0x720000 + * | SHMOO | + * | 64KB | + * | | + * ~ ~ + * ~ ~ + * |---------------------------|->0x730000 + * | Meta Data | + * | 832KB | + * | | + * ~ ~ + * ~ ~ + * | | + * |---------------------------| + */ diff --git a/roms/u-boot/doc/README.bedbug b/roms/u-boot/doc/README.bedbug new file mode 100644 index 000000000..35e9d2706 --- /dev/null +++ b/roms/u-boot/doc/README.bedbug @@ -0,0 +1,78 @@ +BEDBUG Support for U-Boot +-------------------------- + +These changes implement the bedbug (emBEDded deBUGger) debugger in U-Boot. +A specific implementation is made for the AMCC 405 processor but other flavors +can be easily implemented. + +##################### +### Modifications ### +##################### + +./common/Makefile + Included cmd_bedbug.c and bedbug.c in the Makefile. + +./common/command.c + Added bedbug commands to command table. + +./common/board.c + Added call to initialize debugger on startup. + +./arch/powerpc/cpu/ppc4xx/Makefile + Added bedbug_405.c to the Makefile. + +./arch/powerpc/cpu/ppc4xx/start.S + Added code to handle the debug exception (0x2000) on the 405. + Also added code to handle critical exceptions since the debug + is treated as critical on the 405. + +./arch/powerpc/cpu/ppc4xx/traps.c + Added more detailed output for the program exception to tell + if it is an illegal instruction, privileged instruction or + a trap. Also added debug trap handler. + +./include/ppc_asm.tmpl + Added code to handle critical exceptions + +################# +### New Stuff ### +################# + +./include/bedbug/ppc.h +./include/bedbug/regs.h +./include/bedbug/bedbug.h +./include/bedbug/elf.h [obsoleted by new include/elf.h] +./include/bedbug/tables.h +./include/cmd_bedbug.h +./common/cmd_bedbug.c +./common/bedbug.c + Bedbug library includes code for assembling and disassembling + PowerPC instructions to/from memory as well as handling + hardware breakpoints and stepping through code. These + routines are common to all PowerPC processors. + +./arch/powerpc/cpu/ppc4xx/bedbug_405.c + AMCC PPC405 specific debugger routines. + + +Bedbug support for the MPC860 +----------------------------- + +Changes: + + common/cmd_bedbug.c + Added call to initialize 860 debugger. + + arch/powerpc/cpu/mpc8xx/Makefile + Added new file "bedbug_860.c" to the makefile + + arch/powerpc/cpu/mpc8xx/start.S + Added handler for InstructionBreakpoint (0xfd00) + + arch/powerpc/cpu/mpc8xx/traps.c + Added new routine DebugException() + +New Files: + + arch/powerpc/cpu/mpc8xx/bedbug_860.c + CPU-specific routines for 860 debug registers. diff --git a/roms/u-boot/doc/README.bitbangMII b/roms/u-boot/doc/README.bitbangMII new file mode 100644 index 000000000..0a2fa48a5 --- /dev/null +++ b/roms/u-boot/doc/README.bitbangMII @@ -0,0 +1,56 @@ +This patch rewrites the miiphybb ( Bit-banged MII bus driver ) in order to +support an arbitrary number of mii buses. This feature is useful when your +board uses different mii buses for different phys and all (or a part) of these +buses are implemented via bit-banging mode. + +The driver requires that the following macros should be defined into the board +configuration file: + +CONFIG_BITBANGMII - Enable the miiphybb driver +CONFIG_BITBANGMII_MULTI - Enable the multi bus support + +If the CONFIG_BITBANGMII_MULTI is not defined, the board's config file needs +to define at least the following macros: + +MII_INIT - Generic code to enable the MII bus (optional) +MDIO_DECLARE - Declaration needed to access to the MDIO pin (optional) +MDIO_ACTIVE - Activate the MDIO pin as out pin +MDIO_TRISTATE - Activate the MDIO pin as input/tristate pin +MDIO_READ - Read the MDIO pin +MDIO(v) - Write v on the MDIO pin +MDC_DECLARE - Declaration needed to access to the MDC pin (optional) +MDC(v) - Write v on the MDC pin + +The previous macros make the driver compatible with the previous version +(that didn't support the multi-bus). + +When the CONFIG_BITBANGMII_MULTI is also defined, the board code needs to fill +the bb_miiphy_buses[] array with a record for each required bus and declare +the bb_miiphy_buses_num variable with the number of mii buses. +The record (struct bb_miiphy_bus) has the following fields/callbacks (see +miiphy.h for details): + +char name[] - The symbolic name that must be equal to the MII bus + registered name +int (*init)() - Initialization function called at startup time (just + before the Ethernet initialization) +int (*mdio_active)() - Activate the MDIO pin as output +int (*mdio_tristate)() - Activate the MDIO pin as input/tristate pin +int (*set_mdio)() - Write the MDIO pin +int (*get_mdio)() - Read the MDIO pin +int (*set_mdc)() - Write the MDC pin +int (*delay)() - Delay function +void *priv - Private data used by board specific code + +The board code will look like: + +struct bb_miiphy_bus bb_miiphy_buses[] = { + { .name = "miibus#1", .init = b1_init, .mdio_active = b1_mdio_active, ... }, + { .name = "miibus#2", .init = b2_init, .mdio_active = b2_mdio_active, ... }, + ... +}; +int bb_miiphy_buses_num = sizeof(bb_miiphy_buses) / + sizeof(bb_miiphy_buses[0]); + +2009 Industrie Dial Face S.p.A. + Luigi 'Comio' Mantellini <luigi.mantellini@idf-hit.com> diff --git a/roms/u-boot/doc/README.bloblist b/roms/u-boot/doc/README.bloblist new file mode 100644 index 000000000..274c46055 --- /dev/null +++ b/roms/u-boot/doc/README.bloblist @@ -0,0 +1,82 @@ +# SPDX-License-Identifier: GPL-2.0+ + +Blob Lists - bloblist +===================== + +Introduction +------------ + +A bloblist provides a way to store collections of binary information (blobs) in +a central structure. Each record of information is assigned a tag so that its +owner can find it and update it. Each record is generally described by a C +structure defined by the code that owns it. + + +Passing state through the boot process +-------------------------------------- + +The bloblist is created when the first U-Boot component runs (often SPL, +sometimes TPL). It is passed through to each successive part of the boot and +can be accessed as needed. This provides a way to transfer state from one part +to the next. For example, TPL may determine that a watchdog reset occurred by +reading an SoC register. Reading the register may reset the value, so that it +cannot be read a second time. So TPL can store that in a bloblist record which +can be passed through to SPL and U-Boot proper, which can print a message +indicating that something went wrong and the watchdog fired. + + +Blobs +----- + +While each blob in the bloblist can be of any length, bloblists are designed to +hold small amounts of data, typically a few KB at most. It is not possible to +change the length of a blob once it has been written. Each blob is normally +created from a C structure which can beused to access its fields. + + +Blob tags +--------- + +Each blob has a tag which is a 32-bit number. This uniquely identifies the +owner of the blob. Blob tags are listed in enum blob_tag_t and are named +with a BLOBT_ prefix. + + +Single structure +---------------- + +There is normally only one bloblist in U-Boot. Since a bloblist can store +multiple blobs it does not seem useful to allow multiple bloblists. Of course +there could be reasons for this, such as needing to spread the blobs around in +different memory areas due to fragmented memory, but it is simpler to just have +a single bloblist. + + +API +--- + +Bloblist provides a fairly simple API which allows blobs to be created and +found. All access is via the blob's tag. Blob records are zeroed when added. + + +Finishing the bloblist +---------------------- + +When a part of U-Boot is about to jump to the next part, it can 'finish' the +bloblist in preparation for the next stage. This involves adding a checksum so +that the next stage can make sure that the data arrived safely. While the +bloblist is in use, changes can be made which will affect the checksum, so it +is easier to calculate the checksum at the end after all changes are made. + + +Future work +----------- + +Bootstage has a mechanism to 'stash' its records for passing to the next part. +This should move to using bloblist, to avoid having its own mechanism for +passing information between U-Boot parts. + + +Simon Glass +sjg@chromium.org +12-Aug-2018 diff --git a/roms/u-boot/doc/README.bootcount b/roms/u-boot/doc/README.bootcount new file mode 100644 index 000000000..b1c22905c --- /dev/null +++ b/roms/u-boot/doc/README.bootcount @@ -0,0 +1,51 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +Boot Count Limit +================ + +This allows to detect multiple failed attempts to boot Linux. + +After a power-on reset, "bootcount" variable will be initialized with 1, and +each reboot will increment the value by 1. + +If, after a reboot, the new value of "bootcount" exceeds the value of +"bootlimit", then instead of the standard boot action (executing the contents of +"bootcmd") an alternate boot action will be performed, and the contents of +"altbootcmd" will be executed. + +If the variable "bootlimit" is not defined in the environment, the Boot Count +Limit feature is disabled. If it is enabled, but "altbootcmd" is not defined, +then U-Boot will drop into interactive mode and remain there. + +It is the responsibility of some application code (typically a Linux +application) to reset the variable "bootcount", thus allowing for more boot +cycles. + +BOOTCOUNT_EXT +------------- + +This adds support for maintaining boot count in a file on an EXT filesystem. +The file to use is define by: + +SYS_BOOTCOUNT_EXT_INTERFACE +SYS_BOOTCOUNT_EXT_DEVPART +SYS_BOOTCOUNT_EXT_NAME + +The format of the file is: + +==== ================= +type entry +==== ================= +u8 magic +u8 version +u8 bootcount +u8 upgrade_available +==== ================= + +To prevent unattended usage of "altbootcmd" the "upgrade_available" variable is +used. +If "upgrade_available" is 0, "bootcount" is not saved, if "upgrade_available" is +1 "bootcount" is save. +So the Userspace Application must set the "upgrade_available" and "bootcount" +variables to 0, if a boot was successfully. +This also prevents writes on all reboots. diff --git a/roms/u-boot/doc/README.boston b/roms/u-boot/doc/README.boston new file mode 100644 index 000000000..38f6710e4 --- /dev/null +++ b/roms/u-boot/doc/README.boston @@ -0,0 +1,58 @@ +MIPS Boston Development Board + +--------- + About +--------- + +The MIPS Boston development board is built around an FPGA & 3 PCIe controllers, +one of which is connected to an Intel EG20T Platform Controller Hub which +provides most connectivity to the board. It is used during the development & +testing of both new CPUs and the software support for them. It is essentially +the successor of the older MIPS Malta board. + +-------- + QEMU +-------- + +U-Boot can be run on a currently out-of-tree branch of QEMU with support for +the Boston board added. This QEMU code can currently be found in the "boston" +branch of git://git.linux-mips.org/pub/scm/paul/qemu.git and used like so: + + $ git clone git://git.linux-mips.org/pub/scm/paul/qemu.git -b boston + $ cd qemu + $ ./configure --target-list=mips64el-softmmu + $ make + $ ./mips64el-softmmu/qemu-system-mips64el -M boston -m 2G \ + -bios u-boot.bin -serial stdio + +Please note that QEMU will default to emulating the I6400 CPU which implements +the MIPS64r6 ISA, and at the time of writing doesn't implement any earlier CPUs +with support for the CPS features the Boston board relies upon. You will +therefore need to configure U-Boot to build for MIPSr6 in order to obtain a +binary that will work in QEMU. + +------------- + Toolchain +------------- + +If building for MIPSr6 then you will need a toolchain including GCC 5.x or +newer, or the Codescape toolchain available for download from Imagination +Technologies: + + http://codescape-mips-sdk.imgtec.com/components/toolchain/2015.06-05/ + +The "IMG GNU Linux Toolchain" is capable of building for all current MIPS ISAs, +architecture revisions & both endiannesses. + +-------- + TODO +-------- + + - AHCI support + - CPU driver + - Exception handling (+UHI?) + - Flash support + - IOCU support + - L2 cache support + - More general LCD display driver + - Multi-arch-variant multi-endian fat binary diff --git a/roms/u-boot/doc/README.bus_vcxk b/roms/u-boot/doc/README.bus_vcxk new file mode 100644 index 000000000..aaa1565dd --- /dev/null +++ b/roms/u-boot/doc/README.bus_vcxk @@ -0,0 +1,67 @@ +SPDX-License-Identifier: GPL-2.0+ +/* + * (C) Copyright 2008-2009 + * BuS Elektronik GmbH & Co. KG <www.bus-elektronik.de> + * Jens Scharsig <esw@bus-elektronik.de> + */ + +U-Boot vcxk video controller driver +====================================== + +By defining CONFIG_VIDEO_VCXK this driver can be used with VC2K, VC4K and +VC8K devices on following boards: + +board | ARCH | Vendor +----------------------------------------------------------------------- +EB+CPU5282-T1 | MCF5282 | BuS Elektronik GmbH & Co. KG +EB+MCF-EVB123 | MCF5282 | BuS Elektronik GmbH & Co. KG +EB+CPUx9K2 | AT91RM9200 | BuS Elektronik GmbH & Co. KG +ZLSA | AT91RM9200 | Ruf Telematik AG + +Driver configuration +-------------------- + +The driver needs some defines to describe the target hardware: + +CONFIG_SYS_VCXK_BASE + + base address of VCxK hardware memory + +CONFIG_SYS_VCXK_DEFAULT_LINEALIGN + + defines the physical alignment of a pixel row + +CONFIG_SYS_VCXK_DOUBLEBUFFERED + + some boards that use vcxk prevent read from framebuffer memory. + define this option to enable double buffering (needs 16KiB RAM) + +CONFIG_SYS_VCXK_<xxxx>_PIN + + defines the number of the I/O line PIN in the port + valid values for <xxxx> are: + + ACKNOWLEDGE + describes the acknowledge line from vcxk hardware + + ENABLE + describes the enable line to vcxk hardware + + INVERT + describes the invert line to vcxk hardware + + RESET + describes the reset line to vcxk hardware + + REQUEST + describes the request line to vcxk hardware + +CONFIG_SYS_VCXK_<xxxx>_PORT + + defines the I/O port which is connected with the line + for valid values for <xxxx> see CONFIG_SYS_VCXK_<xxxx>_PIN + +CONFIG_SYS_VCXK_<xxxx>_DDR + + defines the register which configures the direction + for valid values for <xxxx> see CONFIG_SYS_VCXK_<xxxx>_PIN diff --git a/roms/u-boot/doc/README.cfi b/roms/u-boot/doc/README.cfi new file mode 100644 index 000000000..ad5285081 --- /dev/null +++ b/roms/u-boot/doc/README.cfi @@ -0,0 +1,63 @@ +The common CFI driver provides this weak default implementation for +flash_cmd_reset(): + +static void __flash_cmd_reset(flash_info_t *info) +{ + /* + * We do not yet know what kind of commandset to use, so we issue + * the reset command in both Intel and AMD variants, in the hope + * that AMD flash roms ignore the Intel command. + */ + flash_write_cmd(info, 0, 0, AMD_CMD_RESET); + udelay(1); + flash_write_cmd(info, 0, 0, FLASH_CMD_RESET); +} +void flash_cmd_reset(flash_info_t *info) + __attribute__((weak,alias("__flash_cmd_reset"))); + +Some flash chips seem to have trouble with this reset sequence. +In this case, board-specific code can override this weak default +version with a board-specific function. + +At the time of writing, there are two boards that define their own +routine for this. + +First, the digsy_mtc board equipped with the M29W128GH from Numonyx +needs this version to function properly: + +void flash_cmd_reset(flash_info_t *info) +{ + flash_write_cmd(info, 0, 0, AMD_CMD_RESET); +} + +In addition, the t3corp board defines the routine thusly: + +void flash_cmd_reset(flash_info_t *info) +{ + /* + * FLASH at address CONFIG_SYS_FLASH_BASE is a Spansion chip and + * needs the Spansion type reset commands. The other flash chip + * is located behind a FPGA (Xilinx DS617) and needs the Intel type + * reset command. + */ + if (info->start[0] == CONFIG_SYS_FLASH_BASE) + flash_write_cmd(info, 0, 0, AMD_CMD_RESET); + else + flash_write_cmd(info, 0, 0, FLASH_CMD_RESET); +} + +see also: +http://www.mail-archive.com/u-boot@lists.denx.de/msg24368.html + + +Config Option + + CONFIG_SYS_MAX_FLASH_SECT: Number of sectors available on Flash device + + CONFIG_SYS_FLASH_CFI_WIDTH: Data-width of the flash device + + CONFIG_CMD_FLASH: Enables Flash command library + + CONFIG_FLASH_CFI_DRIVER: Enables CFI Flash driver + + CONFIG_FLASH_CFI_MTD: Enables MTD frame work for NOR Flash devices diff --git a/roms/u-boot/doc/README.commands.itest b/roms/u-boot/doc/README.commands.itest new file mode 100644 index 000000000..5e0fe8624 --- /dev/null +++ b/roms/u-boot/doc/README.commands.itest @@ -0,0 +1,16 @@ +A slow day today so here is a revised itest command with provisional +support for comparing strings as well :-)) + +Now table driven to allow the operators +-eq, -ne, -lt, -gt, -le, -ge, ==, !=, <>, <, >, <=, >= + +Uses the expected command modifier for integer compares of width 1, 2 or +4 bytes of .b, .w, .l and the new modifer of .s for a string compare. +String comparison is over the length of the shorter, this hopefully +avoids missing terminators when using an indirect pointer. + +eg. +if itest.l *40000 == 12345678 then; .... +if itest.w *40000 != 1234 then; .... +if itest.b *40000 >= 12 then; .... +if itest.s *40000 -eq hello then; .... diff --git a/roms/u-boot/doc/README.commands.spl b/roms/u-boot/doc/README.commands.spl new file mode 100644 index 000000000..cb3e0c8e0 --- /dev/null +++ b/roms/u-boot/doc/README.commands.spl @@ -0,0 +1,31 @@ +The spl command is used to export a boot parameter image to RAM. Later +it may implement more functions connected to the SPL. + +SUBCOMMAND EXPORT +To execute the command everything has to be in place as if bootm should be +used. (kernel image, initrd-image, fdt-image etc.) + +export has two subcommands: + atags: exports the ATAGS + fdt: exports the FDT + +Call is: +spl export <fdt|atags> [kernel_addr] [initrd_addr] [fdt_addr if fdt] + + +TYPICAL CALL + +on OMAP3: +nandecc hw +nand read 0x82000000 0x280000 0x400000 /* Read kernel image from NAND*/ +spl export atags /* export ATAGS */ +nand erase 0x680000 0x20000 /* erase - one page */ +nand write 0x80000100 0x680000 0x20000 /* write the image - one page */ + +call with FDT: +nandecc hw +nand read 0x82000000 0x280000 0x400000 /* Read kernel image from NAND*/ +tftpboot 0x80000100 devkit8000.dtb /* Read fdt */ +spl export fdt 0x82000000 - 0x80000100 /* export FDT */ +nand erase 0x680000 0x20000 /* erase - one page */ +nand write <adress shown by spl export> 0x680000 0x20000 diff --git a/roms/u-boot/doc/README.console b/roms/u-boot/doc/README.console new file mode 100644 index 000000000..9f5812c89 --- /dev/null +++ b/roms/u-boot/doc/README.console @@ -0,0 +1,100 @@ +SPDX-License-Identifier: GPL-2.0+ +/* + * (C) Copyright 2000 + * Paolo Scaffardi, AIRVENT SAM s.p.a - RIMINI(ITALY), arsenio@tin.it + */ + +U-Boot console handling +======================== + +HOW THE CONSOLE WORKS? +---------------------- + +At system startup U-Boot initializes a serial console. When U-Boot +relocates itself to RAM, all console drivers are initialized (they +will register all detected console devices to the system for further +use). + +If not defined in the environment, the first input device is assigned +to the 'stdin' file, the first output one to 'stdout' and 'stderr'. + +You can use the command "coninfo" to see all registered console +devices and their flags. You can assign a standard file (stdin, +stdout or stderr) to any device you see in that list simply by +assigning its name to the corresponding environment variable. For +example: + + setenv stdin serial <- To use the serial input + setenv stdout video <- To use the video console + +Do a simple "saveenv" to save the console settings in the environment +and get them working on the next startup, too. + +HOW CAN I USE STANDARD FILE INTO THE SOURCES? +--------------------------------------------- + +You can use the following functions to access the console: + +* STDOUT: + putc (to put a char to stdout) + puts (to put a string to stdout) + printf (to format and put a string to stdout) + +* STDIN: + tstc (to test for the presence of a char in stdin) + getc (to get a char from stdin) + +* STDERR: + eputc (to put a char to stderr) + eputs (to put a string to stderr) + eprintf (to format and put a string to stderr) + +* FILE (can be 'stdin', 'stdout', 'stderr'): + fputc (like putc but redirected to a file) + fputs (like puts but redirected to a file) + fprintf (like printf but redirected to a file) + ftstc (like tstc but redirected to a file) + fgetc (like getc but redirected to a file) + +Remember that all FILE-related functions CANNOT be used before +U-Boot relocation (done in 'board_init_r' in arch/*/lib/board.c). + +HOW CAN I USE STANDARD FILE INTO APPLICATIONS? +---------------------------------------------- + +Use the 'bd_mon_fnc' field of the bd_info structure passed to the +application to do everything you want with the console. + +But REMEMBER that that will work only if you have not overwritten any +U-Boot code while loading (or uncompressing) the image of your +application. + +For example, you won't get the console stuff running in the Linux +kernel because the kernel overwrites U-Boot before running. Only +some parameters like the framebuffer descriptors are passed to the +kernel in the high memory area to let the applications (the kernel) +use the framebuffers initialized by U-Boot. + +SUPPORTED DRIVERS +----------------- + +Working drivers: + + serial (architecture dependent serial stuff) + video (mpc8xx video controller) + +Work in progress: + + wl_kbd (Wireless 4PPM keyboard) + +Waiting for volounteers: + + lcd (mpc8xx lcd controller; to ) + +TESTED CONFIGURATIONS +--------------------- + +The driver has been tested with the following configurations (see +CREDITS for other contact informations): + +- MPC823FADS with AD7176 on a PAL TV (YCbYCr) - arsenio@tin.it diff --git a/roms/u-boot/doc/README.davinci b/roms/u-boot/doc/README.davinci new file mode 100644 index 000000000..607531af2 --- /dev/null +++ b/roms/u-boot/doc/README.davinci @@ -0,0 +1,82 @@ +Summary +======= + +Note: this document used to be about the entire family of DaVinci SOCs but the +support for the DM* family and DA830 has since been dropped. + +This README is about U-Boot support for TI's DA850 SoC. This SOC has an OMAP +part number but is very similar to the DaVinci series. + +Currently the following boards are supported: + +* TI DA850 EVM + +* TI OMAP-L138 LCDK + +* Lego EV3 + +Build +===== + +* TI DA850 EVM: + +make da850evm_config +make + +* TI OMAP-L138 LCDK + +make omapl138_lcdk_defconfig +make + +* Lego EV3 + +make legoev3_defconfig +make + +Bootloaders +=============== + +For DA850 an SPL (secondary program loader, see doc/README.SPL) is provided +to load U-Boot from SPI flash, MMC or NAND. The SPL takes care of the low level +initialization. + +The SPL is built as u-boot.ais for all DA850 defconfigs except those booting +from NOR flash. The resulting image file can be programmed to the SPI flash +of the DA850 EVM/LCDK. + +Devices that support booting from NOR utilize execute in place (XIP) and do +not require SPL to perform low level initialization. + +Environment Variables +===================== + +The DA850 EVM allows the user to specify the maximum cpu clock allowed by the +silicon, in Hz, via an environment variable "maxcpuclk". + +The maximum clock rate allowed depends on the silicon populated on the EVM. +Please make sure you understand the restrictions placed on this clock in the +device specific datasheet before setting up this variable. This information is +passed to the Linux kernel using the ATAG_REVISION atag. + +If "maxcpuclk" is not defined, the configuration CONFIG_DA850_EVM_MAX_CPU_CLK +is used to obtain this information. + +Links +===== + +1) TI DA850 EVM +http://focus.ti.com/docs/prod/folders/print/omap-l138.html +http://www.logicpd.com/products/development-kits/zoom-omap-l138-evm-development-kit + +2) TI OMAP-L138 LCDK +http://focus.ti.com/docs/prod/folders/print/omap-l138.html +http://www.ti.com/tool/TMDXLCDK138 + +Davinci special defines +======================= + +CONFIG_SYS_DV_NOR_BOOT_CFG: AM18xx based boards, booting in NOR Boot mode + need a "NOR Boot Configuration Word" stored + in the NOR Flash. This define adds this. + More Info about this, see: + spraba5a.pdf chapter 3.1 diff --git a/roms/u-boot/doc/README.davinci.nand_spl b/roms/u-boot/doc/README.davinci.nand_spl new file mode 100644 index 000000000..f46721a00 --- /dev/null +++ b/roms/u-boot/doc/README.davinci.nand_spl @@ -0,0 +1,141 @@ +With this approach, we don't need the UBL any more on DaVinci boards. +A "make boardname" will compile a u-boot.ubl, with UBL Header, which is +needed for the RBL to find the "UBL", which actually is a UBL-compatible +header, nand spl code and u-boot code. + + +As the RBL uses another read function as the "standard" u-boot, +we need a command, which switches between this two read/write +functions, so we can write the UBL header and the spl +code in a format, which the RBL can read. This is realize +(at the moment in board specific code) in the u-boot command +nandrbl + +nandrbl without arguments returns actual mode (rbl or uboot). +with nandrbl mode (mode = "rbl" or "uboot") you can switch +between the two NAND read/write modes. + + +To set up mkimage you need a config file for mkimage, example: +board/ait/cam_enc_4xx/ublimage.cfg + +For information about the configuration please see: +doc/README.ublimage + +Example for the cam_enc_4xx board: +On the cam_enc_4xx board we have a NAND flash with blocksize = 0x20000 and +pagesize = 0x800, so the u-boot.ubl image (which you get with: +"make cam_enc_4xx") looks like this: + +00000000 00 ed ac a1 20 00 00 00 06 00 00 00 05 00 00 00 |.... ...........| +00000010 00 00 00 00 20 00 00 00 ff ff ff ff ff ff ff ff |.... ...........| +00000020 ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff |................| +* +00000800 14 00 00 ea 14 f0 9f e5 10 f0 9f e5 0c f0 9f e5 |................| +00000810 08 f0 9f e5 04 f0 9f e5 00 f0 9f e5 04 f0 1f e5 |................| +00000820 00 01 00 00 78 56 34 12 78 56 34 12 78 56 34 12 |....xV4.xV4.xV4.| +[...] +* +00001fe0 00 00 00 00 00 00 00 00 ff ff ff ff ff ff ff ff |................| +00001ff0 ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff |................| +* +00003800 14 00 00 ea 14 f0 9f e5 14 f0 9f e5 14 f0 9f e5 |................| +00003810 14 f0 9f e5 14 f0 9f e5 14 f0 9f e5 14 f0 9f e5 |................| +00003820 80 01 08 81 e0 01 08 81 40 02 08 81 a0 02 08 81 |........@.......| + +In the first "page" of the image, we have the UBL Header, needed for +the RBL to find the spl code. + +The spl code starts in the second "page" of the image, with a size +defined by: + +#define CONFIG_SYS_NROF_PAGES_NAND_SPL 6 + +After the spl code, there comes the "real" u-boot code +@ (6 + 1) * pagesize = 0x3800 + +------------------------------------------------------------------------ +Setting up spl code: + +/* + * RBL searches from Block n (n = 1..24) + * so we can define, how many UBL Headers + * we write before the real spl code + */ +#define CONFIG_SYS_NROF_UBL_HEADER 5 +#define CONFIG_SYS_NROF_PAGES_NAND_SPL 6 + +#define CONFIG_SYS_NAND_U_BOOT_OFFS ((CONFIG_SYS_NROF_UBL_HEADER * \ + CONFIG_SYS_NAND_BLOCK_SIZE) + \ + (CONFIG_SYS_NROF_PAGES_NAND_SPL) * \ + CONFIG_SYS_NAND_PAGE_SIZE) +------------------------------------------------------------------------ + +Burning into NAND: + +step 1: +The RBL searches from Block n ( n = 1..24) on page 0 for valid UBL +Headers, so you have to burn the UBL header page from the u-boot.ubl +image to the blocks, you want to have the UBL header. +!! Don;t forget to switch to rbl nand read/write functions with + "nandrbl rbl" + +step 2: +You need to setup in the ublimage.cfg, where the RBL can find the spl +code, and how big it is. + +!! RBL always starts reading from page 0 !! + +For the AIT board, we have: +PAGES 6 +START_BLOCK 5 + +So we need to copy the spl code to block 5 page 0 +!! Don;t forget to switch to rbl nand read/write functions with + "nandrbl rbl" + +step 3: +You need to copy the u-boot image to the block/page +where the spl code reads it (CONFIG_SYS_NAND_U_BOOT_OFFS) +!! Don;t forget to switch to rbl nand read/write functions with + "nandrbl uboot", which is default. + +On the cam_enc_4xx board it is: +#define CONFIG_SYS_NAND_U_BOOT_OFFS (0xc0000) + +-> this results in following NAND usage on the cam_enc_4xx board: + +addr + +20000 possible UBL Header +40000 possible UBL Header +60000 possible UBL Header +80000 possilbe UBL Header +a0000 spl code +c0000 u-boot code + +The above steps are executeed through the following environment vars: +(using 80000 as address for the UBL header) + +pagesz=800 +uboot=/tftpboot/cam_enc_4xx/u-boot.ubl +load=tftp 80000000 ${uboot} +writeheader nandrbl rbl;nand erase 80000 ${pagesz};nand write 80000000 80000 ${pagesz};nandrbl uboot +writenand_spl nandrbl rbl;nand erase a0000 3000;nand write 80000800 a0000 3000;nandrbl uboot +writeuboot nandrbl uboot;nand erase c0000 5d000;nand write 80003800 c0000 5d000 +update=run load writeheader writenand_spl writeuboot + +If you do a "run load update" u-boot, spl + ubl header +are magically updated ;-) + +Note: +- There seem to be a bug in the RBL code (at least on my HW), + In the UBL block, I can set the page to values != 0, so it + is possible to burn step 1 and step 2 in one step into the + flash, but the RBL ignores the page settings, so I have to + burn the UBL Header to a page 0 and the spl code to + a page 0 ... :-( +- If we make the nand read/write functions in the RBL equal to + the functions in u-boot (as I have no RBL code, it is only + possible in u-boot), we could burn the complete image in + one step ... that would be nice ... diff --git a/roms/u-boot/doc/README.dfutftp b/roms/u-boot/doc/README.dfutftp new file mode 100644 index 000000000..a3341bbb6 --- /dev/null +++ b/roms/u-boot/doc/README.dfutftp @@ -0,0 +1,118 @@ +# SPDX-License-Identifier: GPL-2.0+ +# +# Copyright (C) 2015 +# +# Lukasz Majewski <l.majewski@majess.pl> + +Device Firmware Upgrade (DFU) - extension to use TFTP +===================================================== + +Why? +---- + +* Update TFTP (CONFIG_UPDATE_TFTP) only supports writing +code to NAND memory via TFTP. +* DFU supports writing data to the variety of mediums (NAND, +eMMC, SD, partitions, RAM, etc) via USB. + +Combination of both solves their shortcomings! + + +Overview +-------- + +This document briefly describes how to use DFU for +upgrading firmware (e.g. kernel, u-boot, rootfs, etc.) +via TFTP protocol. + +By using Ethernet (TFTP protocol to be precise) it is +possible to overcome the major problem of USB based DFU - +the relatively low transfer speed for large files. +This was caused by DFU standard, which imposed utilization +of only EP0 for transfer. By using Ethernet we can circumvent +this shortcoming. + +Beagle Bone Black rev. C (BBB) powered by TI's am335x CPU has +been used as a demo board. + +To utilize this feature, one needs to first enable support +for USB based DFU (CONFIG_DFU_*) and DFU TFTP update +(CONFIG_DFU_TFTP) described in ./doc/README.update. + +The "dfu" command has been extended to support transfer via TFTP - one +needs to type for example "dfu tftp 0 mmc 0" + +As of this writing (SHA1:8d77576371381ade83de475bb639949b44941e8c v2015.10-rc2) +the update.c code is not enabled (CONFIG_UPDATE_TFTP) by any board in the +contemporary u-boot tree. + + +Environment variables +--------------------- + +The "dfu tftp" command can be used in the "preboot" environment variable +(when it is enabled by defining CONFIG_PREBOOT). +This is the preferable way of using this command in the early boot stage +as opposed to legacy update_tftp() function invocation. + + +Beagle Bone Black (BBB) setup +----------------------------- + +1. Setup tftp env variables: + * select desired eth device - 'ethact' variable ["ethact=cpsw"] + (use "bdinfo" to check current setting) + * setup "serverip" and "ipaddr" variables + * set "loadaddr" as a fixed buffer where incoming data is placed + ["loadaddr=0x81000000"] + +######### +# BONUS # +######### +It is possible to use USB interface to emulate ETH connection by setting +"ethact=usb_ether". In this way one can have very fast DFU transfer via USB. + +For 33MiB test image the transfer rate was 1MiB/s for ETH over USB and 200KiB/s +for pure DFU USB transfer. + +2. Setup update_tftp variables: + * set "updatefile" - the file name to be downloaded via TFTP (stored on + the HOST at e.g. /srv/tftp) + +3. If required, to update firmware on boot, put the "dfu tftp 0 mmc 0" in the + "preboot" env variable. Otherwise use this command from u-boot prompt. + +4. Inspect "dfu" specific variables: + * "dfu_alt_info" - information about available DFU entities + * "dfu_bufsiz" - variable to set buffer size [in bytes] - when it is not + possible to set large enough default buffer (8 MiB @ BBB) + + + +FIT image format for download +----------------------------- + +To create FIT image for download one should follow the update tftp README file +(./doc/README.update) with one notable difference: + +The original snippet of ./doc/uImage.FIT/update_uboot.its + + images { + update@1 { + description = "U-Boot binary"; + +should look like + + images { + u-boot.bin@1 { + description = "U-Boot binary"; + +where "u-boot.bin" is the DFU entity name to be stored. + + + +To do +----- + +* Extend dfu-util command to support TFTP based transfers +* Upload support (via TFTP) diff --git a/roms/u-boot/doc/README.displaying-bmps b/roms/u-boot/doc/README.displaying-bmps new file mode 100644 index 000000000..331154166 --- /dev/null +++ b/roms/u-boot/doc/README.displaying-bmps @@ -0,0 +1,27 @@ +If you are experiencing hangups/data-aborts when trying to display a BMP image, +the following might be relevant to your situation... + +Some architectures cannot handle unaligned memory accesses, and an attempt to +perform one will lead to a data abort. On such architectures it is necessary to +make sure all data is properly aligned, and in many situations simply choosing +a 32 bit aligned address is enough to ensure proper alignment. This is not +always the case when dealing with data that has an internal layout such as a +BMP image: + +BMP images have a header that starts with 2 byte-size fields followed by mostly +32 bit fields. The packed struct that represents this header can be seen below: + +typedef struct bmp_header { + /* Header */ + char signature[2]; + __u32 file_size; + __u32 reserved; + __u32 data_offset; + ... etc +} __attribute__ ((packed)) bmp_header_t; + +When placed in an aligned address such as 0x80a00000, char signature offsets +the __u32 fields into unaligned addresses (in our example 0x80a00002, +0x80a00006, and so on...). When these fields are accessed by U-Boot, a 32 bit +access is generated at a non-32-bit-aligned address, causing a data abort. +The proper alignment for BMP images is therefore: 32-bit-aligned-address + 2. diff --git a/roms/u-boot/doc/README.distro b/roms/u-boot/doc/README.distro new file mode 100644 index 000000000..c4f041ca7 --- /dev/null +++ b/roms/u-boot/doc/README.distro @@ -0,0 +1,430 @@ +SPDX-License-Identifier: GPL-2.0+ +/* + * (C) Copyright 2014 Red Hat Inc. + * Copyright (c) 2014-2015, NVIDIA CORPORATION. All rights reserved. + * Copyright (C) 2015 K. Merker <merker@debian.org> + */ + +Generic Distro Configuration Concept +==================================== + +Linux distributions are faced with supporting a variety of boot mechanisms, +environments or bootloaders (PC BIOS, EFI, U-Boot, Barebox, ...). This makes +life complicated. Worse, bootloaders such as U-Boot have a configurable set +of features, and each board chooses to enable a different set of features. +Hence, distros typically need to have board-specific knowledge in order to +set up a bootable system. + +This document defines a common set of U-Boot features that are required for +a distro to support the board in a generic fashion. Any board wishing to +allow distros to install and boot in an out-of-the-box fashion should enable +all these features. Linux distros can then create a single set of boot +support/install logic that targets these features. This will allow distros +to install on many boards without the need for board-specific logic. + +In fact, some of these features can be implemented by any bootloader, thus +decoupling distro install/boot logic from any knowledge of the bootloader. + +This model assumes that boards will load boot configuration files from a +regular storage mechanism (eMMC, SD card, USB Disk, SATA disk, etc.) with +a standard partitioning scheme (MBR, GPT). Boards that cannot support this +storage model are outside the scope of this document, and may still need +board-specific installer/boot-configuration support in a distro. + +To some extent, this model assumes that a board has a separate boot flash +that contains U-Boot, and that the user has somehow installed U-Boot to this +flash before running the distro installer. Even on boards that do not conform +to this aspect of the model, the extent of the board-specific support in the +distro installer logic would be to install a board-specific U-Boot package to +the boot partition during installation. This distro-supplied U-Boot can still +implement the same features as on any other board, and hence the distro's boot +configuration file generation logic can still be board-agnostic. + +Locating Bootable Disks +----------------------- + +Typical desktop/server PCs search all (or a user-defined subset of) attached +storage devices for a bootable partition, then load the bootloader or boot +configuration files from there. A U-Boot board port that enables the features +mentioned in this document will search for boot configuration files in the +same way. + +Thus, distros do not need to manipulate any kind of bootloader-specific +configuration data to indicate which storage device the system should boot +from. + +Distros simply need to install the boot configuration files (see next +section) in an ext2/3/4 or FAT partition, mark the partition bootable (via +the MBR bootable flag, or GPT legacy_bios_bootable attribute), and U-Boot (or +any other bootloader) will find those boot files and execute them. This is +conceptually identical to creating a grub2 configuration file on a desktop +PC. + +Note that in the absence of any partition that is explicitly marked bootable, +U-Boot falls back to searching the first valid partition of a disk for boot +configuration files. Other bootloaders are recommended to do the same, since +I believe that partition table bootable flags aren't so commonly used outside +the realm of x86 PCs. + +U-Boot can also search for boot configuration files from a TFTP server. + +Boot Configuration Files +------------------------ + +The standard format for boot configuration files is that of extlinux.conf, as +handled by U-Boot's "syslinux" (disk) or "pxe boot" (network). This is roughly +as specified at: + +http://www.freedesktop.org/wiki/Specifications/BootLoaderSpec/ + +... with the exceptions that the BootLoaderSpec document: + +* Prescribes a separate configuration per boot menu option, whereas U-Boot + lumps all options into a single extlinux.conf file. Hence, U-Boot searches + for /extlinux/extlinux.conf then /boot/extlinux/extlinux.conf on disk, or + pxelinux.cfg/default over the network. + +* Does not document the fdtdir option, which automatically selects the DTB to + pass to the kernel. + +One example extlinux.conf generated by the Fedora installer is: + +------------------------------------------------------------ +# extlinux.conf generated by anaconda + +ui menu.c32 + +menu autoboot Welcome to Fedora. Automatic boot in # second{,s}. Press a key for options. +menu title Fedora Boot Options. +menu hidden + +timeout 50 +#totaltimeout 9000 + +default Fedora (3.17.0-0.rc4.git2.1.fc22.armv7hl+lpae) 22 (Rawhide) + +label Fedora (3.17.0-0.rc4.git2.1.fc22.armv7hl) 22 (Rawhide) + kernel /boot/vmlinuz-3.17.0-0.rc4.git2.1.fc22.armv7hl + append ro root=UUID=8eac677f-8ea8-4270-8479-d5ddbb797450 console=ttyS0,115200n8 LANG=en_US.UTF-8 drm.debug=0xf + fdtdir /boot/dtb-3.17.0-0.rc4.git2.1.fc22.armv7hl + initrd /boot/initramfs-3.17.0-0.rc4.git2.1.fc22.armv7hl.img + +label Fedora (3.17.0-0.rc4.git2.1.fc22.armv7hl+lpae) 22 (Rawhide) + kernel /boot/vmlinuz-3.17.0-0.rc4.git2.1.fc22.armv7hl+lpae + append ro root=UUID=8eac677f-8ea8-4270-8479-d5ddbb797450 console=ttyS0,115200n8 LANG=en_US.UTF-8 drm.debug=0xf + fdtdir /boot/dtb-3.17.0-0.rc4.git2.1.fc22.armv7hl+lpae + initrd /boot/initramfs-3.17.0-0.rc4.git2.1.fc22.armv7hl+lpae.img + +label Fedora-0-rescue-8f6ba7b039524e0eb957d2c9203f04bc (0-rescue-8f6ba7b039524e0eb957d2c9203f04bc) + kernel /boot/vmlinuz-0-rescue-8f6ba7b039524e0eb957d2c9203f04bc + initrd /boot/initramfs-0-rescue-8f6ba7b039524e0eb957d2c9203f04bc.img + append ro root=UUID=8eac677f-8ea8-4270-8479-d5ddbb797450 console=ttyS0,115200n8 + fdtdir /boot/dtb-3.16.0-0.rc6.git1.1.fc22.armv7hl+lpae +------------------------------------------------------------ + +Another hand-crafted network boot configuration file is: + +------------------------------------------------------------ +TIMEOUT 100 + +MENU TITLE TFTP boot options + +LABEL jetson-tk1-emmc + MENU LABEL ../zImage root on Jetson TK1 eMMC + LINUX ../zImage + FDTDIR ../ + APPEND console=ttyS0,115200n8 console=tty1 loglevel=8 rootwait rw earlyprintk root=PARTUUID=80a5a8e9-c744-491a-93c1-4f4194fd690b + +LABEL venice2-emmc + MENU LABEL ../zImage root on Venice2 eMMC + LINUX ../zImage + FDTDIR ../ + APPEND console=ttyS0,115200n8 console=tty1 loglevel=8 rootwait rw earlyprintk root=PARTUUID=5f71e06f-be08-48ed-b1ef-ee4800cc860f + +LABEL sdcard + MENU LABEL ../zImage, root on 2GB sdcard + LINUX ../zImage + FDTDIR ../ + APPEND console=ttyS0,115200n8 console=tty1 loglevel=8 rootwait rw earlyprintk root=PARTUUID=b2f82cda-2535-4779-b467-094a210fbae7 + +LABEL fedora-installer-fk + MENU LABEL Fedora installer w/ Fedora kernel + LINUX fedora-installer/vmlinuz + INITRD fedora-installer/initrd.img.orig + FDTDIR fedora-installer/dtb + APPEND loglevel=8 ip=dhcp inst.repo=http://10.0.0.2/mirrors/fedora/linux/development/rawhide/armhfp/os/ rd.shell cma=64M +------------------------------------------------------------ + +U-Boot Implementation +===================== + +Enabling the distro options +--------------------------- + +In your board's defconfig, enable the DISTRO_DEFAULTS option by adding +a line with "CONFIG_DISTRO_DEFAULTS=y". If you want to enable this +from Kconfig itself, for e.g. all boards using a specific SoC then +add a "imply DISTRO_DEFAULTS" to your SoC CONFIG option. + +In your board configuration file, include the following: + +------------------------------------------------------------ +#ifndef CONFIG_SPL_BUILD +#include <config_distro_bootcmd.h> +#endif +------------------------------------------------------------ + +The first of those headers primarily enables a core set of U-Boot features, +such as support for MBR and GPT partitions, ext* and FAT filesystems, booting +raw zImage and initrd (rather than FIT- or uImage-wrapped files), etc. Network +boot support is also enabled here, which is useful in order to boot distro +installers given that distros do not commonly distribute bootable install +media for non-PC targets at present. + +Finally, a few options that are mostly relevant only when using U-Boot- +specific boot.scr scripts are enabled. This enables distros to generate a +U-Boot-specific boot.scr script rather than extlinux.conf as the boot +configuration file. While doing so is fully supported, and +CONFIG_DISTRO_DEFAULTS exposes enough parameterization to boot.scr to +allow for board-agnostic boot.scr content, this document recommends that +distros generate extlinux.conf rather than boot.scr. extlinux.conf is intended +to work across multiple bootloaders, whereas boot.scr will only work with +U-Boot. TODO: document the contract between U-Boot and boot.scr re: which +environment variables a generic boot.scr may rely upon. + +The second of those headers sets up the default environment so that $bootcmd +is defined in a way that searches attached disks for boot configuration files, +and executes them if found. + +Required Environment Variables +------------------------------ + +The U-Boot "syslinux" and "pxe boot" commands require a number of environment +variables be set. Default values for these variables are often hard-coded into +CONFIG_EXTRA_ENV_SETTINGS in the board's U-Boot configuration file, so that +the user doesn't have to configure them. + +fdt_addr: + + Mandatory for any system that provides the DTB in HW (e.g. ROM) and wishes + to pass that DTB to Linux, rather than loading a DTB from the boot + filesystem. Prohibited for any other system. + + If specified a DTB to boot the system must be available at the given + address. + +fdt_addr_r: + + Mandatory. The location in RAM where the DTB will be loaded or copied to when + processing the fdtdir/devicetreedir or fdt/devicetree options in + extlinux.conf. + + This is mandatory even when fdt_addr is provided, since extlinux.conf must + always be able to provide a DTB which overrides any copy provided by the HW. + + A size of 1MB for the FDT/DTB seems reasonable. + +fdtfile: + + Mandatory. the name of the DTB file for the specific board for instance + the espressobin v5 board the value is "marvell/armada-3720-espressobin.dtb" + while on a clearfog pro it is "armada-388-clearfog-pro.dtb" in the case of + a board providing its firmware based DTB this value can be used to override + the DTB with a different DTB. fdtfile will automatically be set for you if + it matches the format ${soc}-${board}.dtb which covers most 32 bit use cases. + AArch64 generally does not match as the Linux kernel put the dtb files under + SoC vendor directories. + +ramdisk_addr_r: + + Mandatory. The location in RAM where the initial ramdisk will be loaded to + when processing the initrd option in extlinux.conf. + + It is recommended that this location be highest in RAM out of fdt_addr_, + kernel_addr_r, and ramdisk_addr_r, so that the RAM disk can vary in size + and use any available RAM. + +kernel_addr_r: + + Mandatory. The location in RAM where the kernel will be loaded to when + processing the kernel option in the extlinux.conf. + + The kernel should be located within the first 128M of RAM in order for the + kernel CONFIG_AUTO_ZRELADDR option to work, which is likely enabled on any + distro kernel. Since the kernel will decompress itself to 0x8000 after the + start of RAM, kernel_addr_r should not overlap that area, or the kernel will + have to copy itself somewhere else first before decompression. + + A size of 16MB for the kernel is likely adequate. + +kernel_comp_addr_r: + Optional. This is only required if user wants to boot Linux from a compressed + Image(.gz, .bz2, .lzma, .lzo) using the booti command. It represents the + location in RAM where the compressed Image will be decompressed temporarily. + Once the decompression is complete, the decompressed data will be moved to + kernel_addr_r for booting. + +kernel_comp_size: + Optional. This is only required if user wants to boot Linux from a compressed + Image using booti command. It represents the size of the compressed file. The + size has to at least the size of loaded image for decompression to succeed. + +pxefile_addr_r: + + Mandatory. The location in RAM where extlinux.conf will be loaded to prior + to processing. + + A size of 1MB for extlinux.conf is more than adequate. + +scriptaddr: + + Mandatory, if the boot script is boot.scr rather than extlinux.conf. The + location in RAM where boot.scr will be loaded to prior to execution. + + A size of 1MB for extlinux.conf is more than adequate. + +For suggestions on memory locations for ARM systems, you must follow the +guidelines specified in Documentation/arm/Booting in the Linux kernel tree. + +For a commented example of setting these values, please see the definition of +MEM_LAYOUT_ENV_SETTINGS in include/configs/tegra124-common.h. + +Boot Target Configuration +------------------------- + +<config_distro_bootcmd.h> defines $bootcmd and many helper command variables +that automatically search attached disks for boot configuration files and +execute them. Boards must provide configure <config_distro_bootcmd.h> so that +it supports the correct set of possible boot device types. To provide this +configuration, simply define macro BOOT_TARGET_DEVICES prior to including +<config_distro_bootcmd.h>. For example: + +------------------------------------------------------------ +#ifndef CONFIG_SPL_BUILD +#define BOOT_TARGET_DEVICES(func) \ + func(MMC, mmc, 1) \ + func(MMC, mmc, 0) \ + func(USB, usb, 0) \ + func(PXE, pxe, na) \ + func(DHCP, dhcp, na) +#include <config_distro_bootcmd.h> +#endif +------------------------------------------------------------ + +Each entry in the macro defines a single boot device (e.g. a specific eMMC +device or SD card) or type of boot device (e.g. USB disk). The parameters to +the func macro (passed in by the internal implementation of the header) are: + +- Upper-case disk type (MMC, SATA, SCSI, IDE, USB, DHCP, PXE, VIRTIO). +- Lower-case disk type (same options as above). +- ID of the specific disk (MMC only) or ignored for other types. + +User Configuration +================== + +Once the user has installed U-Boot, it is expected that the environment will +be reset to the default values in order to enable $bootcmd and friends, as set +up by <config_distro_bootcmd.h>. After this, various environment variables may +be altered to influence the boot process: + +boot_targets: + + The list of boot locations searched. + + Example: mmc0, mmc1, usb, pxe + + Entries may be removed or re-ordered in this list to affect the boot order. + +boot_prefixes: + + For disk-based booting, the list of directories within a partition that are + searched for boot configuration files (extlinux.conf, boot.scr). + + Example: / /boot/ + + Entries may be removed or re-ordered in this list to affect the set of + directories which are searched. + +boot_scripts: + + The name of U-Boot style boot.scr files that $bootcmd searches for. + + Example: boot.scr.uimg boot.scr + + (Typically we expect extlinux.conf to be used, but execution of boot.scr is + maintained for backwards-compatibility.) + + Entries may be removed or re-ordered in this list to affect the set of + filenames which are supported. + +scan_dev_for_extlinux: + + If you want to disable extlinux.conf on all disks, set the value to something + innocuous, e.g. setenv scan_dev_for_extlinux true. + +scan_dev_for_scripts: + + If you want to disable boot.scr on all disks, set the value to something + innocuous, e.g. setenv scan_dev_for_scripts true. + +boot_net_usb_start: + + If you want to prevent USB enumeration by distro boot commands which execute + network operations, set the value to something innocuous, e.g. setenv + boot_net_usb_start true. This would be useful if you know your Ethernet + device is not attached to USB, and you wish to increase boot speed by + avoiding unnecessary actions. + +boot_net_pci_enum: + + If you want to prevent PCI enumeration by distro boot commands which execute + network operations, set the value to something innocuous, e.g. setenv + boot_net_pci_enum true. This would be useful if you know your Ethernet + device is not attached to PCI, and you wish to increase boot speed by + avoiding unnecessary actions. + +Interactively booting from a specific device at the u-boot prompt +================================================================= + +For interactively booting from a user-selected device at the u-boot command +prompt, the environment provides predefined bootcmd_<target> variables for +every target defined in boot_targets, which can be run be the user. + +If the target is a storage device, the format of the target is always +<device type><device number>, e.g. mmc0. Specifying the device number is +mandatory for storage devices, even if only support for a single instance +of the storage device is actually implemented. + +For network targets (dhcp, pxe), only the device type gets specified; +they do not have a device number. + +Examples: + + - run bootcmd_usb0 + boots from the first USB mass storage device + + - run bootcmd_mmc1 + boots from the second MMC device + + - run bootcmd_pxe + boots by tftp using a pxelinux.cfg + +The list of possible targets consists of: + +- network targets + * dhcp + * pxe + +- storage targets (to which a device number must be appended) + * mmc + * sata + * scsi + * ide + * usb + * virtio + +Other *boot* variables than the ones defined above are only for internal use +of the boot environment and are not guaranteed to exist or work in the same +way in future u-boot versions. In particular the <device type>_boot +variables (e.g. mmc_boot, usb_boot) are a strictly internal implementation +detail and must not be used as a public interface. diff --git a/roms/u-boot/doc/README.dns b/roms/u-boot/doc/README.dns new file mode 100644 index 000000000..8dff454b1 --- /dev/null +++ b/roms/u-boot/doc/README.dns @@ -0,0 +1,62 @@ +Domain Name System +------------------------------------------- + +The Domain Name System (DNS) is a hierarchical naming system for computers, +services, or any resource participating in the Internet. It associates various +information with domain names assigned to each of the participants. Most +importantly, it translates domain names meaningful to humans into the numerical +(binary) identifiers associated with networking equipment for the purpose of +locating and addressing these devices world-wide. An often used analogy to +explain the Domain Name System is that it serves as the "phone book" for the +Internet by translating human-friendly computer hostnames into IP addresses. +For example, www.example.com translates to 208.77.188.166. + +For more information on DNS - http://en.wikipedia.org/wiki/Domain_Name_System + +U-Boot and DNS +------------------------------------------ + +CONFIG_CMD_DNS - controls if the 'dns' command is compiled in. If it is, it + will send name lookups to the dns server (env var 'dnsip') + Turning this option on will about abou 1k to U-Boot's size. + + Example: + +bfin> print dnsip +dnsip=192.168.0.1 + +bfin> dns www.google.com +66.102.1.104 + + By default, dns does nothing except print the IP number on + the default console - which by itself, would be pretty + useless. Adding a third argument to the dns command will + use that as the environment variable to be set. + + Example: + +bfin> print googleip +## Error: "googleip" not defined +bfin> dns www.google.com googleip +64.233.161.104 +bfin> print googleip +googleip=64.233.161.104 +bfin> ping ${googleip} +Using Blackfin EMAC device +host 64.233.161.104 is alive + + In this way, you can lookup, and set many more meaningful + things. + +bfin> sntp +ntpserverip not set +bfin> dns pool.ntp.org ntpserverip +72.18.205.156 +bfin> sntp +Date: 2009-07-18 Time: 4:06:57 + + For some helpful things that can be related to DNS in U-Boot, + look at the top level README for these config options: + CONFIG_CMD_DHCP + CONFIG_BOOTP_DNS + CONFIG_BOOTP_DNS2 diff --git a/roms/u-boot/doc/README.enetaddr b/roms/u-boot/doc/README.enetaddr new file mode 100644 index 000000000..5baa9f217 --- /dev/null +++ b/roms/u-boot/doc/README.enetaddr @@ -0,0 +1,118 @@ +--------------------------------- + Ethernet Address (MAC) Handling +--------------------------------- + +There are a variety of places in U-Boot where the MAC address is used, parsed, +and stored. This document covers proper usage of each location and the moving +of data between them. + +----------- + Locations +----------- + +Here are the places where MAC addresses might be stored: + + - board-specific location (eeprom, dedicated flash, ...) + Note: only used when mandatory due to hardware design etc... + + - environment ("ethaddr", "eth1addr", ...) + Note: this is the preferred way to permanently store MAC addresses + + - ethernet data (struct eth_device -> enetaddr) + Note: these are temporary copies of the MAC address which exist only + after the respective init steps have run and only to make usage + in other places easier (to avoid constant env lookup/parsing) + + - struct bd_info and/or device tree + Note: these are temporary copies of the MAC address only for the + purpose of passing this information to an OS kernel we are about + to boot + +Correct flow of setting up the MAC address (summarized): + +1. Read from hardware in initialize() function +2. Read from environment in net/eth.c after initialize() +3. The environment variable will be compared to the driver initialized + struct eth_device->enetaddr. If they differ, a warning is printed, and the + environment variable will be used unchanged. + If the environment variable is not set, it will be initialized from + eth_device->enetaddr, and a warning will be printed. + If both are invalid and CONFIG_NET_RANDOM_ETHADDR is defined, a random, + locally-assigned MAC is written to eth_device->enetaddr. +4. Program the address into hardware if the following conditions are met: + a) The relevant driver has a 'write_addr' function + b) The user hasn't set an 'ethmacskip' environment variable + c) The address is valid (unicast, not all-zeros) + +Previous behavior had the MAC address always being programmed into hardware +in the device's init() function. + +------- + Usage +------- + +If the hardware design mandates that the MAC address is stored in some special +place (like EEPROM etc...), then the board specific init code (such as the +board-specific misc_init_r() function) is responsible for locating the MAC +address(es) and initializing the respective environment variable(s) from it. +Note that this shall be done if, and only if, the environment does not already +contain these environment variables, i.e. existing variable definitions must +not be overwritten. + +During runtime, the ethernet layer will use the environment variables to sync +the MAC addresses to the ethernet structures. All ethernet driver code should +then only use the enetaddr member of the eth_device structure. This is done +on every network command, so the ethernet copies will stay in sync. + +Any other code that wishes to access the MAC address should query the +environment directly. The helper functions documented below should make +working with this storage much smoother. + +--------- + Helpers +--------- + +To assist in the management of these layers, a few helper functions exist. You +should use these rather than attempt to do any kind of parsing/manipulation +yourself as many common errors have arisen in the past. + + * void string_to_enetaddr(const char *addr, uchar *enetaddr); + +Convert a string representation of a MAC address to the binary version. +char *addr = "00:11:22:33:44:55"; +uchar enetaddr[6]; +string_to_enetaddr(addr, enetaddr); +/* enetaddr now equals { 0x00, 0x11, 0x22, 0x33, 0x44, 0x55 } */ + + * int eth_env_get_enetaddr(char *name, uchar *enetaddr); + +Look up an environment variable and convert the stored address. If the address +is valid, then the function returns 1. Otherwise, the function returns 0. In +all cases, the enetaddr memory is initialized. If the env var is not found, +then it is set to all zeros. The common function is_valid_ethaddr() is used +to determine address validity. +uchar enetaddr[6]; +if (!eth_env_get_enetaddr("ethaddr", enetaddr)) { + /* "ethaddr" is not set in the environment */ + ... try and setup "ethaddr" in the env ... +} +/* enetaddr is now set to the value stored in the ethaddr env var */ + + * int eth_env_set_enetaddr(char *name, const uchar *enetaddr); + +Store the MAC address into the named environment variable. The return value is +the same as the env_set() function. +uchar enetaddr[6] = { 0x00, 0x11, 0x22, 0x33, 0x44, 0x55 }; +eth_env_set_enetaddr("ethaddr", enetaddr); +/* the "ethaddr" env var should now be set to "00:11:22:33:44:55" */ + + * the %pM format modifier + +The %pM format modifier can be used with any standard printf function to format +the binary 6 byte array representation of a MAC address. +uchar enetaddr[6] = { 0x00, 0x11, 0x22, 0x33, 0x44, 0x55 }; +printf("The MAC is %pM\n", enetaddr); + +char buf[20]; +sprintf(buf, "%pM", enetaddr); +/* the buf variable is now set to "00:11:22:33:44:55" */ diff --git a/roms/u-boot/doc/README.esbc_validate b/roms/u-boot/doc/README.esbc_validate new file mode 100644 index 000000000..540923215 --- /dev/null +++ b/roms/u-boot/doc/README.esbc_validate @@ -0,0 +1,40 @@ +SPDX-License-Identifier: GPL-2.0+ +/* + * (C) Copyright 2015 + */ + +esbc_validate command +======================================== + +1. esbc_validate command is meant for validating header and + signature of images (Boot Script and ESBC uboot client). + SHA-256 and RSA operations are performed using SEC block in HW. + This command works on both PBL based and Non PBL based Freescale + platforms. + Command usage: + esbc_validate img_hdr_addr [pub_key_hash] + esbc_validate hdr_addr <hash_val> + Validates signature using RSA verification. + $hdr_addr Address of header of the image to be validated. + $hash_val -Optional. It provides Hash of public/srk key to be + used to verify signature. + +2. ESBC uboot client can be linux. Additionally, rootfs and device + tree blob can also be signed. +3. In the event of header or signature failure in validation, + ITS and ITF bits determine further course of action. +4. In case of soft failure, appropriate error is dumped on console. +5. In case of hard failure, SoC is issued RESET REQUEST after + dumping error on the console. +6. KEY REVOCATION Feature: + QorIQ platforms like B4/T4 have support of srk key table and key + revocation in ISBC code in Silicon. + The srk key table allows the user to have a key table with multiple + keys and revoke any key in case of particular key gets compromised. + In case the ISBC code uses the key revocation and srk key table to + verify the u-boot code, the subsequent chain of trust should also + use the same. +6. ISBC KEY EXTENSION Feature: + This feature allows large number of keys to be used for esbc validation + of images. A set of public keys is being signed and validated by ISBC + which can be further used for esbc validation of images. diff --git a/roms/u-boot/doc/README.ext4 b/roms/u-boot/doc/README.ext4 new file mode 100644 index 000000000..8ecd21eee --- /dev/null +++ b/roms/u-boot/doc/README.ext4 @@ -0,0 +1,83 @@ +U-Boot supports access of both ext2 and ext4 filesystems, either in read-only +mode or in read-write mode. + +First, to enable support for both ext4 (and, automatically, ext2 as well), +but without selecting the corresponding commands, enable one of the following: + + CONFIG_FS_EXT4 (for read-only) + CONFIG_EXT4_WRITE (for read-write) + +Next, to select the ext2-related commands: + + * ext2ls + * ext2load + +or ext4-related commands: + + * ext4size + * ext4ls + * ext4load + +use one or both of: + + CONFIG_CMD_EXT2 + CONFIG_CMD_EXT4 + +Selecting either of the above automatically selects CONFIG_FS_EXT4 if it +wasn't enabled already. + +In addition, to get the write access command "ext4write", enable: + + CONFIG_CMD_EXT4_WRITE + +which automatically selects CONFIG_EXT4_WRITE if it wasn't defined +already. + +Also relevant are the generic filesystem commands, selected by: + + CONFIG_CMD_FS_GENERIC + +This does not automatically enable EXT4 support for you, you still need +to do that yourself. + +Some sample commands to test ext4 support: + +1. Check that the commands can be seen in the output of U-Boot help: + + UBOOT #help + ... + ext4load- load binary file from a Ext4 file system + ext4ls - list files in a directory (default /) + ext4size - determine a file's size + ext4write- create a file in ext4 formatted partition + ... + +2. To list the files in an ext4-formatted partition, run: + + ext4ls <interface> <dev[:part]> [directory] + + For example: + UBOOT #ext4ls mmc 0:5 /usr/lib + +3. To read and load a file from an ext4-formatted partition to RAM, run: + + ext4load <interface> <dev[:part]> [addr] [filename] [bytes] + + For example: + UBOOT #ext4load mmc 2:2 0x30007fc0 uImage + +4. To write a file to an ext4-formatted partition. + + a) First load a file to RAM at a particular address for example 0x30007fc0. + Now execute ext4write command: + ext4write <interface> <dev[:part]> [filename] [Address] [sizebytes] + + For example: + UBOOT #ext4write mmc 2:2 /boot/uImage 0x30007fc0 6183120 + (here 6183120 is the size of the file to be written) + Note: Absolute path is required for the file to be written + +References : + -- ext4 implementation in Linux Kernel + -- Uboot existing ext2 load and ls implementation + -- Journaling block device JBD2 implementation in linux Kernel diff --git a/roms/u-boot/doc/README.falcon b/roms/u-boot/doc/README.falcon new file mode 100644 index 000000000..713d7063a --- /dev/null +++ b/roms/u-boot/doc/README.falcon @@ -0,0 +1,232 @@ +U-Boot Falcon Mode +==================== + +Introduction +------------ + +This document provides an overview of how to add support for Falcon Mode +to a board. + +Falcon Mode is introduced to speed up the booting process, allowing +to boot a Linux kernel (or whatever image) without a full blown U-Boot. + +Falcon Mode relies on the SPL framework. In fact, to make booting faster, +U-Boot is split into two parts: the SPL (Secondary Program Loader) and U-Boot +image. In most implementations, SPL is used to start U-Boot when booting from +a mass storage, such as NAND or SD-Card. SPL has now support for other media, +and can generally be seen as a way to start an image performing the minimum +required initialization. SPL mainly initializes the RAM controller, and then +copies U-Boot image into the memory. + +The Falcon Mode extends this way allowing to start the Linux kernel directly +from SPL. A new command is added to U-Boot to prepare the parameters that SPL +must pass to the kernel, using ATAGS or Device Tree. + +In normal mode, these parameters are generated each time before +loading the kernel, passing to Linux the address in memory where +the parameters can be read. +With Falcon Mode, this snapshot can be saved into persistent storage and SPL is +informed to load it before running the kernel. + +To boot the kernel, these steps under a Falcon-aware U-Boot are required: + +1. Boot the board into U-Boot. +After loading the desired legacy-format kernel image into memory (and DT as +well, if used), use the "spl export" command to generate the kernel parameters +area or the DT. U-Boot runs as when it boots the kernel, but stops before +passing the control to the kernel. + +2. Save the prepared snapshot into persistent media. +The address where to save it must be configured into board configuration +file (CONFIG_CMD_SPL_NAND_OFS for NAND). + +3. Boot the board into Falcon Mode. SPL will load the kernel and copy +the parameters which are saved in the persistent area to the required address. +If a valid uImage is not found at the defined location, U-Boot will be +booted instead. + +It is required to implement a custom mechanism to select if SPL loads U-Boot +or another image. + +The value of a GPIO is a simple way to operate the selection, as well as +reading a character from the SPL console if CONFIG_SPL_CONSOLE is set. + +Falcon Mode is generally activated by setting CONFIG_SPL_OS_BOOT. This tells +SPL that U-Boot is not the only available image that SPL is able to start. + +Configuration +---------------------------- +CONFIG_CMD_SPL Enable the "spl export" command. + The command "spl export" is then available in U-Boot + mode +CONFIG_SYS_SPL_ARGS_ADDR Address in RAM where the parameters must be + copied by SPL. + In most cases, it is <start_of_ram> + 0x100 + +CONFIG_SYS_NAND_SPL_KERNEL_OFFS Offset in NAND where the kernel is stored + +CONFIG_CMD_SPL_NAND_OFS Offset in NAND where the parameters area was saved. + +CONFIG_CMD_SPL_NOR_OFS Offset in NOR where the parameters area was saved. + +CONFIG_CMD_SPL_WRITE_SIZE Size of the parameters area to be copied + +CONFIG_SPL_OS_BOOT Activate Falcon Mode. + +Function that a board must implement +------------------------------------ + +void spl_board_prepare_for_linux(void) : optional + Called from SPL before starting the kernel + +spl_start_uboot() : required + Returns "0" if SPL should start the kernel, "1" if U-Boot + must be started. + +Environment variables +--------------------- + +A board may chose to look at the environment for decisions about falcon +mode. In this case the following variables may be supported: + +boot_os : Set to yes/Yes/true/True/1 to enable booting to OS, + any other value to fall back to U-Boot (including + unset) +falcon_args_file : Filename to load as the 'args' portion of falcon mode + rather than the hard-coded value. +falcon_image_file : Filename to load as the OS image portion of falcon + mode rather than the hard-coded value. + +Using spl command +----------------- + +spl - SPL configuration + +Usage: + +spl export <img=atags|fdt> [kernel_addr] [initrd_addr] [fdt_addr ] + +img : "atags" or "fdt" +kernel_addr : kernel is loaded as part of the boot process, but it is not started. + This is the address where a kernel image is stored. +initrd_addr : Address of initial ramdisk + can be set to "-" if fdt_addr without initrd_addr is used +fdt_addr : in case of fdt, the address of the device tree. + +The spl export command does not write to a storage media. The user is +responsible to transfer the gathered information (assembled ATAGS list +or prepared FDT) from temporary storage in RAM into persistant storage +after each run of 'spl export'. Unfortunately the position of temporary +storage can not be predicted nor provided at commandline, it depends +highly on your system setup and your provided data (ATAGS or FDT). +However at the end of an succesful 'spl export' run it will print the +RAM address of temporary storage. The RAM address of FDT will also be +set in the environment variable 'fdtargsaddr', the new length of the +prepared FDT will be set in the environment variable 'fdtargslen'. +These environment variables can be used in scripts for writing updated +FDT to persistent storage. + +Now the user have to save the generated BLOB from that printed address +to the pre-defined address in persistent storage +(CONFIG_CMD_SPL_NAND_OFS in case of NAND). +The following example shows how to prepare the data for Falcon Mode on +twister board with ATAGS BLOB. + +The "spl export" command is prepared to work with ATAGS and FDT. However, +using FDT is at the moment untested. The ppc port (see a3m071 example +later) prepares the fdt blob with the fdt command instead. + + +Usage on the twister board: +-------------------------------- + +Using mtd names with the following (default) configuration +for mtdparts: + +device nand0 <omap2-nand.0>, # parts = 9 + #: name size offset mask_flags + 0: MLO 0x00080000 0x00000000 0 + 1: u-boot 0x00100000 0x00080000 0 + 2: env1 0x00040000 0x00180000 0 + 3: env2 0x00040000 0x001c0000 0 + 4: kernel 0x00600000 0x00200000 0 + 5: bootparms 0x00040000 0x00800000 0 + 6: splashimg 0x00200000 0x00840000 0 + 7: mini 0x02800000 0x00a40000 0 + 8: rootfs 0x1cdc0000 0x03240000 0 + + +twister => nand read 82000000 kernel + +NAND read: device 0 offset 0x200000, size 0x600000 + 6291456 bytes read: OK + +Now the kernel is in RAM at address 0x82000000 + +twister => spl export atags 0x82000000 +## Booting kernel from Legacy Image at 82000000 ... + Image Name: Linux-3.5.0-rc4-14089-gda0b7f4 + Image Type: ARM Linux Kernel Image (uncompressed) + Data Size: 3654808 Bytes = 3.5 MiB + Load Address: 80008000 + Entry Point: 80008000 + Verifying Checksum ... OK + Loading Kernel Image ... OK +OK +cmdline subcommand not supported +bdt subcommand not supported +Argument image is now in RAM at: 0x80000100 + +The result can be checked at address 0x80000100: + +twister => md 0x80000100 +80000100: 00000005 54410001 00000000 00000000 ......AT........ +80000110: 00000000 00000067 54410009 746f6f72 ....g.....ATroot +80000120: 65642f3d 666e2f76 77722073 73666e20 =/dev/nfs rw nfs + +The parameters generated with this step can be saved into NAND at the offset +0x800000 (value for twister for CONFIG_CMD_SPL_NAND_OFS) + +nand erase.part bootparms +nand write 0x80000100 bootparms 0x4000 + +Now the parameters are stored into the NAND flash at the address +CONFIG_CMD_SPL_NAND_OFS (=0x800000). + +Next time, the board can be started into Falcon Mode moving the +setting the gpio (on twister gpio 55 is used) to kernel mode. + +The kernel is loaded directly by the SPL without passing through U-Boot. + +Example with FDT: a3m071 board +------------------------------- + +To boot the Linux kernel from the SPL, the DT blob (fdt) needs to get +prepard/patched first. U-Boot usually inserts some dynamic values into +the DT binary (blob), e.g. autodetected memory size, MAC addresses, +clocks speeds etc. To generate this patched DT blob, you can use +the following command: + +1. Load fdt blob to SDRAM: +=> tftp 1800000 a3m071/a3m071.dtb + +2. Set bootargs as desired for Linux booting (e.g. flash_mtd): +=> run mtdargs addip2 addtty + +3. Use "fdt" commands to patch the DT blob: +=> fdt addr 1800000 +=> fdt boardsetup +=> fdt chosen + +4. Display patched DT blob (optional): +=> fdt print + +5. Save fdt to NOR flash: +=> erase fc060000 fc07ffff +=> cp.b 1800000 fc060000 10000 +... + + +Falcon Mode was presented at the RMLL 2012. Slides are available at: + +http://schedule2012.rmll.info/IMG/pdf/LSM2012_UbootFalconMode_Babic.pdf diff --git a/roms/u-boot/doc/README.fdt-control b/roms/u-boot/doc/README.fdt-control new file mode 100644 index 000000000..424d13fc5 --- /dev/null +++ b/roms/u-boot/doc/README.fdt-control @@ -0,0 +1,230 @@ +# SPDX-License-Identifier: GPL-2.0+ +# +# Copyright (c) 2011 The Chromium OS Authors. + +Device Tree Control in U-Boot +============================= + +This feature provides for run-time configuration of U-Boot via a flat +device tree (fdt). U-Boot configuration has traditionally been done +using CONFIG options in the board config file. This feature aims to +make it possible for a single U-Boot binary to support multiple boards, +with the exact configuration of each board controlled by a flat device +tree (fdt). This is the approach recently taken by the ARM Linux kernel +and has been used by PowerPC for some time. + +The fdt is a convenient vehicle for implementing run-time configuration +for three reasons. Firstly it is easy to use, being a simple text file. +It is extensible since it consists of nodes and properties in a nice +hierarchical format. + +Finally, there is already excellent infrastructure for the fdt: a +compiler checks the text file and converts it to a compact binary +format, and a library is already available in U-Boot (libfdt) for +handling this format. + +The dts directory contains a Makefile for building the device tree blob +and embedding it in your U-Boot image. This is useful since it allows +U-Boot to configure itself according to what it finds there. If you have +a number of similar boards with different peripherals, you can describe +the features of each board in the device tree file, and have a single +generic source base. + +To enable this feature, add CONFIG_OF_CONTROL to your board config file. + + +What is a Flat Device Tree? +--------------------------- + +An fdt can be specified in source format as a text file. To read about +the fdt syntax, take a look at the specification here: + +https://www.power.org/resources/downloads/Power_ePAPR_APPROVED_v1.0.pdf + +You also might find this section of the Linux kernel documentation +useful: (access this in the Linux kernel source code) + + Documentation/devicetree/booting-without-of.txt + +There is also a mailing list: + + http://lists.ozlabs.org/listinfo/devicetree-discuss + +In case you are wondering, OF stands for Open Firmware. + + +Tools +----- + +To use this feature you will need to get the device tree compiler. This is +provided by U-Boot automatically. If you have a system version of dtc +(typically in the 'device-tree-compiler' package), it is currently not used. + +If you want to build your own dtc, it is kept here: + + git://git.kernel.org/pub/scm/utils/dtc/dtc.git + +For example: + + $ git clone git://git.kernel.org/pub/scm/utils/dtc/dtc.git + $ cd dtc + $ make + $ sudo make install + +Then run the compiler (your version will vary): + + $ dtc -v + Version: DTC 1.2.0-g2cb4b51f + $ make tests + $ cd tests + $ ./run_tests.sh + ********** TEST SUMMARY + * Total testcases: 1371 + * PASS: 1371 + * FAIL: 0 + * Bad configuration: 0 + * Strange test result: 0 + +You will also find a useful fdtdump utility for decoding a binary file, as +well as fdtget/fdtput for reading and writing properties in a binary file. + + +Where do I get an fdt file for my board? +---------------------------------------- + +You may find that the Linux kernel has a suitable file. Look in the +kernel source in arch/<arch>/boot/dts. + +If not you might find other boards with suitable files that you can +modify to your needs. Look in the board directories for files with a +.dts extension. + +Failing that, you could write one from scratch yourself! + + +Configuration +------------- + +Use: + +#define CONFIG_DEFAULT_DEVICE_TREE "<name>" + +to set the filename of the device tree source. Then put your device tree +file into + + board/<vendor>/dts/<name>.dts + +This should include your CPU or SOC's device tree file, placed in +arch/<arch>/dts, and then make any adjustments required. + +If CONFIG_OF_EMBED is defined, then it will be picked up and built into +the U-Boot image (including u-boot.bin). This is suitable for debugging +and development only and is not recommended for production devices. + +If CONFIG_OF_SEPARATE is defined, then it will be built and placed in +a u-boot.dtb file alongside u-boot-nodtb.bin. A common approach is then to +join the two: + + cat u-boot-nodtb.bin u-boot.dtb >image.bin + +and then flash image.bin onto your board. Note that U-Boot creates +u-boot-dtb.bin which does the above step for you also. Resulting +u-boot.bin is a copy of u-boot-dtb.bin in this case. If you are using +CONFIG_SPL_FRAMEWORK, then u-boot.img will be built to include the device +tree binary. + +If CONFIG_OF_BOARD is defined, a board-specific routine will provide the +device tree at runtime, for example if an earlier bootloader stage creates +it and passes it to U-Boot. + +If CONFIG_OF_HOSTFILE is defined, then it will be read from a file on +startup. This is only useful for sandbox. Use the -d flag to U-Boot to +specify the file to read. + +You cannot use more than one of these options at the same time. + +To use a device tree file that you have compiled yourself, pass +EXT_DTB=<filename> to 'make', as in: + + make EXT_DTB=boot/am335x-boneblack-pubkey.dtb + +Then U-Boot will copy that file to u-boot.dtb, put it in the .img file +if used, and u-boot-dtb.bin. + +If you wish to put the fdt at a different address in memory, you can +define the "fdtcontroladdr" environment variable. This is the hex +address of the fdt binary blob, and will override either of the options. +Be aware that this environment variable is checked prior to relocation, +when only the compiled-in environment is available. Therefore it is not +possible to define this variable in the saved SPI/NAND flash +environment, for example (it will be ignored). After relocation, this +variable will be set to the address of the newly relocated fdt blob. +It is read-only and cannot be changed. It can optionally be used to +control the boot process of Linux with bootm/bootz commands. + +To use this, put something like this in your board header file: + +#define CONFIG_EXTRA_ENV_SETTINGS "fdtcontroladdr=10000\0" + +Build: + +After board configuration is done, fdt supported u-boot can be build in two ways: +1) build the default dts which is defined from CONFIG_DEFAULT_DEVICE_TREE + $ make +2) build the user specified dts file + $ make DEVICE_TREE=<dts-file-name> + + +Relocation, SPL and TPL +----------------------- + +U-Boot can be divided into three phases: TPL, SPL and U-Boot proper. + +The full device tree is available to U-Boot proper, but normally only a subset +(or none at all) is available to TPL and SPL. See 'Pre-Relocation Support' and +'SPL Support' in doc/driver-model/design.rst for more details. + + +Using several DTBs in the SPL (CONFIG_SPL_MULTI_DTB) +---------------------------------------------------- +In some rare cases it is desirable to let SPL be able to select one DTB among +many. This usually not very useful as the DTB for the SPL is small and usually +fits several platforms. However the DTB sometimes include information that do +work on several platforms (like IO tuning parameters). +In this case it is possible to use CONFIG_SPL_MULTI_DTB. This option appends to +the SPL a FIT image containing several DTBs listed in SPL_OF_LIST. +board_fit_config_name_match() is called to select the right DTB. + +If board_fit_config_name_match() relies on DM (DM driver to access an EEPROM +containing the board ID for example), it possible to start with a generic DTB +and then switch over to the right DTB after the detection. For this purpose, +the platform code must call fdtdec_resetup(). Based on the returned flag, the +platform may have to re-initiliaze the DM subusystem using dm_uninit() and +dm_init_and_scan(). + + +Limitations +----------- + +U-Boot is designed to build with a single architecture type and CPU +type. So for example it is not possible to build a single ARM binary +which runs on your AT91 and OMAP boards, relying on an fdt to configure +the various features. This is because you must select one of +the CPU families within arch/arm/cpu/arm926ejs (omap or at91) at build +time. Similarly you cannot build for multiple cpu types or +architectures. + +That said the complexity reduction by using fdt to support variants of +boards which use the same SOC / CPU can be substantial. + +It is important to understand that the fdt only selects options +available in the platform / drivers. It cannot add new drivers (yet). So +you must still have the CONFIG option to enable the driver. For example, +you need to define CONFIG_SYS_NS16550 to bring in the NS16550 driver, +but can use the fdt to specific the UART clock, peripheral address, etc. +In very broad terms, the CONFIG options in general control *what* driver +files are pulled in, and the fdt controls *how* those files work. + +-- +Simon Glass <sjg@chromium.org> +1-Sep-11 diff --git a/roms/u-boot/doc/README.fec_mxc b/roms/u-boot/doc/README.fec_mxc new file mode 100644 index 000000000..9ca6ac2fb --- /dev/null +++ b/roms/u-boot/doc/README.fec_mxc @@ -0,0 +1,39 @@ +U-Boot config options used in fec_mxc.c + +CONFIG_FEC_MXC + Selects fec_mxc.c to be compiled into u-boot. Can read out the + ethaddr from the SoC eFuses (see below). + +CONFIG_MII + Must be defined if CONFIG_FEC_MXC is defined. + +CONFIG_FEC_XCV_TYPE + Defaults to MII100 for 100 Base-tx. + RGMII selects 1000 Base-tx reduced pin count interface. + RMII selects 100 Base-tx reduced pin count interface. + +CONFIG_FEC_MXC_SWAP_PACKET + Forced on iff MX28. + Swaps the bytes order of all words(4 byte units) in the packet. + This should not be specified by a board file. It is cpu specific. + +CONFIG_PHYLIB + fec_mxc supports PHYLIB and should be used for new boards. + +CONFIG_FEC_MXC_NO_ANEG + Relevant only if PHYLIB not used. Skips auto-negotiation restart. + +CONFIG_FEC_MXC_PHYADDR + Optional, selects the exact phy address that should be connected + and function fecmxc_initialize will try to initialize it. + +CONFIG_FEC_FIXED_SPEED + Optional, selects a fixed speed on the MAC interface without asking some + phy. This is usefull if there is a direct MAC <-> MAC connection, for + example if the CPU is connected directly via the RGMII interface to a + ethernet-switch. + +Reading the ethaddr from the SoC eFuses: +if CONFIG_FEC_MXC is defined and the U-Boot environment does not contain the +ethaddr variable, then its value gets read from the corresponding eFuses in +the SoC. See the README files of the specific SoC for details. diff --git a/roms/u-boot/doc/README.fsl-clk b/roms/u-boot/doc/README.fsl-clk new file mode 100644 index 000000000..3a9927f07 --- /dev/null +++ b/roms/u-boot/doc/README.fsl-clk @@ -0,0 +1,5 @@ +Freescale system clock options + + - CONFIG_SYS_FSL_CLK + Enable to call get_clocks() in board_init_f() for + non-PPC platforms. diff --git a/roms/u-boot/doc/README.fsl-ddr b/roms/u-boot/doc/README.fsl-ddr new file mode 100644 index 000000000..cec5d94df --- /dev/null +++ b/roms/u-boot/doc/README.fsl-ddr @@ -0,0 +1,439 @@ +Table of interleaving 2-4 controllers +===================================== + +--------------+-----------------------------------------------------------+ + |Configuration | Memory Controller | + | | 1 2 3 4 | + |--------------+--------------+--------------+-----------------------------+ + | Two memory | Not Intlv'ed | Not Intlv'ed | | + | complexes +--------------+--------------+ | + | | 2-way Intlv'ed | | + |--------------+--------------+--------------+--------------+ | + | | Not Intlv'ed | Not Intlv'ed | Not Intlv'ed | | + | Three memory +--------------+--------------+--------------+ | + | complexes | 2-way Intlv'ed | Not Intlv'ed | | + | +-----------------------------+--------------+ | + | | 3-way Intlv'ed | | + +--------------+--------------+--------------+--------------+--------------+ + | | Not Intlv'ed | Not Intlv'ed | Not Intlv'ed | Not Intlv'ed | + | Four memory +--------------+--------------+--------------+--------------+ + | complexes | 2-way Intlv'ed | 2-way Intlv'ed | + | +-----------------------------+-----------------------------+ + | | 4-way Intlv'ed | + +--------------+-----------------------------------------------------------+ + + +Table of 2-way interleaving modes supported in cpu/8xxx/ddr/ +====================================================== + +-------------+---------------------------------------------------------+ + | | Rank Interleaving | + | +--------+-----------+-----------+------------+-----------+ + |Memory | | | | 2x2 | 4x1 | + |Controller | None | 2x1 lower | 2x1 upper | {CS0+CS1}, | {CS0+CS1+ | + |Interleaving | | {CS0+CS1} | {CS2+CS3} | {CS2+CS3} | CS2+CS3} | + +-------------+--------+-----------+-----------+------------+-----------+ + |None | Yes | Yes | Yes | Yes | Yes | + +-------------+--------+-----------+-----------+------------+-----------+ + |Cacheline | Yes | Yes | No | No, Only(*)| Yes | + | |CS0 Only| | | {CS0+CS1} | | + +-------------+--------+-----------+-----------+------------+-----------+ + |Page | Yes | Yes | No | No, Only(*)| Yes | + | |CS0 Only| | | {CS0+CS1} | | + +-------------+--------+-----------+-----------+------------+-----------+ + |Bank | Yes | Yes | No | No, Only(*)| Yes | + | |CS0 Only| | | {CS0+CS1} | | + +-------------+--------+-----------+-----------+------------+-----------+ + |Superbank | No | Yes | No | No, Only(*)| Yes | + | | | | | {CS0+CS1} | | + +-------------+--------+-----------+-----------+------------+-----------+ + (*) Although the hardware can be configured with memory controller + interleaving using "2x2" rank interleaving, it only interleaves {CS0+CS1} + from each controller. {CS2+CS3} on each controller are only rank + interleaved on that controller. + + For memory controller interleaving, identical DIMMs are suggested. Software + doesn't check the size or organization of interleaved DIMMs. + +The ways to configure the ddr interleaving mode +============================================== +1. In board header file(e.g.MPC8572DS.h), add default interleaving setting + under "CONFIG_EXTRA_ENV_SETTINGS", like: + #define CONFIG_EXTRA_ENV_SETTINGS \ + "hwconfig=fsl_ddr:ctlr_intlv=bank" \ + ...... + +2. Run U-Boot "setenv" command to configure the memory interleaving mode. + Either numerical or string value is accepted. + + # disable memory controller interleaving + setenv hwconfig "fsl_ddr:ctlr_intlv=null" + + # cacheline interleaving + setenv hwconfig "fsl_ddr:ctlr_intlv=cacheline" + + # page interleaving + setenv hwconfig "fsl_ddr:ctlr_intlv=page" + + # bank interleaving + setenv hwconfig "fsl_ddr:ctlr_intlv=bank" + + # superbank + setenv hwconfig "fsl_ddr:ctlr_intlv=superbank" + + # 1KB 3-way interleaving + setenv hwconfig "fsl_ddr:ctlr_intlv=3way_1KB" + + # 4KB 3-way interleaving + setenv hwconfig "fsl_ddr:ctlr_intlv=3way_4KB" + + # 8KB 3-way interleaving + setenv hwconfig "fsl_ddr:ctlr_intlv=3way_8KB" + + # disable bank (chip-select) interleaving + setenv hwconfig "fsl_ddr:bank_intlv=null" + + # bank(chip-select) interleaving cs0+cs1 + setenv hwconfig "fsl_ddr:bank_intlv=cs0_cs1" + + # bank(chip-select) interleaving cs2+cs3 + setenv hwconfig "fsl_ddr:bank_intlv=cs2_cs3" + + # bank(chip-select) interleaving (cs0+cs1) and (cs2+cs3) (2x2) + setenv hwconfig "fsl_ddr:bank_intlv=cs0_cs1_and_cs2_cs3" + + # bank(chip-select) interleaving (cs0+cs1+cs2+cs3) (4x1) + setenv hwconfig "fsl_ddr:bank_intlv=cs0_cs1_cs2_cs3" + + # bank(chip-select) interleaving (auto) + setenv hwconfig "fsl_ddr:bank_intlv=auto" + This auto mode only select from cs0_cs1_cs2_cs3, cs0_cs1, null dependings + on DIMMs. + +Memory controller address hashing +================================== +If the DDR controller supports address hashing, it can be enabled by hwconfig. + +Syntax is: +hwconfig=fsl_ddr:addr_hash=true + +Memory controller ECC on/off +============================ +If ECC is enabled in board configuratoin file, i.e. #define CONFIG_DDR_ECC, +ECC can be turned on/off by hwconfig. + +Syntax is +hwconfig=fsl_ddr:ecc=off + + +Memory address parity on/off +============================ +address parity can be turned on/off by hwconfig. +Syntax is: +hwconfig=fsl_ddr:parity=on + + +Memory testing options for mpc85xx +================================== +1. Memory test can be done once U-Boot prompt comes up using mtest, or +2. Memory test can be done with Power-On-Self-Test function, activated at + compile time. + + In order to enable the POST memory test, CONFIG_POST needs to be + defined in board configuraiton header file. By default, POST memory test + performs a fast test. A slow test can be enabled by changing the flag at + compiling time. To test memory bigger than 2GB, 36BIT support is needed. + Memory is tested within a 2GB window. TLBs are used to map the virtual 2GB + window to physical address so that all physical memory can be tested. + +Combination of hwconfig +======================= +Hwconfig can be combined with multiple parameters, for example, on a supported +platform + +hwconfig=fsl_ddr:addr_hash=true,ctlr_intlv=cacheline,bank_intlv=cs0_cs1_cs2_cs3,ecc=on + + +Table for dynamic ODT for DDR3 +============================== +For single-slot system with quad-rank DIMM and dual-slot system, dynamic ODT may +be needed, depending on the configuration. The numbers in the following tables are +in Ohms. + +* denotes dynamic ODT + +Two slots system ++-----------------------+----------+---------------+-----------------------------+-----------------------------+ +| Configuration | |DRAM controller| Slot 1 | Slot 2 | ++-----------+-----------+----------+-------+-------+--------------+--------------+--------------+--------------+ +| | | | | | Rank 1 | Rank 2 | Rank 1 | Rank 2 | ++ Slot 1 | Slot 2 |Write/Read| Write | Read |-------+------+-------+------+-------+------+-------+------+ +| | | | | | Write | Read | Write | Read | Write | Read | Write | Read | ++-----------+-----------+----------+-------+-------+-------+------+-------+------+-------+------+-------+------+ +| | | Slot 1 | off | 75 | 120 | off | off | off | off | off | 30 | 30 | +| Dual Rank | Dual Rank |----------+-------+-------+-------+------+-------+------+-------+------+-------+------+ +| | | Slot 2 | off | 75 | off | off | 30 | 30 | 120 | off | off | off | ++-----------+-----------+----------+-------+-------+-------+------+-------+------+-------+------+-------+------+ +| | | Slot 1 | off | 75 | 120 | off | off | off | 20 | 20 | | | +| Dual Rank |Single Rank|----------+-------+-------+-------+------+-------+------+-------+------+-------+------+ +| | | Slot 2 | off | 75 | off | off | 20 | 20 | 120 *| off | | | ++-----------+-----------+----------+-------+-------+-------+------+-------+------+-------+------+-------+------+ +| | | Slot 1 | off | 75 | 120 *| off | | | off | off | 20 | 20 | +|Single Rank| Dual Rank |----------+-------+-------+-------+------+-------+------+-------+------+-------+------+ +| | | Slot 2 | off | 75 | 20 | 20 | | | 120 | off | off | off | ++-----------+-----------+----------+-------+-------+-------+------+-------+------+-------+------+-------+------+ +| | | Slot 1 | off | 75 | 120 *| off | | | 30 | 30 | | | +|Single Rank|Single Rank|----------+-------+-------+-------+------+-------+------+-------+------+-------+------+ +| | | Slot 2 | off | 75 | 30 | 30 | | | 120 *| off | | | ++-----------+-----------+----------+-------+-------+-------+------+-------+------+-------+------+-------+------+ +| Dual Rank | Empty | Slot 1 | off | 75 | 40 | off | off | off | | | | | ++-----------+-----------+----------+-------+-------+-------+------+-------+------+-------+------+-------+------+ +| Empty | Dual Rank | Slot 2 | off | 75 | | | | | 40 | off | off | off | ++-----------+-----------+----------+-------+-------+-------+------+-------+------+-------+------+-------+------+ +|Single Rank| Empty | Slot 1 | off | 75 | 40 | off | | | | | | | ++-----------+-----------+----------+-------+-------+-------+------+-------+------+-------+------+-------+------+ +| Empty |Single Rank| Slot 2 | off | 75 | | | | | 40 | off | | | ++-----------+-----------+----------+-------+-------+-------+------+-------+------+-------+------+-------+------+ + +Single slot system ++-------------+------------+---------------+-----------------------------+-----------------------------+ +| | |DRAM controller| Rank 1 | Rank 2 | Rank 3 | Rank 4 | +|Configuration| Write/Read |-------+-------+-------+------+-------+------+-------+------+-------+------+ +| | | Write | Read | Write | Read | Write | Read | Write | Read | Write | Read | ++-------------+------------+-------+-------+-------+------+-------+------+-------+------+-------+------+ +| | R1 | off | 75 | 120 *| off | off | off | 20 | 20 | off | off | +| |------------+-------+-------+-------+------+-------+------+-------+------+-------+------+ +| | R2 | off | 75 | off | 20 | 120 | off | 20 | 20 | off | off | +| Quad Rank |------------+-------+-------+-------+------+-------+------+-------+------+-------+------+ +| | R3 | off | 75 | 20 | 20 | off | off | 120 *| off | off | off | +| |------------+-------+-------+-------+------+-------+------+-------+------+-------+------+ +| | R4 | off | 75 | 20 | 20 | off | off | off | 20 | 120 | off | ++-------------+------------+-------+-------+-------+------+-------+------+-------+------+-------+------+ +| | R1 | off | 75 | 40 | off | off | off | +| Dual Rank |------------+-------+-------+-------+------+-------+------+ +| | R2 | off | 75 | 40 | off | off | off | ++-------------+------------+-------+-------+-------+------+-------+------+ +| Single Rank | R1 | off | 75 | 40 | off | ++-------------+------------+-------+-------+-------+------+ + +Reference http://www.xrosstalkmag.com/mag_issues/xrosstalk_oct08_final.pdf + http://download.micron.com/pdf/technotes/ddr3/tn4108_ddr3_design_guide.pdf + + +Table for ODT for DDR2 +====================== +Two slots system ++-----------------------+----------+---------------+-----------------------------+-----------------------------+ +| Configuration | |DRAM controller| Slot 1 | Slot 2 | ++-----------+-----------+----------+-------+-------+--------------+--------------+--------------+--------------+ +| | | | | | Rank 1 | Rank 2 | Rank 1 | Rank 2 | ++ Slot 1 | Slot 2 |Write/Read| Write | Read |-------+------+-------+------+-------+------+-------+------+ +| | | | | | Write | Read | Write | Read | Write | Read | Write | Read | ++-----------+-----------+----------+-------+-------+-------+------+-------+------+-------+------+-------+------+ +| | | Slot 1 | off | 150 | off | off | off | off | 75 | 75 | off | off | +| Dual Rank | Dual Rank |----------+-------+-------+-------+------+-------+------+-------+------+-------+------+ +| | | Slot 2 | off | 150 | 75 | 75 | off | off | off | off | off | off | ++-----------+-----------+----------+-------+-------+-------+------+-------+------+-------+------+-------+------+ +| | | Slot 1 | off | 150 | off | off | off | off | 75 | 75 | | | +| Dual Rank |Single Rank|----------+-------+-------+-------+------+-------+------+-------+------+-------+------+ +| | | Slot 2 | off | 150 | 75 | 75 | off | off | off | off | | | ++-----------+-----------+----------+-------+-------+-------+------+-------+------+-------+------+-------+------+ +| | | Slot 1 | off | 150 | off | off | | | 75 | 75 | off | off | +|Single Rank| Dual Rank |----------+-------+-------+-------+------+-------+------+-------+------+-------+------+ +| | | Slot 2 | off | 150 | 75 | 75 | | | off | off | off | off | ++-----------+-----------+----------+-------+-------+-------+------+-------+------+-------+------+-------+------+ +| | | Slot 1 | off | 150 | off | off | | | 75 | 75 | | | +|Single Rank|Single Rank|----------+-------+-------+-------+------+-------+------+-------+------+-------+------+ +| | | Slot 2 | off | 150 | 75 | 75 | | | off | off | | | ++-----------+-----------+----------+-------+-------+-------+------+-------+------+-------+------+-------+------+ +| Dual Rank | Empty | Slot 1 | off | 75 | 150 | off | off | off | | | | | ++-----------+-----------+----------+-------+-------+-------+------+-------+------+-------+------+-------+------+ +| Empty | Dual Rank | Slot 2 | off | 75 | | | | | 150 | off | off | off | ++-----------+-----------+----------+-------+-------+-------+------+-------+------+-------+------+-------+------+ +|Single Rank| Empty | Slot 1 | off | 75 | 150 | off | | | | | | | ++-----------+-----------+----------+-------+-------+-------+------+-------+------+-------+------+-------+------+ +| Empty |Single Rank| Slot 2 | off | 75 | | | | | 150 | off | | | ++-----------+-----------+----------+-------+-------+-------+------+-------+------+-------+------+-------+------+ + +Single slot system ++-------------+------------+---------------+-----------------------------+ +| | |DRAM controller| Rank 1 | Rank 2 | +|Configuration| Write/Read |-------+-------+-------+------+-------+------+ +| | | Write | Read | Write | Read | Write | Read | ++-------------+------------+-------+-------+-------+------+-------+------+ +| | R1 | off | 75 | 150 | off | off | off | +| Dual Rank |------------+-------+-------+-------+------+-------+------+ +| | R2 | off | 75 | 150 | off | off | off | ++-------------+------------+-------+-------+-------+------+-------+------+ +| Single Rank | R1 | off | 75 | 150 | off | ++-------------+------------+-------+-------+-------+------+ + +Reference http://www.samsung.com/global/business/semiconductor/products/dram/downloads/applicationnote/ddr2_odt_control_200603.pdf + + +Interactive DDR debugging +=========================== + +For DDR parameter tuning up and debugging, the interactive DDR debugger can +be activated by setting the environment variable "ddr_interactive" to any +value. (The value of ddr_interactive may have a meaning in the future, but, +for now, the presence of the variable will cause the debugger to run.) Once +activated, U-Boot will show the prompt "FSL DDR>" before enabling the DDR +controller. The available commands are printed by typing "help". + +Another way to enter the interactive DDR debugger without setting the +environment variable is to send the 'd' character early during the boot +process. To save booting time, no additional delay is added, so the window +to send the key press is very short -- basically, it is the time before the +memory controller code starts to run. For example, when rebooting from +within U-Boot, the user must press 'd' IMMEDIATELY after hitting enter to +initiate a 'reset' command. In case of power on/reset, the user can hold +down the 'd' key while applying power or hitting the board's reset button. + +The example flow of using interactive debugging is +type command "compute" to calculate the parameters from the default +type command "print" with arguments to show SPD, options, registers +type command "edit" with arguments to change any if desired +type command "copy" with arguments to copy controller/dimm settings +type command "go" to continue calculation and enable DDR controller + +Additional commands to restart the debugging are: +type command "reset" to reset the board +type command "recompute" to reload SPD and start over + +Note, check "next_step" to show the flow. For example, after edit opts, the +next_step is STEP_ASSIGN_ADDRESSES. After editing registers, the next_step is +STEP_PROGRAM_REGS. Upon issuing command "go", the debugger will program the +DDR controller with the current setting without further calculation and then +exit to resume the booting of the machine. + +The detail syntax for each commands are + +print [c<n>] [d<n>] [spd] [dimmparms] [commonparms] [opts] [addresses] [regs] + c<n> - the controller number, eg. c0, c1 + d<n> - the DIMM number, eg. d0, d1 + spd - print SPD data + dimmparms - DIMM parameters, calculated from SPD + commonparms - lowest common parameters for all DIMMs + opts - options + addresses - address assignment (not implemented yet) + regs - controller registers + +edit <c#> <d#> <spd|dimmparms|commonparms|opts|addresses|regs> <element> <value> + c<n> - the controller number, eg. c0, c1 + d<n> - the DIMM number, eg. d0, d1 + spd - print SPD data + dimmparms - DIMM parameters, calculated from SPD + commonparms - lowest common parameters for all DIMMs + opts - options + addresses - address assignment (not implemented yet) + regs - controller registers + <element> - name of the modified element + byte number if the object is SPD + <value> - decimal or heximal (prefixed with 0x) numbers + +copy <src c#> <src d#> <spd|dimmparms|commonparms|opts|addresses|regs> <dst c#> <dst d#> + same as for "edit" command + DIMM numbers ignored for commonparms, opts, and regs + +reset + no arguement - reset the board + +recompute + no argument - reload SPD and start over + +compute + no argument - recompute from current next_step + +next_step + no argument - show current next_step + +help + no argument - print a list of all commands + +go + no argument - program memory controller(s) and continue with U-Boot + +Examples of debugging flow + + FSL DDR>compute + Detected UDIMM UG51U6400N8SU-ACF + FSL DDR>print + print [c<n>] [d<n>] [spd] [dimmparms] [commonparms] [opts] [addresses] [regs] + FSL DDR>print dimmparms + DIMM parameters: Controller=0 DIMM=0 + DIMM organization parameters: + module part name = UG51U6400N8SU-ACF + rank_density = 2147483648 bytes (2048 megabytes) + capacity = 4294967296 bytes (4096 megabytes) + burst_lengths_bitmask = 0C + base_addresss = 0 (00000000 00000000) + n_ranks = 2 + data_width = 64 + primary_sdram_width = 64 + ec_sdram_width = 0 + registered_dimm = 0 + n_row_addr = 15 + n_col_addr = 10 + edc_config = 0 + n_banks_per_sdram_device = 8 + tCKmin_X_ps = 1500 + tCKmin_X_minus_1_ps = 0 + tCKmin_X_minus_2_ps = 0 + tCKmax_ps = 0 + caslat_X = 960 + tAA_ps = 13125 + caslat_X_minus_1 = 0 + caslat_X_minus_2 = 0 + caslat_lowest_derated = 0 + tRCD_ps = 13125 + tRP_ps = 13125 + tRAS_ps = 36000 + tWR_ps = 15000 + tWTR_ps = 7500 + tRFC_ps = 160000 + tRRD_ps = 6000 + tRC_ps = 49125 + refresh_rate_ps = 7800000 + tIS_ps = 0 + tIH_ps = 0 + tDS_ps = 0 + tDH_ps = 0 + tRTP_ps = 7500 + tDQSQ_max_ps = 0 + tQHS_ps = 0 + FSL DDR>edit c0 opts ECC_mode 0 + FSL DDR>edit c0 regs cs0_bnds 0x000000FF + FSL DDR>go + 2 GiB left unmapped + 4 GiB (DDR3, 64-bit, CL=9, ECC off) + DDR Chip-Select Interleaving Mode: CS0+CS1 + Testing 0x00000000 - 0x7fffffff + Testing 0x80000000 - 0xffffffff + Remap DDR 2 GiB left unmapped + + POST memory PASSED + Flash: 128 MiB + L2: 128 KB enabled + Corenet Platform Cache: 1024 KB enabled + SERDES: timeout resetting bank 3 + SRIO1: disabled + SRIO2: disabled + MMC: FSL_ESDHC: 0 + EEPROM: Invalid ID (ff ff ff ff) + PCIe1: disabled + PCIe2: Root Complex, x1, regs @ 0xfe201000 + 01:00.0 - 8086:10d3 - Network controller + PCIe2: Bus 00 - 01 + PCIe3: disabled + In: serial + Out: serial + Err: serial + Net: Initializing Fman + Fman1: Uploading microcode version 101.8.0 + e1000: 00:1b:21:81:d2:e0 + FM1@DTSEC1, FM1@DTSEC2, FM1@DTSEC3, FM1@DTSEC4, FM1@DTSEC5, e1000#0 [PRIME] + Warning: e1000#0 MAC addresses don't match: + Address in SROM is 00:1b:21:81:d2:e0 + Address in environment is 00:e0:0c:00:ea:05 + + Hit any key to stop autoboot: 0 + => diff --git a/roms/u-boot/doc/README.fsl-dpaa b/roms/u-boot/doc/README.fsl-dpaa new file mode 100644 index 000000000..3ef5eeb32 --- /dev/null +++ b/roms/u-boot/doc/README.fsl-dpaa @@ -0,0 +1,10 @@ +This file documents Freescale DPAA-specific options. + +FMan (Frame Manager) + - CONFIG_FSL_FM_10GEC_REGULAR_NOTATION + on SoCs T4240, T2080, LS1043A, etc, the notation between 10GEC and MAC as below: + 10GEC1->MAC9, 10GEC2->MAC10, 10GEC3->MAC1, 10GEC4->MAC2 + on SoCs T1024, etc, the notation between 10GEC and MAC as below: + 10GEC1->MAC1, 10GEC2->MAC2 + so we introduce CONFIG_FSL_FM_10GEC_REGULAR_NOTATION to identify the new SoCs on + which 10GEC enumeration is consistent with MAC enumeration. diff --git a/roms/u-boot/doc/README.fsl-esdhc b/roms/u-boot/doc/README.fsl-esdhc new file mode 100644 index 000000000..b620625df --- /dev/null +++ b/roms/u-boot/doc/README.fsl-esdhc @@ -0,0 +1,8 @@ +Freescale esdhc-specific options + + - CONFIG_SYS_FSL_ESDHC_LE + ESDHC IP is in little-endian mode. Accessing ESDHC registers can be + determined by ESDHC IP's endian mode or processor's endian mode. + - CONFIG_SYS_FSL_ESDHC_BE + ESDHC IP is in big-endian mode. Accessing ESDHC registers can be determined + by ESDHC IP's endian mode or processor's endian mode. diff --git a/roms/u-boot/doc/README.fsl-hwconfig b/roms/u-boot/doc/README.fsl-hwconfig new file mode 100644 index 000000000..e752505da --- /dev/null +++ b/roms/u-boot/doc/README.fsl-hwconfig @@ -0,0 +1,46 @@ +Freescale-specific 'hwconfig' options. + +This file documents Freescale-specific key:value pairs for the 'hwconfig' +option. See README.hwconfig for general information about 'hwconfig'. + +audclk + Specific to the P1022DS reference board. + + This option specifies which of the two oscillator frequencies should be + routed to the Wolfson WM8776 codec. The ngPIXIS can be programmed to + route either a 11.2896MHz or a 12.288MHz clock. The default is + 12.288MHz. This option has two effects. First, the MUX on the board + will be programmed accordingly. Second, the clock-frequency property + in the codec node in the device tree will be updated to the correct + value. + + 'audclk:11' + Select the 11.2896MHz clock + + 'audclk:12' + Select the 12.288MHz clock + +usb + Specific to boards have USB controller + + This option specifies the following for a USB controller: + + - which controller mode to use + - which USB PHY to use + + This is used by generic USB device-tree fixup function to update + modified values of phy type and controller mode. + + Also used for configuring multiple USB controllers such that + 'usbN' (where N is 1, 2, etc. refers to controller no.) + + 'phy_type' + Select USB phy type: 'utmi' OR 'ulpi' + + 'dr_mode' + Select USB controller mode: 'host', 'peripheral' OR 'otg' + + Examples: + usb1:dr_mode=host;usb2:dr_mode=peripheral' + + usb1:dr_mode=host,phy_type=utmi;usb2:dr_mode=host' diff --git a/roms/u-boot/doc/README.fsl-trustzone-components b/roms/u-boot/doc/README.fsl-trustzone-components new file mode 100644 index 000000000..e1223469e --- /dev/null +++ b/roms/u-boot/doc/README.fsl-trustzone-components @@ -0,0 +1,25 @@ +Freescale ARM64 SoCs like LS2080A have ARM TrustZone components like +TZPC-BP147 (TrustZone Protection Controller) and TZASC-400 (TrustZone +Address Space Controller). + +While most of the configuration related programming of these peripherals +is left to a root-of-trust security software layer (running in EL3 +privilege mode), but still some configurations of these peripherals +might be required while the bootloader is executing in EL3 privilege +mode. The following sections define how to turn on these features for +LS2080A like SoCs. + +TZPC-BP147 (TrustZone Protection Controller) +============================================ +- Depends on CONFIG_FSL_TZPC_BP147 configuration flag. +- Separates Secure World and Normal World on-chip RAM (OCRAM) spaces. +- Provides a programming model to set access control policy via the TZPC + TZDECPROT Registers. + +TZASC-400 (TrustZone Address Space Controller) +============================================== +- Depends on CONFIG_FSL_TZASC_400 configuration flag. +- Separates Secure World and Normal World external memory spaces for bus masters + such as processors and DMA-equipped peripherals. +- Supports 8 fully programmable address regions, initially inactive at reset, + and one base region, always active, that covers the remaining address space. diff --git a/roms/u-boot/doc/README.fsl_iim b/roms/u-boot/doc/README.fsl_iim new file mode 100644 index 000000000..e087f5e0e --- /dev/null +++ b/roms/u-boot/doc/README.fsl_iim @@ -0,0 +1,48 @@ +Driver implementing the fuse API for Freescale's IC Identification Module (IIM) + +This IP can be found on the following SoCs: + - MPC512x, + - i.MX25, + - i.MX27, + - i.MX31, + - i.MX35, + - i.MX51, + - i.MX53. + +The section numbers in this file refer to the i.MX25 Reference Manual. + +A fuse word contains 8 fuse bit slots, as explained in 30.4.2.2.1. + +A bank contains 256 fuse word slots, as shown by the memory map in 30.3.1. + +Some fuse bit or word slots may not have the corresponding fuses actually +implemented in the fusebox. + +See the README files of the SoCs using this driver in order to know the +conventions used by U-Boot to store some specific data in the fuses, e.g. MAC +addresses. + +Fuse operations: + + Read + Read operations are implemented as read accesses to the shadow registers, + using "Word y of Bank x" from the register summary in 30.3.2. This is + explained in detail in 30.4.5.1. + + Sense + Sense operations are implemented as explained in 30.4.5.2. + + Program + Program operations are implemented as explained in 30.4.5.3. Following + this operation, the shadow registers are reloaded by the hardware (not + immediately, but this does not make any difference for a user reading + these registers). + + Override + Override operations are implemented as write accesses to the shadow + registers, as explained in 30.4.5.4. + +Configuration: + + CONFIG_FSL_IIM + Define this to enable the fsl_iim driver. diff --git a/roms/u-boot/doc/README.fuse b/roms/u-boot/doc/README.fuse new file mode 100644 index 000000000..1bc91c44a --- /dev/null +++ b/roms/u-boot/doc/README.fuse @@ -0,0 +1,67 @@ +Fuse API functions and commands + +The fuse API allows to control a fusebox and how it is used by the upper +hardware layers. + +A fuse corresponds to a single non-volatile memory bit that can be programmed +(i.e. blown, set to 1) only once. The programming operation is irreversible. A +fuse that has not been programmed reads 0. + +Fuses can be used by SoCs to store various permanent configuration and data, +e.g. boot configuration, security configuration, MAC addresses, etc. + +A fuse word is the smallest group of fuses that can be read at once from the +fusebox control IP registers. This is limited to 32 bits with the current API. + +A fuse bank is the smallest group of fuse words having a common ID, as defined +by each SoC. + +Upon startup, the fusebox control IP reads the fuse values and stores them to a +volatile shadow cache. + +See the README files of the drivers implementing this API in order to know the +SoC- and implementation-specific details. + +Functions / commands: + + int fuse_read(u32 bank, u32 word, u32 *val); + fuse read <bank> <word> [<cnt>] + Read fuse words from the shadow cache. + + int fuse_sense(u32 bank, u32 word, u32 *val); + fuse sense <bank> <word> [<cnt>] + Sense - i.e. read directly from the fusebox, skipping the shadow cache - + fuse words. This operation does not update the shadow cache. + + This is useful to know the true value of fuses if an override has been + performed (see below). + + int fuse_prog(u32 bank, u32 word, u32 val); + fuse prog [-y] <bank> <word> <hexval> [<hexval>...] + Program fuse words. This operation directly affects the fusebox and is + irreversible. The shadow cache is updated accordingly or not, depending on + each IP. + + Only the bits to be programmed should be set in the input value (i.e. for + fuse bits that have already been programmed and hence should be left + unchanged by a further programming, it is preferable to clear the + corresponding bits in the input value in order not to perform a new + hardware programming operation on these fuse bits). + + int fuse_override(u32 bank, u32 word, u32 val); + fuse override <bank> <word> <hexval> [<hexval>...] + Override fuse words in the shadow cache. + + The fusebox is unaffected, so following this operation, the shadow cache + may differ from the fusebox values. Read or sense operations can then be + used to get the values from the shadow cache or from the fusebox. + + This is useful to change the behaviors linked to some cached fuse values, + either because this is needed only temporarily, or because some of the + fuses have already been programmed or are locked (if the SoC allows to + override a locked fuse). + +Configuration: + + CONFIG_CMD_FUSE + Define this to enable the fuse commands. diff --git a/roms/u-boot/doc/README.generic-board b/roms/u-boot/doc/README.generic-board new file mode 100644 index 000000000..bc35179fb --- /dev/null +++ b/roms/u-boot/doc/README.generic-board @@ -0,0 +1,135 @@ +# SPDX-License-Identifier: GPL-2.0+ +# +# (C) Copyright 2014 Google, Inc +# Simon Glass <sjg@chromium.org> + +Background +---------- + +U-Boot traditionally had a board.c file for each architecture. This introduced +quite a lot of duplication, with each architecture tending to do +initialisation slightly differently. To address this, a new 'generic board +init' feature was introduced in March 2013 (further motivation is +provided in the cover letter below). + +All boards and architectures have moved to this as of mid 2016. + + +What has changed? +----------------- + +The main change is that the arch/<arch>/lib/board.c file is removed in +favour of common/board_f.c (for pre-relocation init) and common/board_r.c +(for post-relocation init). + +Related to this, the global_data and bd_info structures now have a core set of +fields which are common to all architectures. Architecture-specific fields +have been moved to separate structures. + + +Further Background +------------------ + +The full text of the original generic board series is reproduced below. + +--8<------------- + +This series creates a generic board.c implementation which contains +the essential functions of the major arch/xxx/lib/board.c files. + +What is the motivation for this change? + +1. There is a lot of repeated code in the board.c files. Any change to +things like setting up the baud rate requires a change in 10 separate +places. + +2. Since there are 10 separate files, adding a new feature which requires +initialisation is painful since it must be independently added in 10 +places. + +3. As time goes by the architectures naturally diverge since there is limited +pressure to compare features or even CONFIG options against similar things +in other board.c files. + +4. New architectures must implement all the features all over again, and +sometimes in subtle different ways. This places an unfair burden on getting +a new architecture fully functional and running with U-Boot. + +5. While it is a bit of a tricky change, I believe it is worthwhile and +achievable. There is no requirement that all code be common, only that +the code that is common should be located in common/board.c rather than +arch/xxx/lib/board.c. + +All the functions of board_init_f() and board_init_r() are broken into +separate function calls so that they can easily be included or excluded +for a particular architecture. It also makes it easier to adopt Graeme's +initcall proposal when it is ready. + +http://lists.denx.de/pipermail/u-boot/2012-January/114499.html + +This series removes the dependency on generic relocation. So relocation +happens as one big chunk and is still completely arch-specific. See the +relocation series for a proposed solution to this for ARM: + +http://lists.denx.de/pipermail/u-boot/2011-December/112928.html + +or Graeme's recent x86 series v2: + +http://lists.denx.de/pipermail/u-boot/2012-January/114467.html + +Instead of moving over a whole architecture, this series takes the approach +of simply enabling generic board support for an architecture. It is then up +to each board to opt in by defining CONFIG_SYS_GENERIC_BOARD in the board +config file. If this is not done, then the code will be generated as +before. This allows both sets of code to co-exist until we are comfortable +with the generic approach, and enough boards run. + +ARM is a relatively large board.c file and one which I can test, therefore +I think it is a good target for this series. On the other hand, x86 is +relatively small and simple, but different enough that it introduces a +few issues to be solved. So I have chosen both ARM and x86 for this series. +After a suggestion from Wolfgang I have added PPC also. This is the +largest and most feature-full board, so hopefully we have all bases +covered in this RFC. + +A generic global_data structure is also required. This might upset a few +people. Here is my basic reasoning: most fields are the same, all +architectures include and need it, most global_data.h files already have +#ifdefs to select fields for a particular SOC, so it is hard to +see why architecures are different in this area. We can perhaps add a +way to put architecture-specific fields into a separate header file, but +for now I have judged that to be counter-productive. + +Similarly we need a generic bd_info structure, since generic code will +be accessing it. I have done this in the same way as global_data and the +same comments apply. + +There was dicussion on the list about passing gd_t around as a parameter +to pre-relocation init functions. I think this makes sense, but it can +be done as a separate change, and this series does not require it. + +While this series needs to stand on its own (as with the link script +cleanup series and the generic relocation series) the goal is the +unification of the board init code. So I hope we can address issues with +this in mind, rather than focusing too narrowly on particular ARM, x86 or +PPC issues. + +I have run-tested ARM on Tegra Seaboard only. To try it out, define +CONFIG_SYS_GENERIC_BOARD in your board file and rebuild. Most likely on +x86 and PPC at least it will hang, but if you are lucky it will print +something first :-) + +I have run this though MAKEALL with CONFIG_SYS_GENERIC_BOARD on for all +ARM, PPC and x86 boards. There are a few failures due to errors in +the board config, which I have sent patches for. The main issue is +just the difference between __bss_end and __bss_end__. + +Note: the first group of commits are required for this series to build, +but could be separated out if required. I have included them here for +convenience. + +------------->8-- + +Simon Glass, sjg@chromium.org +March 2014 +Updated after final removal, May 2016 diff --git a/roms/u-boot/doc/README.generic_usb_ohci b/roms/u-boot/doc/README.generic_usb_ohci new file mode 100644 index 000000000..65b0896c7 --- /dev/null +++ b/roms/u-boot/doc/README.generic_usb_ohci @@ -0,0 +1,63 @@ +Notes on the the generic USB-OHCI driver +======================================== + +This driver (drivers/usb/usb_ohci.[ch]) is the result of the merge of +various existing OHCI drivers that were basically identical beside +cpu/board dependant initalization. This initalization has been moved +into cpu/board directories and are called via the hooks below. + +Configuration options +---------------------- + + CONFIG_USB_OHCI_NEW: enable the new OHCI driver + + CONFIG_SYS_USB_OHCI_BOARD_INIT: call the board dependant hooks: + + - extern int board_usb_init(void); + - extern int usb_board_stop(void); + - extern int usb_cpu_init_fail(void); + + CONFIG_SYS_USB_OHCI_CPU_INIT: call the cpu dependant hooks: + + - extern int usb_cpu_init(void); + - extern int usb_cpu_stop(void); + - extern int usb_cpu_init_fail(void); + + CONFIG_SYS_USB_OHCI_REGS_BASE: defines the base address of the OHCI + registers + + CONFIG_SYS_USB_OHCI_SLOT_NAME: slot name + + CONFIG_SYS_USB_OHCI_MAX_ROOT_PORTS: maximal number of ports of the + root hub. + + +Endianness issues +------------------ + +The USB bus operates in little endian, but unfortunately there are +OHCI controllers that operate in big endian such as ppc4xx. For these the +config option + + CONFIG_SYS_OHCI_BE_CONTROLLER + +needs to be defined. + + +PCI Controllers +---------------- + +You'll need to define + + CONFIG_PCI_OHCI + +If you have several USB PCI controllers, define + + CONFIG_PCI_OHCI_DEVNO: number of the OHCI device in PCI list + +If undefined, the first instance found in PCI space will be used. + +PCI Controllers need to do byte swapping on register accesses, so they +should to define: + + CONFIG_SYS_OHCI_SWAP_REG_ACCESS diff --git a/roms/u-boot/doc/README.gpio b/roms/u-boot/doc/README.gpio new file mode 100644 index 000000000..548ff37b8 --- /dev/null +++ b/roms/u-boot/doc/README.gpio @@ -0,0 +1,42 @@ + +GPIO hog (CONFIG_GPIO_HOG) +-------- + +All the GPIO hog are initialized in gpio_hog_probe_all() function called in +board_r.c just before board_late_init() but you can also acces directly to +the gpio with gpio_hog_lookup_name(). + + +Example, for the device tree: + + tca6416@20 { + compatible = "ti,tca6416"; + reg = <0x20>; + #gpio-cells = <2>; + gpio-controller; + + env_reset { + gpio-hog; + input; + gpios = <6 GPIO_ACTIVE_LOW>; + }; + boot_rescue { + gpio-hog; + input; + line-name = "foo-bar-gpio"; + gpios = <7 GPIO_ACTIVE_LOW>; + }; + }; + +You can than access the gpio in your board code with: + + struct gpio_desc *desc; + int ret; + + ret = gpio_hog_lookup_name("boot_rescue", &desc); + if (ret) + return; + if (dm_gpio_get_value(desc) == 1) + printf("\nBooting into Rescue System\n"); + else if (dm_gpio_get_value(desc) == 0) + printf("\nBoot normal\n"); diff --git a/roms/u-boot/doc/README.gpt b/roms/u-boot/doc/README.gpt new file mode 100644 index 000000000..91e397d06 --- /dev/null +++ b/roms/u-boot/doc/README.gpt @@ -0,0 +1,315 @@ +# SPDX-License-Identifier: GPL-2.0+ +# +# Copyright (C) 2012 Samsung Electronics +# +# Lukasz Majewski <l.majewski@samsung.com> + +Glossary: +======== +- UUID -(Universally Unique Identifier) +- GUID - (Globally Unique ID) +- EFI - (Extensible Firmware Interface) +- UEFI - (Unified EFI) - EFI evolution +- GPT (GUID Partition Table) - it is the EFI standard part +- partitions - lists of available partitions (defined at u-boot): + ./include/configs/{target}.h + +Introduction: +============= +This document describes the GPT partition table format and usage of +the gpt command in u-boot. + +UUID introduction: +==================== + +GPT for marking disks/partitions is using the UUID. It is supposed to be a +globally unique value. A UUID is a 16-byte (128-bit) number. The number of +theoretically possible UUIDs is therefore about 3 x 10^38. +More often UUID is displayed as 32 hexadecimal digits, in 5 groups, +separated by hyphens, in the form 8-4-4-4-12 for a total of 36 characters +(32 digits and 4 hyphens) + +For instance, GUID of Basic data partition: EBD0A0A2-B9E5-4433-87C0-68B6B72699C7 +and GUID of Linux filesystem data: 0FC63DAF-8483-4772-8E79-3D69D8477DE4 + +Historically there are 5 methods to generate this number. The oldest one is +combining machine's MAC address and timer (epoch) value. + +Successive versions are using MD5 hash, random numbers and SHA-1 hash. All major +OSes and programming languages are providing libraries to compute UUID (e.g. +uuid command line tool). + +GPT brief explanation: +====================== + + Layout: + ------- + + -------------------------------------------------- + LBA 0 |Protective MBR | + ---------------------------------------------------------- + LBA 1 |Primary GPT Header | Primary + -------------------------------------------------- GPT + LBA 2 |Entry 1|Entry 2| Entry 3| Entry 4| + -------------------------------------------------- + LBA 3 |Entries 5 - 128 | + | | + | | + ---------------------------------------------------------- + LBA 34 |Partition 1 | + | | + ----------------------------------- + |Partition 2 | + | | + ----------------------------------- + |Partition n | + | | + ---------------------------------------------------------- + LBA -34 |Entry 1|Entry 2| Entry 3| Entry 4| Backup + -------------------------------------------------- GPT + LBA -33 |Entries 5 - 128 | + | | + | | + LBA -2 | | + -------------------------------------------------- + LBA -1 |Backup GPT Header | + ---------------------------------------------------------- + +For a legacy reasons, GPT's LBA 0 sector has a MBR structure. It is called +"protective MBR". +Its first partition entry ID has 0xEE value, and disk software, which is not +handling the GPT sees it as a storage device without free space. + +It is possible to define 128 linearly placed partition entries. + +"LBA -1" means the last addressable block (in the mmc subsystem: +"dev_desc->lba - 1") + +Primary/Backup GPT header: +---------------------------- +Offset Size Description + +0 8 B Signature ("EFI PART", 45 46 49 20 50 41 52 54) +8 4 B Revision (For version 1.0, the value is 00 00 01 00) +12 4 B Header size (in bytes, usually 5C 00 00 00 meaning 92 bytes) +16 4 B CRC32 of header (0 to header size), with this field zeroed + during calculation +20 4 B Reserved (ZERO); +24 8 B Current LBA (location of this header copy) +32 8 B Backup LBA (location of the other header copy) +40 8 B First usable LBA for partitions (primary partition table last + LBA + 1) +48 8 B Last usable LBA (secondary partition table first LBA - 1) +56 16 B Disk GUID (also referred as UUID on UNIXes) +72 8 B Partition entries starting LBA (always 2 in primary copy) +80 4 B Number of partition entries +84 4 B Size of a partition entry (usually 128) +88 4 B CRC32 of partition array +92 * Reserved; must be ZERO (420 bytes for a 512-byte LBA) + +TOTAL: 512 B + + +IMPORTANT: + +GPT headers and partition entries are protected by CRC32 (the POSIX CRC32). + +Primary GPT header and Backup GPT header have swapped values of "Current LBA" +and "Backup LBA" and therefore different CRC32 check-sum. + +CRC32 for GPT headers (field "CRC of header") are calculated up till +"Header size" (92), NOT 512 bytes. + +CRC32 for partition entries (field "CRC32 of partition array") is calculated for +the whole array entry ( Number_of_partition_entries * +sizeof(partition_entry_size (usually 128))) + +Observe, how Backup GPT is placed in the memory. It is NOT a mirror reflect +of the Primary. + + Partition Entry Format: + ---------------------- + Offset Size Description + + 0 16 B Partition type GUID (Big Endian) + 16 16 B Unique partition GUID in (Big Endian) + 32 8 B First LBA (Little Endian) + 40 8 B Last LBA (inclusive) + 48 8 B Attribute flags [+] + 56 72 B Partition name (text) + + Attribute flags: + Bit 0 - System partition + Bit 1 - Hide from EFI + Bit 2 - Legacy BIOS bootable + Bit 48-63 - Defined and used by the individual partition type + For Basic data partition : + Bit 60 - Read-only + Bit 62 - Hidden + Bit 63 - Not mount + +Creating GPT partitions in U-Boot: +============== + +To restore GUID partition table one needs to: +1. Define partition layout in the environment. + Format of partitions layout: + "uuid_disk=...;name=u-boot,size=60MiB,uuid=...; + name=kernel,size=60MiB,uuid=...;" + or + "uuid_disk=${uuid_gpt_disk};name=${uboot_name}, + size=${uboot_size},uuid=${uboot_uuid};" + + The fields 'name' and 'size' are mandatory for every partition. + The field 'start' is optional. + + If field 'size' of the last partition is 0, the partition is extended + up to the end of the device. + + The fields 'uuid' and 'uuid_disk' are optional if CONFIG_RANDOM_UUID is + enabled. A random uuid will be used if omitted or they point to an empty/ + non-existent environment variable. The environment variable will be set to + the generated UUID. The 'gpt guid' command reads the current value of the + uuid_disk from the GPT. + + The field 'bootable' is optional, it is used to mark the GPT partition + bootable (set attribute flags "Legacy BIOS bootable"). + "name=u-boot,size=60MiB;name=boot,size=60Mib,bootable;name=rootfs,size=0" + It can be used to locate bootable disks with command + "part list <interface> <dev> -bootable <varname>", + please check out doc/README.distro for use. + +2. Define 'CONFIG_EFI_PARTITION' and 'CONFIG_CMD_GPT' + +3. From u-boot prompt type: + gpt write mmc 0 $partitions + +Checking (validating) GPT partitions in U-Boot: +=============================================== + +Procedure is the same as above. The only change is at point 3. + +At u-boot prompt one needs to write: + gpt verify mmc 0 [$partitions] + +where [$partitions] is an optional parameter. + +When it is not provided, only basic checks based on CRC32 calculation for GPT +header and PTEs are performed. +When provided, additionally partition data - name, size and starting +offset (last two in LBA) - are compared with data defined in '$partitions' +environment variable. + +After running this command, return code is set to 0 if no errors found in +on non-volatile medium stored GPT. + +Following line can be used to assess if GPT verification has succeed: + +U-BOOT> gpt verify mmc 0 $partitions +U-BOOT> if test $? = 0; then echo "GPT OK"; else echo "GPT ERR"; fi + +Renaming GPT partitions from U-Boot: +==================================== + +GPT partition names are a mechanism via which userspace and U-Boot can +communicate about software updates and boot failure. The 'gpt guid', +'gpt read', 'gpt rename' and 'gpt swap' commands facilitate +programmatic renaming of partitions from bootscripts by generating and +modifying the partitions layout string. Here is an illustration of +employing 'swap' to exchange 'primary' and 'backup' partition names: + +U-BOOT> gpt swap mmc 0 primary backup + +Afterwards, all partitions previously named 'primary' will be named +'backup', and vice-versa. Alternatively, single partitions may be +renamed. In this example, mmc0's first partition will be renamed +'primary': + +U-BOOT> gpt rename mmc 0 1 primary + +The GPT functionality may be tested with the 'sandbox' board by +creating a disk image as described under 'Block Device Emulation' in +doc/arch/index.rst: + +=>host bind 0 ./disk.raw +=> gpt read host 0 +[ . . . ] +=> gpt swap host 0 name othername +[ . . . ] + +Modifying GPT partition layout from U-Boot: +=========================================== + +The entire GPT partition layout can be exported to an environment +variable and then modified enmasse. Users can change the partition +numbers, offsets, names and sizes. The resulting variable can used to +reformat the device. Here is an example of reading the GPT partitions +into a variable and then modifying them: + +U-BOOT> gpt read mmc 0 current_partitions +U-BOOT> env edit current_partitions +edit: uuid_disk=[...];name=part1,start=0x4000,size=0x4000,uuid=[...]; +name=part2,start=0xc000,size=0xc000,uuid=[...];[ . . . ] + +U-BOOT> gpt write mmc 0 $current_partitions +U-BOOT> gpt verify mmc 0 $current_partitions + +Partition type GUID: +==================== + +For created partition, the used partition type GUID is +PARTITION_BASIC_DATA_GUID (EBD0A0A2-B9E5-4433-87C0-68B6B72699C7). + +If you define 'CONFIG_PARTITION_TYPE_GUID', a optionnal parameter 'type' +can specify a other partition type guid: + + "uuid_disk=...;name=u-boot,size=60MiB,uuid=...; + name=kernel,size=60MiB,uuid=..., + type=0FC63DAF-8483-4772-8E79-3D69D8477DE4;" + +Some strings can be also used at the place of known GUID : + "system" = PARTITION_SYSTEM_GUID + (C12A7328-F81F-11D2-BA4B-00A0C93EC93B) + "mbr" = LEGACY_MBR_PARTITION_GUID + (024DEE41-33E7-11D3-9D69-0008C781F39F) + "msft" = PARTITION_MSFT_RESERVED_GUID + (E3C9E316-0B5C-4DB8-817D-F92DF00215AE) + "data" = PARTITION_BASIC_DATA_GUID + (EBD0A0A2-B9E5-4433-87C0-68B6B72699C7) + "linux" = PARTITION_LINUX_FILE_SYSTEM_DATA_GUID + (0FC63DAF-8483-4772-8E79-3D69D8477DE4) + "raid" = PARTITION_LINUX_RAID_GUID + (A19D880F-05FC-4D3B-A006-743F0F84911E) + "swap" = PARTITION_LINUX_SWAP_GUID + (0657FD6D-A4AB-43C4-84E5-0933C84B4F4F) + "lvm" = PARTITION_LINUX_LVM_GUID + (E6D6D379-F507-44C2-A23C-238F2A3DF928) + "u-boot-env" = PARTITION_U_BOOT_ENVIRONMENT + (3DE21764-95BD-54BD-A5C3-4ABE786F38A8) + + "uuid_disk=...;name=u-boot,size=60MiB,uuid=...; + name=kernel,size=60MiB,uuid=...,type=linux;" + +They are also used to display the type of partition in "part list" command. + + +Useful info: +============ + +Two programs, namely: 'gdisk' and 'parted' are recommended to work with GPT +recovery. Both are able to handle GUID partitions. +Please, pay attention at -l switch for parted. + +"uuid" program is recommended to generate UUID string. Moreover it can decode +(-d switch) passed in UUID string. It can be used to generate partitions UUID +passed to u-boot environment variables. +If optional CONFIG_RANDOM_UUID is defined then for any partition which environment +uuid is unset, uuid is randomly generated and stored in correspond environment +variable. + +note: +Each string block of UUID generated by program "uuid" is in big endian and it is +also stored in big endian in disk GPT. +Partitions layout can be printed by typing "mmc part". Note that each partition +GUID has different byte order than UUID generated before, this is because first +three blocks of GUID string are in Little Endian. diff --git a/roms/u-boot/doc/README.hwconfig b/roms/u-boot/doc/README.hwconfig new file mode 100644 index 000000000..b6ddb438c --- /dev/null +++ b/roms/u-boot/doc/README.hwconfig @@ -0,0 +1,50 @@ +To enable this feature just define CONFIG_HWCONFIG in your board +config file. + +This implements a simple hwconfig infrastructure: an +interface for software knobs to control hardware. + +This a is very simple implementation, i.e. it is implemented +via the `hwconfig' environment variable. Later we could write +some "hwconfig <enable|disable|list>" commands, ncurses +interface for Award BIOS-like interface, and frame-buffer +interface for AMI GUI[1] BIOS-like interface with mouse +support[2]. + +Current implementation details/limitations: + +1. Doesn't support options dependencies and mutual exclusion. + We can implement this by integrating apt-get[3] into Das + U-Boot. But I haven't bothered yet. + +2. Since we don't implement a hwconfig command, i.e. we're working + with the environment directly, there is no way to tell that + toggling a particular option will need a reboot to take + effect. So, for now it's advised to always reboot the + target after modifying the hwconfig variable. + +3. We support hwconfig options with arguments. For example, + + set hwconfig "dr_usb:mode=peripheral,phy_type=ulpi" + + This selects three hwconfig options: + 1. dr_usb - enable Dual-Role USB controller; + 2. dr_usb_mode:peripheral - USB in Function mode; + 3. dr_usb_phy_type:ulpi - USB should work with ULPI PHYs. + +The purpose of this simple implementation is to refine the +internal API and then we can continue improving the user +experience by adding more mature interfaces, like a hwconfig +command with bells and whistles. Or not adding, if we feel +that the current interface fits people's needs. + +[1] http://en.wikipedia.org/wiki/American_Megatrends +[2] Regarding ncurses and GUI with mouse support -- I'm just + kidding. +[3] The comment regarding apt-get is also a joke, meaning that + dependency tracking could be non-trivial. For example, for + enabling HW feature X we may need to disable Y, and turn Z + into reduced mode (like RMII-only interface for ethernet, + no MII). + + It's quite trivial to implement simple cases though. diff --git a/roms/u-boot/doc/README.i2c b/roms/u-boot/doc/README.i2c new file mode 100644 index 000000000..07cd8df85 --- /dev/null +++ b/roms/u-boot/doc/README.i2c @@ -0,0 +1,60 @@ +I2C Bus Arbitration +=================== + +While I2C supports multi-master buses this is difficult to get right. +The implementation on the master side in software is quite complex. +Clock-stretching and the arbitrary time that an I2C transaction can take +make it difficult to share the bus fairly in the face of high traffic. +When one or more masters can be reset independently part-way through a +transaction it is hard to know the state of the bus. + +U-Boot provides a scheme based on two 'claim' GPIOs, one driven by the +AP (Application Processor, meaning the main CPU) and one driven by the EC +(Embedded Controller, a small CPU aimed at handling system tasks). With +these they can communicate and reliably share the bus. This scheme has +minimal overhead and involves very little code. The scheme can survive +reboots by either side without difficulty. + +Since U-Boot runs on the AP, the terminology used is 'our' claim GPIO, +meaning the AP's, and 'their' claim GPIO, meaning the EC's. This terminology +is used by the device tree bindings in Linux also. + +The driver is implemented as an I2C mux, as it is in Linux. See +i2c-arb-gpio-challenge for the implementation. + +GPIO lines are shared between the AP and EC to manage the bus. The AP and EC +each have a 'bus claim' line, which is an output that the other can see. + +- AP_CLAIM: output from AP, signalling to the EC that the AP wants the bus +- EC_CLAIM: output from EC, signalling to the AP that the EC wants the bus + +The basic algorithm is to assert your line when you want the bus, then make +sure that the other side doesn't want it also. A detailed explanation is best +done with an example. + +Let's say the AP wants to claim the bus. It: + +1. Asserts AP_CLAIM +2. Waits a little bit for the other side to notice (slew time) +3. Checks EC_CLAIM. If this is not asserted, then the AP has the bus, and we + are done +4. Otherwise, wait for a few milliseconds (retry time) and see if EC_CLAIM is + released +5. If not, back off, release the claim and wait for a few more milliseconds + (retry time again) +6. Go back to 1 if things don't look wedged (wait time has expired) +7. Panic. The other side is hung with the CLAIM line set. + +The same algorithm applies on the EC. + +To release the bus, just de-assert the claim line. + +Typical delays are: +- slew time 10 us +- retry time 3 ms +- wait time - 50ms + +In general the traffic is fairly light, and in particular the EC wants access +to the bus quite rarely (maybe every 10s or 30s to check the battery). This +scheme works very nicely with very low contention. There is only a 10 us +wait for access to the bus assuming that the other side isn't using it. diff --git a/roms/u-boot/doc/README.iomux b/roms/u-boot/doc/README.iomux new file mode 100644 index 000000000..c428811ce --- /dev/null +++ b/roms/u-boot/doc/README.iomux @@ -0,0 +1,89 @@ +SPDX-License-Identifier: GPL-2.0+ +/* + * (C) Copyright 2008 + * Gary Jennejohn, DENX Software Engineering GmbH <garyj@denx.de> + */ + +U-Boot console multiplexing +=========================== + +HOW CONSOLE MULTIPLEXING WORKS +------------------------------ + +This functionality is controlled with CONFIG_CONSOLE_MUX in the board +configuration file. + +Two new files, common/iomux.c and include/iomux.h, contain the heart +(iomux_doenv()) of the environment setting implementation. + +iomux_doenv() is called in common/cmd_nvedit.c to handle setenv and in +common/console.c in console_init_r() during bootup to initialize +stdio_devices[]. + +A user can use a comma-separated list of devices to set stdin, stdout +and stderr. For example: "setenv stdin serial,nc". NOTE: No spaces +are allowed around the comma(s)! + +The length of the list is limited by malloc(), since the array used +is allocated and freed dynamically. + +It should be possible to specify any device which console_assign() +finds acceptable, but the code has only been tested with serial and +nc. + +iomux_doenv() prevents multiple use of the same device, e.g. "setenv +stdin nc,nc,serial" will discard the second nc. iomux_doenv() is +not able to modify the environment, however, so that "pri stdin" still +shows "nc,nc,serial". + +The major change in common/console.c was to modify fgetc() to call +the iomux_tstc() routine in a for-loop. iomux_tstc() in turn calls +the tstc() routine for every registered device, but exits immediately +when one of them returns true. fgetc() then calls iomux_getc(), +which calls the corresponding getc() routine. fgetc() hangs in +the for-loop until iomux_tstc() returns true and the input can be +retrieved. + +Thus, a user can type into any device registered for stdin. No effort +has been made to demulitplex simultaneous input from multiple stdin +devices. + +fputc() and fputs() have been modified to call iomux_putc() and +iomux_puts() respectively, which call the corresponding output +routines for every registered device. + +Thus, a user can see the ouput for any device registered for stdout +or stderr on all devices registered for stdout or stderr. As an +example, if stdin=serial,nc and stdout=serial,nc then all output +for serial, e.g. echos of input on serial, will appear on serial and nc. + +Just as with the old console code, this statement is still true: +If not defined in the environment, the first input device is assigned +to the 'stdin' file, the first output one to 'stdout' and 'stderr'. + +If CONFIG_SYS_CONSOLE_IS_IN_ENV is defined then multiple input/output +devices can be set at boot time if defined in the environment. + +CAVEATS +------- + +Note that common/iomux.c calls console_assign() for every registered +device as it is discovered. This means that the environment settings +for application consoles will be set to the last device in the list. + +On a slow machine, such as MPC852T clocked at 66MHz, the overhead associated +with calling tstc() and then getc() means that copy&paste will normally not +work, even when stdin=stdout=stderr=serial. +On a faster machine, such as a sequoia, cut&paste of longer (about 80 +characters) lines works fine when serial is the only device used. + +Using nc as a stdin device results in even more overhead because nc_tstc() +is quite slow. Even on a sequoia cut&paste does not work on the serial +interface when nc is added to stdin, although there is no character loss using +the ethernet interface for input. In this test case stdin=serial,nc and +stdout=serial. + +In addition, the overhead associated with sending to two devices, when one of +them is nc, also causes problems. Even on a sequoia cut&paste does not work +on the serial interface (stdin=serial) when nc is added to stdout (stdout= +serial,nc). diff --git a/roms/u-boot/doc/README.kconfig b/roms/u-boot/doc/README.kconfig new file mode 100644 index 000000000..0689f66c2 --- /dev/null +++ b/roms/u-boot/doc/README.kconfig @@ -0,0 +1,158 @@ +Kconfig in U-Boot +================= + +This document describes the configuration infrastructure of U-Boot. + +The conventional configuration was replaced by Kconfig at v2014.10-rc1 release. + + +Language Specification +---------------------- + +Kconfig originates in Linux Kernel. +See the file "Documentation/kbuild/kconfig*.txt" in your Linux Kernel +source directory for a basic specification of Kconfig. + + +Difference from Linux's Kconfig +------------------------------- + +Here are some worth-mentioning configuration targets. + +- silentoldconfig + + This target updates .config, include/generated/autoconf.h and + include/configs/* as in Linux. In U-Boot, it also does the following + for the compatibility with the old configuration system: + + * create a symbolic link "arch/${ARCH}/include/asm/arch" pointing to + the SoC/CPU specific header directory + * create include/config.h + * create include/autoconf.mk + * create spl/include/autoconf.mk (SPL and TPL only) + * create tpl/include/autoconf.mk (TPL only) + + If we could completely switch to Kconfig in a long run + (i.e. remove all the include/configs/*.h), those additional processings + above would be removed. + +- defconfig + + In U-Boot, "make defconfig" is a shorthand of "make sandbox_defconfig" + +- <board>_defconfig + + Now it works as in Linux. + The prefixes such as "+S:" in *_defconfig are deprecated. + You can simply remove the prefixes. Do not add them for new boards. + +- <board>_config + + This does not exist in Linux's Kconfig. + "make <board>_config" works the same as "make <board>_defconfig". + Prior to Kconfig, in U-Boot, "make <board>_config" was used for the + configuration. It is still supported for backward compatibility, so + we do not need to update the distro recipes. + + +The other configuration targets work as in Linux Kernel. + + +Migration steps to Kconfig +-------------------------- + +Prior to Kconfig, the C preprocessor based board configuration had been used +in U-Boot. + +Although Kconfig was introduced and some configs have been moved to Kconfig, +many of configs are still defined in C header files. It will take a very +long term to move all of them to Kconfig. In the interim, the two different +configuration infrastructures should coexist. +The configuration files are generated by both Kconfig and the old preprocessor +based configuration as follows: + +Configuration files for use in C sources + - include/generated/autoconf.h (generated by Kconfig for Normal) + - include/configs/<board>.h (exists for all boards) + +Configuration file for use in makefiles + - include/config/auto.conf (generated by Kconfig) + - include/autoconf.mk (generated by the old config for Normal) + - spl/include/autoconfig.mk (generated by the old config for SPL) + - tpl/include/autoconfig.mk (generated by the old config for TPL) + +When adding a new CONFIG macro, it is highly recommended to add it to Kconfig +rather than to a header file. + + +Conversion from boards.cfg to Kconfig +------------------------------------- + +Prior to Kconfig, boards.cfg was a primary database that contained Arch, CPU, +SoC, etc. of all the supported boards. It was deleted when switching to +Kconfig. Each field of boards.cfg was converted as follows: + + Status -> "S:" entry of MAINTAINERS + Arch -> CONFIG_SYS_ARCH defined by Kconfig + CPU -> CONFIG_SYS_CPU defined by Kconfig + SoC -> CONFIG_SYS_SOC defined by Kconfig + Vendor -> CONFIG_SYS_VENDOR defined by Kconfig + Board -> CONFIG_SYS_BOARD defined by Kconfig + Target -> File name of defconfig (configs/<target>_defconfig) + Options -> CONFIG_SYS_EXTRA_OPTIONS defined by Kconfig + Maintainers -> "M:" entry of MAINTAINERS + + +Tips to add/remove boards +------------------------- + +When adding a new board, the following steps are generally needed: + + [1] Add a header file include/configs/<target>.h + [2] Make sure to define necessary CONFIG_SYS_* in Kconfig: + Define CONFIG_SYS_CPU="cpu" to compile arch/<arch>/cpu/<cpu> + Define CONFIG_SYS_SOC="soc" to compile arch/<arch>/cpu/<cpu>/<soc> + Define CONFIG_SYS_VENDOR="vendor" to compile board/<vendor>/common/* + and board/<vendor>/<board>/* + Define CONFIG_SYS_BOARD="board" to compile board/<board>/* + (or board/<vendor>/<board>/* if CONFIG_SYS_VENDOR is defined) + Define CONFIG_SYS_CONFIG_NAME="target" to include + include/configs/<target>.h + [3] Add a new entry to the board select menu in Kconfig. + The board select menu is located in arch/<arch>/Kconfig or + arch/<arch>/*/Kconfig. + [4] Add a MAINTAINERS file + It is generally placed at board/<board>/MAINTAINERS or + board/<vendor>/<board>/MAINTAINERS + [5] Add configs/<target>_defconfig + +When removing an obsolete board, the following steps are generally needed: + + [1] Remove configs/<target>_defconfig + [2] Remove include/configs/<target>.h if it is not used by any other boards + [3] Remove board/<vendor>/<board>/* or board/<board>/* if it is not used + by any other boards + [4] Update MAINTAINERS if necessary + [5] Remove the unused entry from the board select menu in Kconfig + [6] Add an entry to doc/README.scrapyard + + +TODO +---- + +- The option field of boards.cfg, which was used for the pre-Kconfig + configuration, moved to CONFIG_SYS_EXTRA_OPTIONS verbatim now. + Board maintainers are expected to implement proper Kconfig options + and switch over to them. Eventually CONFIG_SYS_EXTRA_OPTIONS will go away. + CONFIG_SYS_EXTRA_OPTIONS should not be used for new boards. + +- In the pre-Kconfig, a single board had multiple entries in the boards.cfg + file with differences in the option fields. The corresponding defconfig + files were auto-generated when switching to Kconfig. Now we have too many + defconfig files compared with the number of the supported boards. It is + recommended to have only one defconfig per board and allow users to select + the config options. + +- Move the config macros in header files to Kconfig. When we move at least + macros used in makefiles, we can drop include/autoconfig.mk, which makes + the build scripts much simpler. diff --git a/roms/u-boot/doc/README.kwbimage b/roms/u-boot/doc/README.kwbimage new file mode 100644 index 000000000..762b2e3ac --- /dev/null +++ b/roms/u-boot/doc/README.kwbimage @@ -0,0 +1,104 @@ +--------------------------------------------- +Kirkwood Boot Image generation using mkimage +--------------------------------------------- + +This document describes the U-Boot feature as it +is implemented for the Kirkwood family of SoCs. + +The Kirkwood SoC's can boot directly from NAND FLASH, +SPI FLASH, SATA etc. using its internal bootRom support. + +for more details refer section 24.2 of Kirkwood functional specifications. +ref: www.marvell.com/products/embedded.../kirkwood/index.jsp + +Command syntax: +-------------- +./tools/mkimage -l <kwboot_file> + to list the kwb image file details + +./tools/mkimage -n <board specific configuration file> \ + -T kwbimage -a <start address> -e <execution address> \ + -d <input_raw_binary> <output_kwboot_file> + +for ex. +./tools/mkimage -n ./board/Marvell/openrd_base/kwbimage.cfg \ + -T kwbimage -a 0x00600000 -e 0x00600000 \ + -d u-boot.bin u-boot.kwb + + +kwbimage support available with mkimage utility will generate kirkwood boot +image that can be flashed on the board NAND/SPI flash. The make target +which uses mkimage to produce such an image is "u-boot.kwb". For example: + + export KBUILD_OUTPUT=/tmp/build + make distclean + make yourboard_config + make u-boot.kwb + + +Board specific configuration file specifications: +------------------------------------------------ +1. This file must present in the $(BOARDDIR). The default name is + kwbimage.cfg. The name can be set as part of the full path + to the file using CONFIG_SYS_KWD_CONFIG (probably in + include/configs/<yourboard>.h). The path should look like: + $(CONFIG_BOARDDIR)/<yourkwbimagename>.cfg +2. This file can have empty lines and lines starting with "#" as first + character to put comments +3. This file can have configuration command lines as mentioned below, + any other information in this file is treated as invalid. + +Configuration command line syntax: +--------------------------------- +1. Each command line is must have two strings, first one command or address + and second one data string +2. Following are the valid command strings and associated data strings:- + Command string data string + -------------- ----------- + BOOT_FROM nand/spi/sata + NAND_ECC_MODE default/rs/hamming/disabled + NAND_PAGE_SIZE any uint16_t hex value + SATA_PIO_MODE any uint32_t hex value + DDR_INIT_DELAY any uint32_t hex value + DATA regaddr and regdara hex value + you can have maximum 55 such register programming commands + +3. All commands are optional to program + +Typical example of kwimage.cfg file: +----------------------------------- + +# Boot Media configurations +BOOT_FROM nand +NAND_ECC_MODE default +NAND_PAGE_SIZE 0x0800 + +# Configure RGMII-0 interface pad voltage to 1.8V +DATA 0xFFD100e0 0x1b1b1b9b +# DRAM Configuration +DATA 0xFFD01400 0x43000c30 +DATA 0xFFD01404 0x37543000 +DATA 0xFFD01408 0x22125451 +DATA 0xFFD0140C 0x00000a33 +DATA 0xFFD01410 0x000000cc +DATA 0xFFD01414 0x00000000 +DATA 0xFFD01418 0x00000000 +DATA 0xFFD0141C 0x00000C52 +DATA 0xFFD01420 0x00000040 +DATA 0xFFD01424 0x0000F17F +DATA 0xFFD01428 0x00085520 +DATA 0xFFD0147C 0x00008552 +DATA 0xFFD01504 0x0FFFFFF1 +DATA 0xFFD01508 0x10000000 +DATA 0xFFD0150C 0x0FFFFFF5 +DATA 0xFFD01514 0x00000000 +DATA 0xFFD0151C 0x00000000 +DATA 0xFFD01494 0x00030000 +DATA 0xFFD01498 0x00000000 +DATA 0xFFD0149C 0x0000E803 +DATA 0xFFD01480 0x00000001 +# End of Header extension +DATA 0x0 0x0 + +------------------------------------------------ +Author: Prafulla Wadaskar <prafulla@marvell.com> diff --git a/roms/u-boot/doc/README.link-local b/roms/u-boot/doc/README.link-local new file mode 100644 index 000000000..148b4987f --- /dev/null +++ b/roms/u-boot/doc/README.link-local @@ -0,0 +1,75 @@ +------------------------------------------ + Link-local IP address auto-configuration +------------------------------------------ + +Negotiate with other link-local clients on the local network +for an address that doesn't require explicit configuration. +This is especially useful if a DHCP server cannot be guaranteed +to exist in all environments that the device must operate. + +This is an implementation of RFC3927. + +---------- + Commands +---------- + +When CONFIG_CMD_LINK_LOCAL is defined in the board config file, +the "linklocal" command is available. This running this will +take approximately 5 seconds while the address is negotiated. + +------------------------ + Environment interation +------------------------ + +The "llipaddr" variable is set with the most recently +negotiated address and is preferred in future negotiations. + +The "ipaddr", "netmask", and "gatewayip" variables are set +after successful negotiation to enable network access. + +------------- + Limitations +------------- + +RFC3927 requires that addresses are continuously checked to +avoid conflicts, however this can only happen when the net_loop +is getting called. It is possible for a conflict to go undetected +until a command that accesses the network is executed. + +Using NetConsole is one way to ensure that net_loop is always +processing packets and monitoring for conflicts. + +This is also not a concern if the feature is use to connect +directly to another machine that may not be running a DHCP server. + +---------------- + Example script +---------------- + +This script allows use of DHCP and/or Link-local controlled +by env variables. It depends on CONFIG_CMD_LINK_LOCAL, CONFIG_CMD_DHCP, +and CONFIG_BOOTP_MAY_FAIL. +If both fail or are disabled, static settings are used. + +#define CONFIG_EXTRA_ENV_SETTINGS \ + "ipconfigcmd=if test \\\"$dhcpenabled\\\" -ne 0;" \ + "then " \ + "dhcpfail=0;dhcp || dhcpfail=1;" \ + "else " \ + "dhcpfail=-1;" \ + "fi;" \ + "if test \\\"$linklocalenabled\\\" -ne 0 -a " \ + "\\\"$dhcpfail\\\" -ne 0;" \ + "then " \ + "linklocal;" \ + "llfail=0;" \ + "else " \ + "llfail=-1;" \ + "fi;" \ + "if test \\\"$llfail\\\" -ne 0 -a " \ + "\\\"$dhcpfail\\\" -ne 0; " \ + "then " \ + "setenv ipaddr $sipaddr; " \ + "setenv netmask $snetmask; " \ + "setenv gatewayip $sgatewayip; " \ + "fi;\0" \ diff --git a/roms/u-boot/doc/README.lynxkdi b/roms/u-boot/doc/README.lynxkdi new file mode 100644 index 000000000..076f01862 --- /dev/null +++ b/roms/u-boot/doc/README.lynxkdi @@ -0,0 +1,57 @@ + LYNX KDI SUPPORT + + Last Update: July 20, 2003 +======================================================================= + +This file describes support for LynuxWorks KDI within U-Boot. Support +is enabled by defining CONFIG_LYNXKDI. + + +LYNXOS AND BLUECAT SUPPORTED +============================ +Both LynxOS and BlueCat linux KDIs are supported. The implementation +automatically detects which is being booted. When you use mkimage +you should specify "lynxos" for both (see target-specific notes). + + +SUPPORTED ARCHITECTURE/TARGETS +============================== +The following targets have been tested: + +-PowerPC MPC8260ADS + + +FILES TO LOOK AT +================ +include/lynxkdi.h -defines a simple struct passed to a kdi. +common/lynxkdi.c -implements the call to the kdi. +common/cmd_bootm.c -top-level command implementation ("bootm"). + + +==================================================================== +TARGET SPECIFIC NOTES +==================================================================== + +MPC8260ADS +=========== +The default LynxOS and BlueCat implementations require some +modifications to the config file. + +Edit include/configs/MPC8260ADS.h to use the following: + +#define CONFIG_SYS_IMMR 0xFA200000 +#define CONFIG_SYS_BCSR 0xFA100000 +#define CONFIG_SYS_BR1_PRELIM 0xFA101801 + +When creating a LynxOS or BlueCat u-boot image using mkimage, +you must specify the following: + +Both: -A ppc -O lynxos -T kernel -C none +LynxOS: -a 0x00004000 -e 0x00004020 +BlueCat: -a 0x00500000 -e 0x00507000 + +To pass the MAC address to BlueCat you should define the +"fcc2_ether_addr" parameter in the "bootargs" environment +variable. E.g.: + +==> setenv bootargs fcc2_ether_addr=00:11:22:33:44:55:66 diff --git a/roms/u-boot/doc/README.m54418twr b/roms/u-boot/doc/README.m54418twr new file mode 100644 index 000000000..0ca74aa11 --- /dev/null +++ b/roms/u-boot/doc/README.m54418twr @@ -0,0 +1,245 @@ +Freescale MCF54418TWR ColdFire Development Board +================================================ + +TsiChung Liew(Tsi-Chung.Liew@freescale.com) +Created Mar 22, 2012 +=========================================== + + +Changed files: +============== + +- board/freescale/m54418twr/m54418twr.c Dram setup +- board/freescale/m54418twr/Makefile Makefile +- board/freescale/m54418twr/config.mk config make +- board/freescale/m54418twr/u-boot.lds Linker description +- board/freescale/m54418twr/sbf_dram_init.S + DDR/SDRAM initialization + +- arch/m68k/cpu/mcf5445x/cpu.c cpu specific code +- arch/m68k/cpu/mcf5445x/cpu_init.c Flexbus ChipSelect, Mux pins setup, icache and RTC extra regs +- arch/m68k/cpu/mcf5445x/interrupts.c cpu specific interrupt support +- arch/m68k/cpu/mcf5445x/speed.c system, pci, flexbus, and cpu clock +- arch/m68k/cpu/mcf5445x/Makefile Makefile +- arch/m68k/cpu/mcf5445x/config.mk config make +- arch/m68k/cpu/mcf5445x/start.S start up assembly code + +- doc/README.m54418twr This readme file + +- drivers/net/mcffec.c ColdFire common FEC driver +- drivers/net/mcfmii.c ColdFire common MII driver +- drivers/serial/mcfuart.c ColdFire common UART driver + +- arch/m68k/include/asm/bitops.h Bit operation function export +- arch/m68k/include/asm/byteorder.h Byte order functions +- arch/m68k/include/asm/fec.h FEC structure and definition +- arch/m68k/include/asm/global_data.h Global data structure +- arch/m68k/include/asm/immap.h ColdFire specific header file and driver macros +- arch/m68k/include/asm/immap_5441x.h mcf5441x specific header file +- arch/m68k/include/asm/io.h io functions +- arch/m68k/include/asm/m5441x.h mcf5441x specific header file +- arch/m68k/include/asm/posix_types.h Posix +- arch/m68k/include/asm/processor.h header file +- arch/m68k/include/asm/ptrace.h Exception structure +- arch/m68k/include/asm/rtc.h Realtime clock header file +- arch/m68k/include/asm/string.h String function export +- arch/m68k/include/asm/timer.h Timer structure and definition +- arch/m68k/include/asm/types.h Data types definition +- arch/m68k/include/asm/uart.h Uart structure and definition +- arch/m68k/include/asm/u-boot.h u-boot structure + +- include/configs/M54418TWR.h Board specific configuration file + +- arch/m68k/lib/board.c board init function +- arch/m68k/lib/cache.c +- arch/m68k/lib/interrupts.c Coldfire common interrupt functions +- arch/m68k/lib/time.c Timer functions (Dma timer and PIT) +- arch/m68k/lib/traps.c Exception init code + +1 MCF5441x specific Options/Settings +==================================== +1.1 pre-loader is no longer suppoer in thie coldfire family + +1.2 Configuration settings for M54418TWR Development Board +CONFIG_MCF5441x -- define for all MCF5441x CPUs +CONFIG_M54418 -- define for all Freescale MCF54418 CPUs + +CONFIG_MCFUART -- define to use common CF Uart driver +CONFIG_SYS_UART_PORT -- define UART port number, start with 0, 1 and 2 +CONFIG_BAUDRATE -- define UART baudrate + +CONFIG_MCFFEC -- define to use common CF FEC driver +CONFIG_MII -- enable to use MII driver +CONFIG_SYS_DISCOVER_PHY -- enable PHY discovery +CONFIG_SYS_RX_ETH_BUFFER -- Set FEC Receive buffer +CONFIG_SYS_FAULT_ECHO_LINK_DOWN -- +CONFIG_SYS_FEC0_PINMUX -- Set FEC0 Pin configuration +CONFIG_SYS_FEC1_PINMUX -- Set FEC1 Pin configuration +CONFIG_SYS_FEC0_MIIBASE -- Set FEC0 MII base register +CONFIG_SYS_FEC1_MIIBASE -- Set FEC0 MII base register +MCFFEC_TOUT_LOOP -- set FEC timeout loop +CONFIG_HAS_ETH1 -- define to enable second FEC in u-boot + +CONFIG_MCFTMR -- define to use DMA timer + +CONFIG_SYS_IMMR -- define for MBAR offset + +CONFIG_EXTRA_CLOCK -- Enable extra clock such as vco, flexbus, pci, etc + +CONFIG_SYS_MBAR -- define MBAR offset + +CONFIG_MONITOR_IS_IN_RAM -- Not support + +CONFIG_SYS_INIT_RAM_ADDR -- defines the base address of the MCF54455 internal SRAM + +CONFIG_SYS_CSn_BASE -- defines the Chip Select Base register +CONFIG_SYS_CSn_MASK -- defines the Chip Select Mask register +CONFIG_SYS_CSn_CTRL -- defines the Chip Select Control register + +CONFIG_SYS_SDRAM_BASE -- defines the DRAM Base + +2. MEMORY MAP UNDER U-BOOT AND LINUX KERNEL +=========================================== +2.1. System memory map: + MRAM: 0x00000000-0x0003FFFF (256KB) + DDR: 0x40000000-0x47FFFFFF (128MB) + SRAM: 0x80000000-0x8000FFFF (64KB) + IP: 0xE0000000-0xFFFFFFFF (512MB) + +3. COMPILATION +============== +3.1 To create U-Boot the gcc-4.x compiler set (ColdFire ELF version) +from codesourcery.com was used. Download it from: +http://www.codesourcery.com/gnu_toolchains/coldfire/download.html + +3.2 Compilation + export CROSS_COMPILE=cross-compile-prefix + cd u-boot + make distclean + make M54418TWR_config, or - default to spi serial flash boot, 50Mhz input clock + make M54418TWR_nand_mii_config, or - default to nand flash boot, mii mode, 25Mhz input clock + make M54418TWR_nand_rmii_config, or - default to nand flash boot, rmii mode, 50Mhz input clock + make M54418TWR_nand_rmii_lowfreq_config, or - default to nand flash boot, rmii mode, 50Mhz input clock + make M54418TWR_serial_mii_config, or - default to spi serial flash boot, 25Mhz input clock + make M54418TWR_serial_rmii_config, or - default to spi serial flash boot, 50Mhz input clock + make + +4. SCREEN DUMP +============== +4.1 M54418TWR Development board + Boot from NAND flash (NOTE: May not show exactly the same) + +U-Boot 2012.10-00209-g12ae1d8-dirty (Oct 18 2012 - 15:54:54) + +CPU: Freescale MCF54418 (Mask:a3 Version:1) + CPU CLK 250 MHz BUS CLK 125 MHz FLB CLK 125 MHz + INP CLK 50 MHz VCO CLK 500 MHz +Board: Freescale MCF54418 Tower System +SPI: ready +DRAM: 128 MiB +NAND: 256 MiB +In: serial +Out: serial +Err: serial +Net: FEC0, FEC1 +-> pri +baudrate=115200 +bootargs=root=/dev/mtdblock2 rw rootfstype=jffs2 mtdparts=NAND:1M(u-boot)ro,7M(k +ernel)ro,-(jffs2) console=ttyS0,115200 +bootdelay=2 +eth1addr=00:e0:0c:bc:e5:61 +ethact=FEC0 +ethaddr=00:e0:0c:bc:e5:60 +fileaddr=40010000 +filesize=27354 +gatewayip=192.168.1.1 +hostname=M54418TWR +inpclk=50000000 +ipaddr=192.168.1.2 +load=tftp ${loadaddr} ${u-boot}; +loadaddr=0x40010000 +mem=129024k +netdev=eth0 +netmask=255.255.255.0 +prog=nand device 0;nand erase 0 40000;nb_update ${loadaddr} ${filesize};save +serverip=192.168.1.1 +stderr=serial +stdin=serial +stdout=serial +u-boot=u-boot.bin +upd=run load; run prog + +Environment size: 653/131068 bytes +-> bdinfo +memstart = 0x40000000 +memsize = 0x08000000 +flashstart = 0x00000000 +flashsize = 0x00000000 +flashoffset = 0x00000000 +sramstart = 0x80000000 +sramsize = 0x00010000 +mbar = 0xFC000000 +cpufreq = 250 MHz +busfreq = 125 MHz +flbfreq = 125 MHz +inpfreq = 50 MHz +vcofreq = 500 MHz +ethaddr = 00:e0:0c:bc:e5:60 +eth1addr = 00:e0:0c:bc:e5:61 +ip_addr = 192.168.1.2 +baudrate = 115200 bps +-> help +? - alias for 'help' +base - print or set address offset +bdinfo - print Board Info structure +boot - boot default, i.e., run 'bootcmd' +bootd - boot default, i.e., run 'bootcmd' +bootelf - Boot from an ELF image in memory +bootm - boot application image from memory +bootp - boot image via network using BOOTP/TFTP protocol +bootvx - Boot vxWorks from an ELF image +cmp - memory compare +coninfo - print console devices and information +cp - memory copy +crc32 - checksum calculation +dcache - enable or disable data cache +dhcp - boot image via network using DHCP/TFTP protocol +echo - echo args to console +editenv - edit environment variable +env - environment handling commands +exit - exit script +false - do nothing, unsuccessfully +go - start application at address 'addr' +help - print command description/usage +icache - enable or disable instruction cache +iminfo - print header information for application image +imxtract- extract a part of a multi-image +itest - return true/false on integer compare +loop - infinite loop on address range +md - memory display +mdio - MDIO utility commands +mii - MII utility commands +mm - memory modify (auto-incrementing address) +mtest - simple RAM read/write test +mw - memory write (fill) +nand - NAND sub-system +nb_update- Nand boot update program +nboot - boot from NAND device +nfs - boot image via network using NFS protocol +nm - memory modify (constant address) +ping - send ICMP ECHO_REQUEST to network host +printenv- print environment variables +reginfo - print register information +reset - Perform RESET of the CPU +run - run commands in an environment variable +saveenv - save environment variables to persistent storage +setenv - set environment variables +sf - SPI flash sub-system +showvar - print local hushshell variables +sleep - delay execution for some time +source - run script from memory +sspi - SPI utility command +test - minimal test like /bin/sh +tftpboot- boot image via network using TFTP protocol +true - do nothing, successfully +version - print monitor, compiler and linker version diff --git a/roms/u-boot/doc/README.malta b/roms/u-boot/doc/README.malta new file mode 100644 index 000000000..8614696a5 --- /dev/null +++ b/roms/u-boot/doc/README.malta @@ -0,0 +1,16 @@ +MIPS Malta board + +How to flash using a MIPS Navigator Probe: + + - Ensure that your Malta has jumper JP1 fitted. Without this jumper you will + be unable to flash your Malta using a Navigator Probe. + + - Connect Navigator Console to your probe and Malta as usual. + + - Within Navigator Console run the following commands: + + source /path/to/u-boot/board/imgtec/malta/flash-malta-boot.tcl + reset + flash-boot /path/to/u-boot/u-boot.bin + + - You should now be able to reboot your Malta to a U-Boot shell. diff --git a/roms/u-boot/doc/README.marvell b/roms/u-boot/doc/README.marvell new file mode 100644 index 000000000..6fc5ac8a4 --- /dev/null +++ b/roms/u-boot/doc/README.marvell @@ -0,0 +1,98 @@ +Marvell U-Boot Build Instructions +================================= + +This document describes how to compile the U-Boot and how to change U-Boot configuration + +Build Procedure +---------------- +1. Install required packages: + + # sudo apt-get install libssl-dev + # sudo apt-get install device-tree-compiler + # sudo apt-get install swig libpython-dev + +2. Set the cross compiler: + + # sudo apt-get install gcc-aarch64-linux-gnu + # export CROSS_COMPILE=aarch64-linux-gnu- + +3. Clean-up old residuals: + + # make mrproper + +4. Configure the U-Boot: + + # make <defconfig_file> + + - For the Armada-70x0/80x0 DB board use "mvebu_db_armada8k_defconfig" + - For the Armada-80x0 MacchiatoBin use "make mvebu_mcbin-88f8040_defconfig" + - For the Armada-3700 DB board use "make mvebu_db-88f3720_defconfig" + - For the Armada-3700 EspressoBin use "make mvebu_espressobin-88f3720_defconfig" + +5. Configure the device-tree and build the U-Boot image: + + For the Armada-70x0/80x0 DB board compile u-boot and set the required device-tree using: + + # make DEVICE_TREE=<name> + + NOTE: + Compilation with "mvebu_db_armada8k_defconfig" requires explicitly exporting DEVICE_TREE + for the requested board. + By default, u-boot is compiled with armada-8040-db device-tree. + Using A80x0 device-tree on A70x0 might break the device. + In order to prevent this, the required device-tree MUST be set during compilation. + All device-tree files are located in ./arch/arm/dts/ folder. + + For other DB boards (MacchiatoBin, EspressoBin and 3700 DB board) compile u-boot with + just default device-tree from defconfig using: + + # make + + NOTE: + The u-boot.bin should not be used as a stand-alone image. + The ARM Trusted Firmware (ATF) build process uses this image to generate the + flash image. See TF-A Build Instructions for Marvell Platforms for more details at: + https://trustedfirmware-a.readthedocs.io/en/latest/plat/marvell/armada/build.html + +Configuration update +--------------------- + To update the U-Boot configuration, please refer to doc/README.kconfig + + +Permanent ethernet MAC address +------------------------------- + Prior flashing new U-Boot version (as part of ATF image) it is suggested to backup + permanent ethernet MAC addresses as they are stored only in U-Boot env storage (SPI or eMMC). + Some boards like EspressoBin have MAC addresses printed on sticker. Some boards got assigned + only one address other may also more than one. To print current MAC addresses run: + + # echo $ethaddr + # echo $eth1addr + # echo $eth2addr + # echo $eth3addr + # ... + + MAC addresses 00:51:82:11:22:00, 00:51:82:11:22:01, 00:51:82:11:22:02, 00:51:82:11:22:03 + and F0:AD:4E:03:64:7F are default hardcoded values found in Marvell's and Armbian U-Boot + forks and therefore *not* unique. Usage of static hardcoded MAC addresses should be avoided. + When original address is lost (e.g. erased by Armbian boot scripts for EspressoBin) it is + suggested to generate new random one. + + After flashing new U-Boot version it is suggested to reset U-Boot env variables to default + and then set correct permanent ethernet MAC addresses. + + # env default -a + # setenv ethaddr XX:XX:XX:XX:XX:XX + # setenv eth1addr XX:XX:XX:XX:XX:XX + # setenv eth2addr YY:YY:YY:YY:YY:YY + # setenv eth3addr ZZ:ZZ:ZZ:ZZ:ZZ:ZZ + # ... + # saveenv + + Where value for ethaddr is required permanent ethernet MAC address and values for ethNaddr + are optional per-port MAC addresses. When optional ethNaddr variables are not defined then + they are inherited from required ethaddr variable. eth1addr contains MAC address for the + wan port, other for particular lan ports. + + Recent Linux kernel versions use correct permanent ethernet MAC address from U-Boot env as + U-Boot will inject it into kernel's device-tree. diff --git a/roms/u-boot/doc/README.mediatek b/roms/u-boot/doc/README.mediatek new file mode 100644 index 000000000..246579d4b --- /dev/null +++ b/roms/u-boot/doc/README.mediatek @@ -0,0 +1,221 @@ +# SPDX-License-Identifier: GPL-2.0+ +# +# Copyright (C) 2018 MediaTek Inc. +# Ryder Lee <ryder.lee@kernel.org> + + +This document describes how to compile the U-Boot and how to change U-Boot +configuration about the MediaTek SoCs. + + +Build Procedure +=============== + -Set the cross compiler: + + # export CROSS_COMPILE=/path/to/toolchain/arm-linux-gnueabi- + + -Clean-up old residuals: + + # make mrproper + + -Configure the U-Boot: + + # make <defconfig_file> + # make + + - For the MT7623n bananapi R2 board use "mt7623n_bpir2_defconfig" + - For the MT7629 reference board use "mt7629_rfb_defconfig" + + +Boot sequence +============= + -Bootrom -> MTK preloader -> U-Boot + + - MT7623n + + This version of U-Boot doesn't implement SPL. So, MTK preloader binary + is needed to boot up: + + https://github.com/BPI-SINOVOIP/BPI-R2-bsp/tree/master/mt-pack/mtk/bpi-r2/bin + + + -Bootrom -> SPL -> U-Boot + + - MT7629 + + +Configuration update +==================== + To update the U-Boot configuration, please refer to doc/README.kconfig + + +MediaTek image header +===================== +Currently there are two image headers used for MediaTek chips: + + - BootROM image header. This header is used by the first stage bootloader. It records + the desired compatible boot device, integrity information and its load address. + + The on-chip BootROM will firstly verify integrity and compatibility of the bootloader. + + If verification passed, the BootROM will then load the bootloader into on-chip SRAM, + and pass control to it. + + Note that this header is actually a combination of three independent headers: + Device header, BRLYT header and GFH header. + + Used by U-Boot SPL of MT7629 and preloader of MT7623. + + + - MediaTek legacy image header. This header was originally used by the legacy image. It + basically records the load address, image size and image name. + + After all low level initializations passed, the preloader will locate the LK image and + load it into DRAM, and pass control to it. + + Now this header is used by U-Boot of MT7623. + + +To generate these two headers with mkimage: + + # mkimage -T mtk_image -a <load_addr> -n <option_string> -d <input_file> <image_file> + + - mtk_image means using MediaTek's header generation method. + + + - load_addr is the load address of this image. + For first stage bootloader like U-Boot SPL or preloader, it usually points to the + on-chip SRAM. + + For second stage bootloader like U-Boot, it usually points to the DRAM. + + + - option_string contains options to generate the header. + + The option string is using the follow format: + key1=value1;key2=value2;... + + The following key names are valid: + lk: If lk=1, LK image header is used. Otherwise BootROM image header is used. + + lkname: The name of the LK image header. The maximum length is 32. + The default value is "U-Boot". + + media: Desired boot device. The valid values are: + nand : Parallel NAND + snand: Serial NAND + nor : Serial NOR + emmc : eMMC + sdmmc: SD + + nandinfo: Desired NAND device type, a combination of page size, oob size and + optional device capacity. Valid types are: + 2k+64 : for Serial NAND, 2KiB page size + 64B oob size + 2k+120 : for Serial NAND, 2KiB page size + 120B oob size + 2k+128 : for Serial NAND, 2KiB page size + 128B oob size + 4k+256 : for Serial NAND, 4KiB page size + 256B oob size + 1g:2k+64 : for Parallel NAND, 2KiB page size + 64B oob size, total 1Gbit size + 2g:2k+64 : for Parallel NAND, 2KiB page size + 64B oob size, total 2Gbit size + 4g:2k+64 : for Parallel NAND, 2KiB page size + 64B oob size, total 4Gbit size + 2g:2k+128: for Parallel NAND, 2KiB page size + 128B oob size, total 2Gbit size + 4g:2k+128: for Parallel NAND, 2KiB page size + 128B oob size, total 4Gbit size + + +MT7629 partitions on Serial NOR +=============================== + + Start End Size Description + 00000000 - 0000ffff: 64KiB U-Boot SPL + 00010000 - 0005ffff: 320KiB U-Boot + 00060000 - 0006ffff: 64KiB U-Boot env / MediaTek NVRAM + 00070000 - 000affff: 256KiB RF calibration data + 000b0000 - xxxxxxxx: all left Firmware image + + +BPi-R2 (MT7623N) partitions on SD +================================= + Please note that the last two partitions can vary from different Linux distributions + depending on the MBR partition table. + + Start End Size Description + 00000000 - 000001ff: 512B Device header (with MBR partition table) + 00000200 - 000007ff: 1536B BRLYT header + 00000800 - 0004ffff: 318KiB Preloader (with GFH header) + 00050000 - 000fffff: 704KiB U-Boot + 00100000 - 063fffff: 99MiB Reserved + 06400000 - 163fffff: 256MiB Partition 1 (FAT32) + 16400000 - xxxxxxxx: all left Partition 2 (ext4) + + +Upgrading notice on Serial NOR +============================== +Example: MT7629 + + The command sf is used to operate the Serial NOR device: + + - To probe current NOR flash: + + # sf probe + + - To erase a region: + + # sf erase <offset> <len> + + - To write data to an offset: + + # sf write <data_addr> <offset> <len> + + - To boot kernel: + + # bootm 0x300b0000 + + The memory address range 0x30000000 - 0x3fffffff is mapped to the NOR flash. + The DRAM starts at 0x40000000. + + Please note that the output binary u-boot-mtk.bin is a combination of SPL and U-Boot, + and it should be write to beginning of the flash. + + Otherwise you should use standalone files: + + spl/u-boot-spl-mtk.bin for SPL, + u-boot.img for U-Boot. + + +Upgrading notice on SD / eMMC +============================= +Example: MT7623 + + Normally only Preloader and U-Boot can be upgraded within U-Boot, and other partitions + should be written in PC. + + - To probe current SD card / eMMC: + + # mmc dev 0 for eMMC + # mmc dev 1 for SD + + - To erase a region: + + # mmc erase <blk_offset> <blk_num> + + - To write data to a block offset: + + # mmc write <data_addr> <blk_offset> <blk_num> + + - To load kernel image from partition 1: + + # fatload mmc 0:1 <load_address> <path_to_kernel_uImage> for eMMC + # fatload mmc 1:1 <load_address> <path_to_kernel_uImage> for SD + + - To boot kernel: + + # bootm <load_address> + + The DRAM starts at 0x80000000. + + Please note that we use block offset and block count for SD card, not the byte offset. + The block size is always 512 bytes for SD card. + + +Documentation +============= + http://wiki.banana-pi.org/Banana_Pi_BPI-R2 diff --git a/roms/u-boot/doc/README.memory-test b/roms/u-boot/doc/README.memory-test new file mode 100644 index 000000000..eb60e8d83 --- /dev/null +++ b/roms/u-boot/doc/README.memory-test @@ -0,0 +1,98 @@ +The most frequent cause of problems when porting U-Boot to new +hardware, or when using a sloppy port on some board, is memory errors. +In most cases these are not caused by failing hardware, but by +incorrect initialization of the memory controller. So it appears to +be a good idea to always test if the memory is working correctly, +before looking for any other potential causes of any problems. + +U-Boot implements 3 different approaches to perform memory tests: + +1. The get_ram_size() function (see "common/memsize.c"). + + This function is supposed to be used in each and every U-Boot port + determine the presence and actual size of each of the potential + memory banks on this piece of hardware. The code is supposed to be + very fast, so running it for each reboot does not hurt. It is a + little known and generally underrated fact that this code will also + catch 99% of hardware related (i. e. reliably reproducible) memory + errors. It is strongly recommended to always use this function, in + each and every port of U-Boot. + +2. The "mtest" command. + + This is probably the best known memory test utility in U-Boot. + Unfortunately, it is also the most problematic, and the most + useless one. + + There are a number of serious problems with this command: + + - It is terribly slow. Running "mtest" on the whole system RAM + takes a _long_ time before there is any significance in the fact + that no errors have been found so far. + + - It is difficult to configure, and to use. And any errors here + will reliably crash or hang your system. "mtest" is dumb and has + no knowledge about memory ranges that may be in use for other + purposes, like exception code, U-Boot code and data, stack, + malloc arena, video buffer, log buffer, etc. If you let it, it + will happily "test" all such areas, which of course will cause + some problems. + + - It is not easy to configure and use, and a large number of + systems are seriously misconfigured. The original idea was to + test basically the whole system RAM, with only exempting the + areas used by U-Boot itself - on most systems these are the areas + used for the exception vectors (usually at the very lower end of + system memory) and for U-Boot (code, data, etc. - see above; + these are usually at the very upper end of system memory). But + experience has shown that a very large number of ports use + pretty much bogus settings of CONFIG_SYS_MEMTEST_START and + CONFIG_SYS_MEMTEST_END; this results in useless tests (because + the ranges is too small and/or badly located) or in critical + failures (system crashes). + + Because of these issues, the "mtest" command is considered depre- + cated. It should not be enabled in most normal ports of U-Boot, + especially not in production. If you really need a memory test, + then see 1. and 3. above resp. below. + +3. The most thorough memory test facility is available as part of the + POST (Power-On Self Test) sub-system, see "post/drivers/memory.c". + + If you really need to perform memory tests (for example, because + it is mandatory part of your requirement specification), then + enable this test which is generic and should work on all archi- + tectures. + +WARNING: + +It should pointed out that _all_ these memory tests have one +fundamental, unfixable design flaw: they are based on the assumption +that memory errors can be found by writing to and reading from memory. +Unfortunately, this is only true for the relatively harmless, usually +static errors like shorts between data or address lines, unconnected +pins, etc. All the really nasty errors which will first turn your +hair gray, only to make you tear it out later, are dynamical errors, +which usually happen not with simple read or write cycles on the bus, +but when performing back-to-back data transfers in burst mode. Such +accesses usually happen only for certain DMA operations, or for heavy +cache use (instruction fetching, cache flushing). So far I am not +aware of any freely available code that implements a generic, and +efficient, memory test like that. The best known test case to stress +a system like that is to boot Linux with root file system mounted over +NFS, and then build some larger software package natively (say, +compile a Linux kernel on the system) - this will cause enough context +switches, network traffic (and thus DMA transfers from the network +controller), varying RAM use, etc. to trigger any weak spots in this +area. + +Note: An attempt was made once to implement such a test to catch +memory problems on a specific board. The code is pretty much board +specific (for example, it includes setting specific GPIO signals to +provide triggers for an attached logic analyzer), but you can get an +idea how it works: see "examples/standalone/test_burst*". + +Note 2: Ironically enough, the "test_burst" did not catch any RAM +errors, not a single one ever. The problems this code was supposed +to catch did not happen when accessing the RAM, but when reading from +NOR flash. diff --git a/roms/u-boot/doc/README.mpc74xx b/roms/u-boot/doc/README.mpc74xx new file mode 100644 index 000000000..f81f1c2e8 --- /dev/null +++ b/roms/u-boot/doc/README.mpc74xx @@ -0,0 +1,22 @@ +This file contains status information for the port of U-Boot to the +Motorola mpc74xx series of CPUs. + +Author: Josh Huber <huber@mclx.com> + Mission Critical Linux, Inc. + +Currently the support for these CPUs is pretty minimal, but enough to +get things going. (much like the support for the Galileo Eval Board) + +There is a framework in place to enable the L2 cache, and to program +the BATs. Currently, there are still problems with the code which +sets up the L2 cache, so it's not enabled. (IMHO, it shouldn't be +anyway). Additionally, there is support for enabling the MMU, which +we also don't do. The BATs are programmed just for the benefit of +jumping into Linux in a sane configuration. + +Most of the code was based on other cpus supported by U-Boot. + +If you find any errors in the CPU setup code, please send us a note. + +Thanks, +Josh diff --git a/roms/u-boot/doc/README.mpc83xx.ddrecc b/roms/u-boot/doc/README.mpc83xx.ddrecc new file mode 100644 index 000000000..0029f0875 --- /dev/null +++ b/roms/u-boot/doc/README.mpc83xx.ddrecc @@ -0,0 +1,154 @@ +Overview +======== + +The overall usage pattern for ECC diagnostic commands is the following: + + * (injecting errors is initially disabled) + + * define inject mask (which tells the DDR controller what type of errors + we'll be injecting: single/multiple bit etc.) + + * enable injecting errors - from now on the controller injects errors as + indicated in the inject mask + +IMPORTANT NOTICE: enabling injecting multiple-bit errors is potentially +dangerous as such errors are NOT corrected by the controller. Therefore caution +should be taken when enabling the injection of multiple-bit errors: it is only +safe when used on a carefully selected memory area and used under control of +the 'ecc testdw' 'ecc testword' command (see example 'Injecting Multiple-Bit +Errors' below). In particular, when you simply set the multiple-bit errors in +inject mask and enable injection, U-Boot is very likely to hang quickly as the +errors will be injected when it accesses its code, data etc. + + +Use cases for DDR 'ecc' command: +================================ + +Before executing particular tests reset target board or clear status registers: + +=> ecc captureclear +=> ecc errdetectclr all +=> ecc sbecnt 0 + + +Injecting Single-Bit Errors +--------------------------- + +1. Set 1 bit in Data Path Error Inject Mask + +=> ecc injectdatahi 1 + +2. Run test over some memory region + +=> ecc testdw 200000 10 + +3. Check ECC status + +=> ecc status +... +Memory Data Path Error Injection Mask High/Low: 00000001 00000000 +... +Memory Single-Bit Error Management (0..255): + Single-Bit Error Threshold: 255 + Single Bit Error Counter: 16 +... +Memory Error Detect: + Multiple Memory Errors: 0 + Multiple-Bit Error: 0 + Single-Bit Error: 0 +... + +16 errors were generated, Single-Bit Error flag was not set as Single Bit Error +Counter did not reach Single-Bit Error Threshold. + +4. Make sure used memory region got re-initialized with 0x0123456789abcdef + +=> md 200000 +00200000: 01234567 89abcdef 01234567 89abcdef .#Eg.....#Eg.... +00200010: 01234567 89abcdef 01234567 89abcdef .#Eg.....#Eg.... +00200020: 01234567 89abcdef 01234567 89abcdef .#Eg.....#Eg.... +00200030: 01234567 89abcdef 01234567 89abcdef .#Eg.....#Eg.... +00200040: 01234567 89abcdef 01234567 89abcdef .#Eg.....#Eg.... +00200050: 01234567 89abcdef 01234567 89abcdef .#Eg.....#Eg.... +00200060: 01234567 89abcdef 01234567 89abcdef .#Eg.....#Eg.... +00200070: 01234567 89abcdef 01234567 89abcdef .#Eg.....#Eg.... +00200080: deadbeef deadbeef deadbeef deadbeef ................ +00200090: deadbeef deadbeef deadbeef deadbeef ................ + +Injecting Multiple-Bit Errors +----------------------------- + +1. Set more than 1 bit in Data Path Error Inject Mask + +=> ecc injectdatahi 1 +=> ecc injectdatalo 1 + +2. Run test over some memory region + +=> ecc testword 200000 1 + +3. Check ECC status + +=> ecc status +... +Memory Data Path Error Injection Mask High/Low: 00000001 00000001 +... +Memory Error Detect: + Multiple Memory Errors: 0 + Multiple-Bit Error: 1 + Single-Bit Error: 0 +... + +The Multiple Memory Errors flags not set and Multiple-Bit Error flags are set. + +4. Make sure used memory region got re-initialized with 0x0123456789abcdef + +=> md 200000 +00200000: 01234567 89abcdef 01234567 89abcdef .#Eg.....#Eg.... +00200010: 01234567 89abcdef 01234567 89abcdef .#Eg.....#Eg.... +00200020: 01234567 89abcdef 01234567 89abcdef .#Eg.....#Eg.... +00200030: 01234567 89abcdef 01234567 89abcdef .#Eg.....#Eg.... +00200040: 01234567 89abcdef 01234567 89abcdef .#Eg.....#Eg.... +00200050: 01234567 89abcdef 01234567 89abcdef .#Eg.....#Eg.... +00200060: 01234567 89abcdef 01234567 89abcdef .#Eg.....#Eg.... +00200070: 01234567 89abcdef 01234567 89abcdef .#Eg.....#Eg.... +00200080: deadbeef deadbeef deadbeef deadbeef ................ +00200090: deadbeef deadbeef deadbeef deadbeef ................ + + +Test Single-Bit Error Counter and Threshold +------------------------------------------- + +1. Set 1 bit in Data Path Error Inject Mask + +=> ecc injectdatahi 1 + +2. Enable error injection + +=> ecc inject en + +3. Let u-boot run for a with Single-Bit error injection enabled + +4. Disable error injection + +=> ecc inject dis + +4. Check status + +=> ecc status + +... +Memory Single-Bit Error Management (0..255): + Single-Bit Error Threshold: 255 + Single Bit Error Counter: 199 + +Memory Error Detect: + Multiple Memory Errors: 1 + Multiple-Bit Error: 0 + Single-Bit Error: 1 +... + +Observe that Single-Bit Error is 'on' which means that Single-Bit Error Counter +reached Single-Bit Error Threshold. Multiple Memory Errors bit is also 'on', that +is Counter reached Threshold more than one time (it wraps back after reaching +Threshold). diff --git a/roms/u-boot/doc/README.mpc83xxads b/roms/u-boot/doc/README.mpc83xxads new file mode 100644 index 000000000..372fdd9ce --- /dev/null +++ b/roms/u-boot/doc/README.mpc83xxads @@ -0,0 +1,97 @@ +Freescale MPC83xx ADS Boards +----------------------------------------- + +0. Toolchain / Building + + $ PATH=$PATH:/usr/powerpc/bin + $ CROSS_COMPILE=powerpc-linux- + $ export PATH CROSS_COMPILE + + $ powerpc-linux-gcc -v + Reading specs from /usr/powerpc/lib/gcc/powerpc-linux/3.4.3/specs + Configured with: ../configure --prefix=/usr/powerpc + --exec-prefix=/usr/powerpc --target=powerpc-linux --enable-shared + --disable-nls --disable-multilib --enable-languages=c,c++,ada,f77,objc + Thread model: posix + gcc version 3.4.3 (Debian) + + $ powerpc-linux-as -v + GNU assembler version 2.15 (powerpc-linux) using BFD version 2.15 + + + $ make MPC8349ADS_config + Configuring for MPC8349ADS board... + + $ make + + +1. Board Switches and Jumpers + + +2. Memory Map + +2.1. The memory map should look pretty much like this: + + 0x0000_0000 0x7fff_ffff DDR 2G + 0x8000_0000 0x9fff_ffff PCI MEM 512M + 0xc000_0000 0xdfff_ffff Rapid IO 512M + 0xe000_0000 0xe00f_ffff CCSR 1M + 0xe200_0000 0xe2ff_ffff PCI IO 16M + 0xf000_0000 0xf7ff_ffff SDRAM 128M + 0xf800_0000 0xf80f_ffff BCSR 1M + 0xfe00_0000 0xffff_ffff FLASH (boot bank) 16M + + +3. Definitions + +3.1 Explanation of NEW definitions in: + + include/configs/MPC8349ADS.h + + CONFIG_MPC83xx MPC83xx family + CONFIG_MPC8349 MPC8349 specific + CONFIG_TSEC_ENET Use on-chip 10/100/1000 ethernet + + +4. Compilation + + Assuming you're using BASH shell: + + export CROSS_COMPILE=your-cross-compile-prefix + cd u-boot + make distclean + make MPC8349ADS_config + make + +5. Downloading and Flashing Images + +5.0 Download over serial line using Kermit: + + loadb + [Drop to kermit: + ^\c + send <u-boot-bin-image> + c + ] + + + Or via tftp: + + tftp 10000 u-boot.bin + +5.1 Reflash U-Boot Image using U-Boot + + tftp 10000 u-boot.bin + protect off fe000000 fe09ffff + erase fe000000 fe09ffff + + cp.b 10000 fe000000 xxxx +or + cp.b 10000 fe000000 a0000 + +You might have to supply the correct byte count for 'xxxx' from +the TFTP. Maybe a0000 will work too, that corresponds to the +erased sectors. + + +6. Notes diff --git a/roms/u-boot/doc/README.mpc85xx b/roms/u-boot/doc/README.mpc85xx new file mode 100644 index 000000000..8464e7f4d --- /dev/null +++ b/roms/u-boot/doc/README.mpc85xx @@ -0,0 +1,166 @@ +External Debug Support +---------------------- + +Freescale's e500v1 and e500v2 cores (used in mpc85xx chips) have some +restrictions on external debugging (JTAG). In particular, for the debugger to +be able to receive control after a single step or breakpoint: + - MSR[DE] must be set + - A valid opcode must be fetchable, through the MMU, from the debug + exception vector (IVPR + IVOR15). + +To maximize the time during which this requirement is met, U-Boot sets MSR[DE] +immediately on entry and keeps it set. It also uses a temporary TLB to keep a +mapping to a valid opcode at the debug exception vector, even if we normally +don't support exception vectors being used that early, and that's not the area +where U-Boot currently executes from. + +Note that there may still be some small windows where debugging will not work, +such as in between updating IVPR and IVOR15. + +Config Switches: +---------------- + +Please refer README section "MPC85xx External Debug Support" + +Major Config Switches during various boot Modes +---------------------------------------------- + +NOR boot + !defined(CONFIG_SYS_RAMBOOT) && !defined(CONFIG_SPL) +NOR boot Secure + !defined(CONFIG_SYS_RAMBOOT) && defined(CONFIG_NXP_ESBC) +RAMBOOT(SD, SPI & NAND boot) + defined(CONFIG_SYS_RAMBOOT) +RAMBOOT Secure (SD, SPI & NAND) + defined(CONFIG_SYS_RAMBOOT) && defined(CONFIG_NXP_ESBC) +NAND SPL BOOT + defined(CONFIG_SYS_RAMBOOT) && defined(CONFIG_NAND_SPL) + + +TLB Entries during u-boot execution +----------------------------------- + +Note: Sequence number is in order of execution + +A) defined(CONFIG_SYS_RAMBOOT) i.e. SD, SPI, NAND RAMBOOT & NAND_SPL boot + + 1) TLB entry to overcome e500 v1/v2 debug restriction + Location : Label "_start_e500" + TLB Entry : CONFIG_SYS_PPC_E500_DEBUG_TLB + EPN -->RPN : CONFIG_SYS_MONITOR_BASE --> CONFIG_SYS_MONITOR_BASE + Properties : 256K, AS0, I, IPROT + + 2) TLB entry for working in AS1 + Location : Label "create_init_ram_area" + TLB Entry : 15 + EPN -->RPN : CONFIG_SYS_MONITOR_BASE --> CONFIG_SYS_MONITOR_BASE + Properties : 1M, AS1, I, G, IPROT + + 3) TLB entry for the stack during AS1 + Location : Lable "create_init_ram_area" + TLB Entry : 14 + EPN -->RPN : CONFIG_SYS_INIT_RAM_ADDR --> CONFIG_SYS_INIT_RAM_ADDR + Properties : 16K, AS1, IPROT + + 4) TLB entry for CCSRBAR during AS1 execution + Location : cpu_init_early_f + TLB Entry : 13 + EPN -->RPN : CONFIG_SYS_CCSRBAR --> CONFIG_SYS_CCSRBAR + Properties : 1M, AS1, I, G + + 5) Invalidate unproctected TLB Entries + Location : cpu_init_early_f + Invalidated: 13 + + 6) Create TLB entries as per boards/freescale/<board>/tlb.c + Location : cpu_init_early_f --> init_tlbs() + Properties : ..., AS0, ... + Please note It can overwrites previous TLB Entries. + + 7) Disable TLB Entries of AS1 + Location : cpu_init_f --> disable_tlb() + Disable : 15, 14 + + 8) Update Flash's TLB entry + Location : Board_init_r + TLB entry : Search from TLB entries + EPN -->RPN : CONFIG_SYS_FLASH_BASE --> CONFIG_SYS_FLASH_BASE_PHYS + Properties : Board specific size, AS0, I, G, IPROT + + +B) !defined(CONFIG_SYS_RAMBOOT) i.e. NOR boot + + 1) TLB entry to overcome e500 v1/v2 debug restriction + Location : Label "_start_e500" + TLB Entry : CONFIG_SYS_PPC_E500_DEBUG_TLB +#if defined(CONFIG_NXP_ESBC) + EPN -->RPN : CONFIG_SYS_MONITOR_BASE --> CONFIG_SYS_PBI_FLASH_WINDOW + Properties : 1M, AS1, I, G, IPROT +#else + EPN -->RPN : CONFIG_SYS_MONITOR_BASE & 0xffc00000 --> 0xffc00000 + Properties : 4M, AS0, I, G, IPROT +#endif + + 2) TLB entry for working in AS1 + Location : Label "create_init_ram_area" + TLB Entry : 15 +#if defined(CONFIG_NXP_ESBC) + EPN -->RPN : CONFIG_SYS_MONITOR_BASE --> CONFIG_SYS_PBI_FLASH_WINDOW + Properties : 1M, AS1, I, G, IPROT +#else + EPN -->RPN : CONFIG_SYS_MONITOR_BASE & 0xffc00000 --> 0xffc00000 + Properties : 4M, AS1, I, G, IPROT +#endif + + 3) TLB entry for the stack during AS1 + Location : Lable "create_init_ram_area" + TLB Entry : 14 + EPN -->RPN : CONFIG_SYS_INIT_RAM_ADDR --> CONFIG_SYS_INIT_RAM_ADDR + Properties : 16K, AS1, IPROT + + 4) TLB entry for CCSRBAR during AS1 execution + Location : cpu_init_early_f + TLB Entry : 13 + EPN -->RPN : CONFIG_SYS_CCSRBAR --> CONFIG_SYS_CCSRBAR + Properties : 1M, AS1, I, G + + 5) TLB entry for Errata workaround CONFIG_SYS_FSL_ERRATUM_IFC_A003399 + Location : cpu_init_early_f + TLB Entry : 9 + EPN -->RPN : SRAM_BASE_ADDR --> SRAM_BASE_ADDR + Properties : 1M, AS1, I + + 6) CONFIG_SYS_FSL_ERRATUM_IFC_A003399 Adjust flash's phys addr + Location : cpu_init_early_f --> setup_ifc + TLB Entry : Get Flash TLB + EPN -->RPN : Adjusted flash_phys --> Adjusted flash_phys + Properties : 4M, AS1, I, G, IPROT + + 7) CONFIG_SYS_FSL_ERRATUM_IFC_A003399: E500 v1,v2 debug restriction + Location : cpu_init_early_f --> setup_ifc + TLB Entry : CONFIG_SYS_PPC_E500_DEBUG_TLB + EPN -->RPN : Adjusted flash_phys --> Adjusted flash_phys + Properties : 4M, AS0, I, G, IPROT + + 8) Invalidate unproctected TLB Entries + Location : cpu_init_early_f + Invalidated: 13, 9 + + 9) Create TLB entries as per boards/freescale/<board>/tlb.c + Location : cpu_init_early_f --> init_tlbs() + Properties : ..., AS0, ... + Note: It can overwrites previous TLB Entries + + 10) Disable TLB Entries of AS1 + Location : cpu_init_f --> disable_tlb() + Disable : 15, 14 + + 11) Create DDR's TLB entriy + Location : Board_init_f -> dram_init + TLB entry : Search free TLB entry + + 12) Update Flash's TLB entry + Location : Board_init_r + TLB entry : Search from TLB entries + EPN -->RPN : CONFIG_SYS_FLASH_BASE --> CONFIG_SYS_FLASH_BASE_PHYS + Properties : Board specific size, AS0, I, G, IPROT diff --git a/roms/u-boot/doc/README.mpc85xx-sd-spi-boot b/roms/u-boot/doc/README.mpc85xx-sd-spi-boot new file mode 100644 index 000000000..e3f580446 --- /dev/null +++ b/roms/u-boot/doc/README.mpc85xx-sd-spi-boot @@ -0,0 +1,75 @@ +---------------------------------------- +Booting from On-Chip ROM (eSDHC or eSPI) +---------------------------------------- + +boot_format is a tool to write SD bootable images to a filesystem and build +SD/SPI images to a binary file for writing later. + +When booting from an SD card/MMC, boot_format puts the configuration file and +the RAM-based U-Boot image on the card. +When booting from an EEPROM, boot_format generates a binary image that is used +to boot from this EEPROM. + +Where to get boot_format: +======================== + +you can browse it online at: +http://git.freescale.com/git/cgit.cgi/ppc/sdk/boot-format.git/ + +Building +======== + +Run the following to build this project + + $ make + +Execution +========= + +boot_format runs under a regular Linux machine and requires a super user mode +to run. Execute boot_format as follows. + +For building SD images by writing directly to a file system on SD media: + + $ boot_format $config u-boot.bin -sd $device + +Where $config is the included config.dat file for your platform and $device +is the target block device for the SD media on your computer. + +For build binary images directly a local file: + + $ boot_format $config u-boot.bin -spi $file + +Where $file is the target file. Also keep in mind the u-boot.bin file needs +to be the u-boot built for your particular platform and target media. + +Example: To generate a u-boot.bin for a P1022DS booting from SD, run the +following in the u-boot repository: + + $ make P1022DS_SDCARD + +Configuration Files +=================== + +Below are the configuration files to be used with a particular platform. Keep +in mind that some of these config files are tied to the platforms DDR speed. +Please see the SoC reference manual for more documentation. + +P1022DS config_sram_p1022ds.dat +P2020DS config_sram_p2020ds.dat +P1020RDB config_ddr2_1g_p1020rdb_533M.dat +P1020RDB config_ddr2_1g_p1020rdb_667M.dat +P2020RDB config_ddr2_1g_p2020rdb_800M.dat +P2020RDB config_ddr2_1g_p2020rdb_667M.dat +P2020RDB config_ddr3_1gb_64bit_p2020rdb_pc.dat +P1020RDB config_ddr3_1gb_p1_p2_rdb_pc_800M.dat +P1011RDB config_ddr3_1gb_p1_p2_rdb_pc_800M.dat +P1010RDB config_ddr3_1gb_p1010rdb_800M.dat +P1021RDB config_ddr3_1gb_p1_p2_rdb_pc_800M.dat +P1022DS config_ddr3_2gb_p1022ds.dat +P1024RDB config_ddr3_1gb_p1_p2_rdb_pc_667M.dat +P1025RDB config_ddr3_1gb_p1_p2_rdb_pc_667M.dat +P1016RDB config_ddr3_1gb_p1_p2_rdb_pc_667M.dat +P1020UTM config_ddr3_1gb_p1_p2_rdb_pc_800M.dat +P1020MBG config_ddr3_1gb_p1_p2_rdb_pc_800M.dat +MPC8536DS config_ddr2_512m_mpc8536ds_667M.dat diff --git a/roms/u-boot/doc/README.mpc85xx-spin-table b/roms/u-boot/doc/README.mpc85xx-spin-table new file mode 100644 index 000000000..72c7bd7b5 --- /dev/null +++ b/roms/u-boot/doc/README.mpc85xx-spin-table @@ -0,0 +1,26 @@ +Spin table in cache +===================================== +As specified by ePAPR v1.1, the spin table needs to be in cached memory. After +DDR is initialized and U-Boot relocates itself into DDR, the spin table is +accessible for core 0. It is part of release.S, within 4KB range after +__secondary_start_page. For other cores to use the spin table, the booting +process is described below: + +Core 0 sets up the reset page on the top 4K of memory (or 4GB if total memory +is more than 4GB), and creates a TLB to map it to 0xffff_f000, regardless of +the physical address of this page, with WIMGE=0b01010. Core 0 also enables boot +page translation for secondary cores to use this page of memory. Then 4KB +memory is copied from __secondary_start_page to the boot page, after flusing +cache because this page is mapped as normal DDR. Before copying the reset page, +core 0 puts the physical address of the spin table (which is in release.S and +relocated to the top of mapped memory) into a variable __spin_table_addr so +that secondary cores can see it. + +When secondary cores boot up from 0xffff_f000 page, they only have one default +TLB. While booting, they set up another TLB in AS=1 space and jump into +the new space. The new TLB covers the physical address of the spin table page, +with WIMGE =0b00100. Now secondary cores can keep polling the spin table +without stress DDR bus because both the code and the spin table is in cache. + +For the above to work, DDR has to set the 'M' bit of WIMGE, in order to keep +cache coherence. diff --git a/roms/u-boot/doc/README.mpc85xxcds b/roms/u-boot/doc/README.mpc85xxcds new file mode 100644 index 000000000..79d71cb37 --- /dev/null +++ b/roms/u-boot/doc/README.mpc85xxcds @@ -0,0 +1,225 @@ +Motorola MPC85xxCDS boards +-------------------------- + +The CDS family of boards consists of a PCI backplane called the +"Arcadia", a PCI-form-factor carrier card that plugs into a PCI slot, +and a CPU daughter card that bolts onto the daughter card. + +Much of the content of the README.mpc85xxads for the 85xx ADS boards +applies to the 85xx CDS boards as well. In particular the toolchain, +the switch nomenclature, and the basis for the memory map. There are +some differences, though. + + +Building U-Boot +--------------- + +The Binutils in current ELDK toolchain will not support MPC85xx +chip. You need to use binutils-2.14.tar.bz2 (or newer) from + http://ftp.gnu.org/gnu/binutils. + +The 85xx CDS code base is known to compile using: + gcc (GCC) 3.2.2 20030217 (Yellow Dog Linux 3.0 3.2.2-2a) + + +Memory Map +---------- + +The memory map for U-Boot and linux has been extended w.r.t. the ADS +platform to allow for utilization of all 85xx CDS devices. The memory +map is setup for linux to operate properly. The linux source when +configured for MPC85xx CDS has been updated to reflect the new memory +map. + +The mapping is: + + 0x0000_0000 0x7fff_ffff DDR 2G + 0x8000_0000 0x9fff_ffff PCI1 MEM 512M + 0xa000_0000 0xbfff_ffff PCI2 MEM 512M + 0xe000_0000 0xe00f_ffff CCSR 1M + 0xe200_0000 0xe2ff_ffff PCI1 IO 16M + 0xe300_0000 0xe3ff_ffff PCI2 IO 16M + 0xf000_0000 0xf7ff_ffff SDRAM 128M + 0xf800_0000 0xf80f_ffff NVRAM/CADMUS (*) 1M + 0xff00_0000 0xff7f_ffff FLASH (2nd bank) 8M + 0xff80_0000 0xffff_ffff FLASH (boot bank) 8M + + (*) The system control registers (CADMUS) start at offset 0xfdb0_4000 + within the NVRAM/CADMUS region of memory. + + +Using Flash +----------- + +The CDS board has two flash banks, each 8MB in size (2^23 = 0x00800000). +There is a switch which allows the boot-bank to be selected. The switch +settings for updating flash are given below. + +The U-Boot commands for copying the boot-bank into the secondary bank are +as follows: + + erase ff780000 ff7fffff + cp.b fff80000 ff780000 80000 + + +U-Boot/kermit commands for downloading an image, then copying +it into the secondary bank: + + loadb + [Drop to kermit: + ^\c + send <u-boot-bin-image> + c + ] + + erase ff780000 ff7fffff + cp.b $loadaddr ff780000 80000 + + +U-Boot commands for downloading an image via tftp and flashing +it into the second bank: + + tftp 10000 <u-boot.bin.image> + erase ff780000 ff7fffff + cp.b 10000 ff780000 80000 + + +After copying the image into the second bank of flash, be sure to toggle +SW2[2] on the carrier card before resetting the board in order to set the +secondary bank as the boot-bank. + + +Carrier Board Switches +---------------------- + +As a reminder, you should read the README.mpc85xxads too. + +Most switches on the carrier board should not be changed. The only +user-settable switches on the carrier board are used to configure +the flash banks and determining the PCI slot. + +The first two bits of SW2 control how flash is used on the board: + + 12345678 + -------- + SW2=00XXXXXX FLASH: Boot bank 1, bank 2 available. + 01XXXXXX FLASH: Boot bank 2, bank 1 available (swapped). + 10XXXXXX FLASH: Boot promjet, bank 1 available + 11XXXXXX FLASH: Boot promjet, bank 2 available + +The boot bank is always mapped to FF80_0000 and listed first by +the "flinfo" command. The secondary bank is always FF00_0000. + +When using PCI, linux needs to know to which slot the CDS carrier is +connected.. By convention, the user-specific bits of SW2 are used to +convey this information: + + 12345678 + -------- + SW2=xxxxxx00 PCI SLOT INFORM: The CDS carrier is in slot0 of the Arcadia + xxxxxx01 PCI SLOT INFORM: The CDS carrier is in slot1 of the Arcadia + xxxxxx10 PCI SLOT INFORM: The CDS carrier is in slot2 of the Arcadia + xxxxxx11 PCI SLOT INFORM: The CDS carrier is in slot3 of the Arcadia + +These are cleverly, er, clearly silkscreened as Slot 1 through 4, +respectively, on the Arcadia near the support posts. + + +The default setting of all switches on the carrier board is: + + 12345678 + -------- + SW1=01101100 + SW2=0x1111yy x=Flash bank, yy=PCI slot + SW3=11101111 + SW4=10001000 + + +8555/41 CPU Card Switches +------------------------- + +Most switches on the CPU Card should not be changed. However, the +frequency can be changed by setting SW3: + + 12345678 + -------- + SW3=XX00XXXX == CORE:CCB 2:1 + XX01XXXX == CORE:CCB 5:2 + XX10XXXX == CORE:CCB 3:1 + XX11XXXX == CORE:CCB 7:2 + XXXX1000 == CCB:SYSCLK 8:1 + XXXX1010 == CCB:SYSCLK 10:1 + +A safe default setting for all switches on the CPU board is: + + 12345678 + -------- + SW1=10001111 + SW2=01000111 + SW3=00001000 + SW4=11111110 + + +8548 CPU Card Switches +---------------------- +And, just to be confusing, in this set of switches: + + ON = 1 + OFF = 0 + +Default + SW1=11111101 + SW2=10011111 + SW3=11001000 (8X) (2:1) + SW4=11110011 + + SW3=X000XXXX == CORE:CCB 4:1 + X001XXXX == CORE:CCB 9:2 + X010XXXX == CORE:CCB 1:1 + X011XXXX == CORE:CCB 3:2 + X100XXXX == CORE:CCB 2:1 + X101XXXX == CORE:CCB 5:2 + X110XXXX == CORE:CCB 3:1 + X111XXXX == CORE:CCB 7:2 + XXXX0000 == CCB:SYSCLK 16:1 + XXXX0001 == RESERVED + XXXX0010 == CCB:SYSCLK 2:1 + XXXX0011 == CCB:SYSCLK 3:1 + XXXX0100 == CCB:SYSCLK 4:1 + XXXX0101 == CCB:SYSCLK 5:1 + XXXX0110 == CCB:SYSCLK 6:1 + XXXX0111 == RESERVED + XXXX1000 == CCB:SYSCLK 8:1 + XXXX1001 == CCB:SYSCLK 9:1 + XXXX1010 == CCB:SYSCLK 10:1 + XXXX1011 == RESERVED + XXXX1100 == CCB:SYSCLK 12:1 + XXXX1101 == CCB:SYSCLK 20:1 + XXXX1110 == RESERVED + XXXX1111 == RESERVED + + +eDINK Info +---------- + +One bank of flash may contain an eDINK image. + +Memory Map: + + CCSRBAR @ 0xe0000000 + Flash Bank 1 @ 0xfe000000 + Flash Bank 2 @ 0xff000000 + Ram @ 0 + +Commands for downloading a U-Boot image to memory from edink: + + env -c + time -s 4/8/2004 4:30p + dl -k -b -o 100000 + [Drop to kermit: + ^\c + transmit /binary <u-boot-bin-image> + c + ] + + fu -l 100000 fe780000 80000 diff --git a/roms/u-boot/doc/README.multi-dtb-fit b/roms/u-boot/doc/README.multi-dtb-fit new file mode 100644 index 000000000..f48450efc --- /dev/null +++ b/roms/u-boot/doc/README.multi-dtb-fit @@ -0,0 +1,65 @@ +MULTI DTB FIT and SPL_MULTI_DTB_FIT + +The purpose of this feature is to enable U-Boot or the SPL to select its DTB +from a FIT appended at the end of the binary. +It comes in two flavors: U-Boot (CONFIG_MULTI_DTB_FIT) and SPL +(CONFIG_SPL_MULTI_DTB_FIT). + +U-Boot flavor: +Usually the DTB is selected by the SPL and passed down to U-Boot. But some +platforms don't use the SPL. In this case MULTI_DTB_FIT can used to provide +U-Boot with a choice of DTBs. +The relevant DTBs are packed into a FIT (list provided by CONFIG_OF_LIST). The +FIT is automatically generated at the end of the compilation and appended to +u-boot.bin so that U-Boot can locate it and select the correct DTB from inside +the FIT. +The selection is done using board_fit_config_name_match() (same as what the SPL +uses to select the DTB for U-Boot). The selection happens during fdtdec_setup() +which is called during before relocation by board_init_f(). + +SPL flavor: +the SPL uses only a small subset of the DTB and it usually depends more +on the SOC than on the board. So it's usually fine to include a DTB in the +SPL that doesn't exactly match the board. There are howerver some cases +where it's not possible. In the later case, in order to support multiple +boards (or board revisions) with the same SPL binary, SPL_MULTI_DTB_FIT +can be used. +The relevant DTBs are packed into a FIT. This FIT is automatically generated +at the end of the compilation, compressed and appended to u-boot-spl.bin, so +that SPL can locate it and select the correct DTB from inside the FIT. +CONFIG_SPL_OF_LIST is used to list the relevant DTBs. +The compression stage is optional but reduces the impact on the size of the +SPL. LZO and GZIP compressions are supported. By default, the area where the +FIT is uncompressed is dynamicaly allocated but this behaviour can be changed +for platforms that don't provide a HEAP big enough to contain the uncompressed +FIT. +The SPL uses board_fit_config_name_match() to find the correct DTB within the +FIT (same as what the SPL uses to select the DTB for U-Boot). +Uncompression and selection stages happen in fdtdec_setup() which is called +during the early initialization stage of the SPL (spl_early_init() or +spl_init()) + +Impacts and performances (SPL flavor): +The impact of this option is relatively small. Here are some numbers measured +for a TI DRA72 platform: + + +----------+------------+-----------+------------+ + | size | size delta | SPL boot | boot time | + | (bytes) | (bytes) | time (s) | delta (s) | ++---------------------------+----------+------------+-----------+------------+ +| 1 DTB | | | | | ++---------------------------+----------+------------+-----------+------------+ +| reference | 125305 | 0 | 1.389 | 0 | +| LZO (dynamic allocation) | 125391 | 86 | 1.381 | -0.008 | ++---------------------------+----------+------------+-----------+------------+ +| 4 DTBs (DRA7, DRA71, | | | | | +| DRA72, DRA72 revC) | | | | | ++---------------------------+----------+------------+-----------+------------+ +| LZO (dynamic allocation) | 125991 | 686 | 1.39 | 0.001 | +| LZO (user defined area) | 125927 | 622 | 1.403 | 0.014 | +| GZIP (user defined area) | 133880 | 8575 | 1.421 | 0.032 | +| No compression (in place) | 137472 | 12167 | 1.412 | 0.023 | ++---------------------------+----------+------------+-----------+------------+ + +Note: SPL boot time is the time elapsed between the 'reset' command is entered +and the time when the first U-Boot (not SPL) version string is displayed. diff --git a/roms/u-boot/doc/README.mxc_ocotp b/roms/u-boot/doc/README.mxc_ocotp new file mode 100644 index 000000000..7a2863cfd --- /dev/null +++ b/roms/u-boot/doc/README.mxc_ocotp @@ -0,0 +1,51 @@ +Driver implementing the fuse API for Freescale's On-Chip OTP Controller (OCOTP) +on MXC + +This IP can be found on the following SoCs: + - Vybrid VF610, + - i.MX6. + +Note that this IP is different from albeit similar to the IPs of the same name +that can be found on the following SoCs: + - i.MX23, + - i.MX28, + - i.MX50. + +The section numbers in this file refer to the i.MX6 Reference Manual. + +A fuse word contains 32 fuse bit slots, as explained in 46.2.1. + +A bank contains 8 fuse word slots, as explained in 46.2.1 and shown by the +memory map in 46.4. + +Some fuse bit or word slots may not have the corresponding fuses actually +implemented in the fusebox. + +See the README files of the SoCs using this driver in order to know the +conventions used by U-Boot to store some specific data in the fuses, e.g. MAC +addresses. + +Fuse operations: + + Read + Read operations are implemented as read accesses to the shadow registers, + using "Bankx Wordy" from the memory map in 46.4. This is explained in + detail by the first two paragraphs in 46.2.1.2. + + Sense + Sense operations are implemented as the direct fusebox read explained by + the steps in 46.2.1.2. + + Program + Program operations are implemented as explained by the steps in 46.2.1.3. + Following this operation, the shadow registers are not reloaded by the + hardware. + + Override + Override operations are implemented as write accesses to the shadow + registers, as explained by the first paragraph in 46.2.1.3. + +Configuration: + + CONFIG_MXC_OCOTP + Define this to enable the mxc_ocotp driver. diff --git a/roms/u-boot/doc/README.nand b/roms/u-boot/doc/README.nand new file mode 100644 index 000000000..ec461b2dc --- /dev/null +++ b/roms/u-boot/doc/README.nand @@ -0,0 +1,345 @@ +# SPDX-License-Identifier: GPL-2.0+ +NAND FLASH commands and notes + +See NOTE below!!! + +# (C) Copyright 2003 +# Dave Ellis, SIXNET, dge@sixnetio.com +# + +Commands: + + nand bad + Print a list of all of the bad blocks in the current device. + + nand device + Print information about the current NAND device. + + nand device num + Make device `num' the current device and print information about it. + + nand erase off|partition size + nand erase clean [off|partition size] + Erase `size' bytes starting at offset `off'. Alternatively partition + name can be specified, in this case size will be eventually limited + to not exceed partition size (this behaviour applies also to read + and write commands). Only complete erase blocks can be erased. + + If `erase' is specified without an offset or size, the entire flash + is erased. If `erase' is specified with partition but without an + size, the entire partition is erased. + + If `clean' is specified, a JFFS2-style clean marker is written to + each block after it is erased. + + This command will not erase blocks that are marked bad. There is + a debug option in cmd_nand.c to allow bad blocks to be erased. + Please read the warning there before using it, as blocks marked + bad by the manufacturer must _NEVER_ be erased. + + nand info + Print information about all of the NAND devices found. + + nand read addr ofs|partition size + Read `size' bytes from `ofs' in NAND flash to `addr'. Blocks that + are marked bad are skipped. If a page cannot be read because an + uncorrectable data error is found, the command stops with an error. + + nand read.oob addr ofs|partition size + Read `size' bytes from the out-of-band data area corresponding to + `ofs' in NAND flash to `addr'. This is limited to the 16 bytes of + data for one 512-byte page or 2 256-byte pages. There is no check + for bad blocks or ECC errors. + + nand write addr ofs|partition size + Write `size' bytes from `addr' to `ofs' in NAND flash. Blocks that + are marked bad are skipped. If a page cannot be read because an + uncorrectable data error is found, the command stops with an error. + + As JFFS2 skips blocks similarly, this allows writing a JFFS2 image, + as long as the image is short enough to fit even after skipping the + bad blocks. Compact images, such as those produced by mkfs.jffs2 + should work well, but loading an image copied from another flash is + going to be trouble if there are any bad blocks. + + nand write.trimffs addr ofs|partition size + Enabled by the CONFIG_CMD_NAND_TRIMFFS macro. This command will write to + the NAND flash in a manner identical to the 'nand write' command + described above -- with the additional check that all pages at the end + of eraseblocks which contain only 0xff data will not be written to the + NAND flash. This behaviour is required when flashing UBI images + containing UBIFS volumes as per the UBI FAQ[1]. + + [1] http://www.linux-mtd.infradead.org/doc/ubi.html#L_flasher_algo + + nand write.oob addr ofs|partition size + Write `size' bytes from `addr' to the out-of-band data area + corresponding to `ofs' in NAND flash. This is limited to the 16 bytes + of data for one 512-byte page or 2 256-byte pages. There is no check + for bad blocks. + + nand read.raw addr ofs|partition [count] + nand write.raw addr ofs|partition [count] + Read or write one or more pages at "ofs" in NAND flash, from or to + "addr" in memory. This is a raw access, so ECC is avoided and the + OOB area is transferred as well. If count is absent, it is assumed + to be one page. As with .yaffs2 accesses, the data is formatted as + a packed sequence of "data, oob, data, oob, ..." -- no alignment of + individual pages is maintained. + +Configuration Options: + + CONFIG_SYS_NAND_U_BOOT_OFFS + NAND Offset from where SPL will read u-boot image. This is the starting + address of u-boot MTD partition in NAND. + + CONFIG_CMD_NAND + Enables NAND support and commands. + + CONFIG_CMD_NAND_TORTURE + Enables the torture command (see description of this command below). + + CONFIG_SYS_MAX_NAND_DEVICE + The maximum number of NAND devices you want to support. + + CONFIG_SYS_NAND_MAX_ECCPOS + If specified, overrides the maximum number of ECC bytes + supported. Useful for reducing image size, especially with SPL. + This must be at least 48 if nand_base.c is used. + + CONFIG_SYS_NAND_MAX_OOBFREE + If specified, overrides the maximum number of free OOB regions + supported. Useful for reducing image size, especially with SPL. + This must be at least 2 if nand_base.c is used. + + CONFIG_SYS_NAND_MAX_CHIPS + The maximum number of NAND chips per device to be supported. + + CONFIG_SYS_NAND_SELF_INIT + Traditionally, glue code in drivers/mtd/nand/raw/nand.c has driven + the initialization process -- it provides the mtd and nand + structs, calls a board init function for a specific device, + calls nand_scan(), and registers with mtd. + + This arrangement does not provide drivers with the flexibility to + run code between nand_scan_ident() and nand_scan_tail(), or other + deviations from the "normal" flow. + + If a board defines CONFIG_SYS_NAND_SELF_INIT, drivers/mtd/nand/raw/nand.c + will make one call to board_nand_init(), with no arguments. That + function is responsible for calling a driver init function for + each NAND device on the board, that performs all initialization + tasks except setting mtd->name, and registering with the rest of + U-Boot. Those last tasks are accomplished by calling nand_register() + on the new mtd device. + + Example of new init to be added to the end of an existing driver + init: + + /* chip is struct nand_chip, and is now provided by the driver. */ + mtd = nand_to_mtd(&chip); + + /* + * Fill in appropriate values if this driver uses these fields, + * or uses the standard read_byte/write_buf/etc. functions from + * nand_base.c that use these fields. + */ + chip.IO_ADDR_R = ...; + chip.IO_ADDR_W = ...; + + if (nand_scan_ident(mtd, CONFIG_SYS_MAX_NAND_CHIPS, NULL)) + error out + + /* + * Insert here any code you wish to run after the chip has been + * identified, but before any other I/O is done. + */ + + if (nand_scan_tail(mtd)) + error out + + /* + * devnum is the device number to be used in nand commands + * and in mtd->name. Must be less than CONFIG_SYS_MAX_NAND_DEVICE. + */ + if (nand_register(devnum, mtd)) + error out + + In addition to providing more flexibility to the driver, it reduces + the difference between a U-Boot driver and its Linux counterpart. + nand_init() is now reduced to calling board_nand_init() once, and + printing a size summary. This should also make it easier to + transition to delayed NAND initialization. + + Please convert your driver even if you don't need the extra + flexibility, so that one day we can eliminate the old mechanism. + + + CONFIG_SYS_NAND_ONFI_DETECTION + Enables detection of ONFI compliant devices during probe. + And fetching device parameters flashed on device, by parsing + ONFI parameter page. + +Platform specific options +========================= + CONFIG_NAND_OMAP_GPMC + Enables omap_gpmc.c driver for OMAPx and AMxxxx platforms. + GPMC controller is used for parallel NAND flash devices, and can + do ECC calculation (not ECC error detection) for HAM1, BCH4, BCH8 + and BCH16 ECC algorithms. + + CONFIG_NAND_OMAP_ELM + Enables omap_elm.c driver for OMAPx and AMxxxx platforms. + ELM controller is used for ECC error detection (not ECC calculation) + of BCH4, BCH8 and BCH16 ECC algorithms. + Some legacy platforms like OMAP3xx do not have in-built ELM h/w engine, + thus such SoC platforms need to depend on software library for ECC error + detection. However ECC calculation on such plaforms would still be + done by GPMC controller. + + CONFIG_SPL_NAND_AM33XX_BCH + Enables SPL-NAND driver (am335x_spl_bch.c) which supports ELM based + hardware ECC correction. This is useful for platforms which have ELM + hardware engine and use NAND boot mode. + Some legacy platforms like OMAP3xx do not have in-built ELM h/w engine, + so those platforms should use CONFIG_SPL_NAND_SIMPLE for enabling + SPL-NAND driver with software ECC correction support. + + CONFIG_NAND_OMAP_ECCSCHEME + On OMAP platforms, this CONFIG specifies NAND ECC scheme. + It can take following values: + OMAP_ECC_HAM1_CODE_SW + 1-bit Hamming code using software lib. + (for legacy devices only) + OMAP_ECC_HAM1_CODE_HW + 1-bit Hamming code using GPMC hardware. + (for legacy devices only) + OMAP_ECC_BCH4_CODE_HW_DETECTION_SW + 4-bit BCH code (unsupported) + OMAP_ECC_BCH4_CODE_HW + 4-bit BCH code (unsupported) + OMAP_ECC_BCH8_CODE_HW_DETECTION_SW + 8-bit BCH code with + - ecc calculation using GPMC hardware engine, + - error detection using software library. + - requires CONFIG_BCH to enable software BCH library + (For legacy device which do not have ELM h/w engine) + OMAP_ECC_BCH8_CODE_HW + 8-bit BCH code with + - ecc calculation using GPMC hardware engine, + - error detection using ELM hardware engine. + OMAP_ECC_BCH16_CODE_HW + 16-bit BCH code with + - ecc calculation using GPMC hardware engine, + - error detection using ELM hardware engine. + + How to select ECC scheme on OMAP and AMxx platforms ? + ----------------------------------------------------- + Though higher ECC schemes have more capability to detect and correct + bit-flips, but still selection of ECC scheme is dependent on following + - hardware engines present in SoC. + Some legacy OMAP SoC do not have ELM h/w engine thus such + SoC cannot support BCHx_HW ECC schemes. + - size of OOB/Spare region + With higher ECC schemes, more OOB/Spare area is required to + store ECC. So choice of ECC scheme is limited by NAND oobsize. + + In general following expression can help: + NAND_OOBSIZE >= 2 + (NAND_PAGESIZE / 512) * ECC_BYTES + where + NAND_OOBSIZE = number of bytes available in + OOB/spare area per NAND page. + NAND_PAGESIZE = bytes in main-area of NAND page. + ECC_BYTES = number of ECC bytes generated to + protect 512 bytes of data, which is: + 3 for HAM1_xx ecc schemes + 7 for BCH4_xx ecc schemes + 14 for BCH8_xx ecc schemes + 26 for BCH16_xx ecc schemes + + example to check for BCH16 on 2K page NAND + NAND_PAGESIZE = 2048 + NAND_OOBSIZE = 64 + 2 + (2048 / 512) * 26 = 106 > NAND_OOBSIZE + Thus BCH16 cannot be supported on 2K page NAND. + + However, for 4K pagesize NAND + NAND_PAGESIZE = 4096 + NAND_OOBSIZE = 224 + ECC_BYTES = 26 + 2 + (4096 / 512) * 26 = 210 < NAND_OOBSIZE + Thus BCH16 can be supported on 4K page NAND. + + + CONFIG_NAND_OMAP_GPMC_PREFETCH + On OMAP platforms that use the GPMC controller + (CONFIG_NAND_OMAP_GPMC_PREFETCH), this options enables the code that + uses the prefetch mode to speed up read operations. + +NOTE: +===== + +The Disk On Chip driver is currently broken and has been for some time. +There is a driver in drivers/mtd/nand/raw, taken from Linux, that works with +the current NAND system but has not yet been adapted to the u-boot +environment. + +Additional improvements to the NAND subsystem by Guido Classen, 10-10-2006 + +JFFS2 related commands: + + implement "nand erase clean" and old "nand erase" + using both the new code which is able to skip bad blocks + "nand erase clean" additionally writes JFFS2-cleanmarkers in the oob. + +Miscellaneous and testing commands: + "markbad [offset]" + create an artificial bad block (for testing bad block handling) + + "scrub [offset length]" + like "erase" but don't skip bad block. Instead erase them. + DANGEROUS!!! Factory set bad blocks will be lost. Use only + to remove artificial bad blocks created with the "markbad" command. + + "torture offset [size]" + Torture block to determine if it is still reliable. + Enabled by the CONFIG_CMD_NAND_TORTURE configuration option. + This command returns 0 if the block is still reliable, else 1. + If the block is detected as unreliable, it is up to the user to decide to + mark this block as bad. + The analyzed block is put through 3 erase / write cycles (or less if the block + is detected as unreliable earlier). + This command can be used in scripts, e.g. together with the markbad command to + automate retries and handling of possibly newly detected bad blocks if the + nand write command fails. + It can also be used manually by users having seen some NAND errors in logs to + search the root cause of these errors. + The underlying nand_torture() function is also useful for code willing to + automate actions following a nand->write() error. This would e.g. be required + in order to program or update safely firmware to NAND, especially for the UBI + part of such firmware. + Optionally, a second parameter size can be given to test multiple blocks with + one call. If size is not a multiple of the NAND's erase size, then the block + that contains offset + size will be tested in full. If used with size, this + command returns 0 if all tested blocks have been found reliable, else 1. + + +NAND locking command (for chips with active LOCKPRE pin) + + "nand lock" + set NAND chip to lock state (all pages locked) + + "nand lock tight" + set NAND chip to lock tight state (software can't change locking anymore) + + "nand lock status" + displays current locking status of all pages + + "nand unlock [offset] [size]" + unlock consecutive area (can be called multiple times for different areas) + + "nand unlock.allexcept [offset] [size]" + unlock all except specified consecutive area + +I have tested the code with board containing 128MiB NAND large page chips +and 32MiB small page chips. diff --git a/roms/u-boot/doc/README.nand-boot-ppc440 b/roms/u-boot/doc/README.nand-boot-ppc440 new file mode 100644 index 000000000..1e9c10264 --- /dev/null +++ b/roms/u-boot/doc/README.nand-boot-ppc440 @@ -0,0 +1,60 @@ +----------------------------- +NAND boot on PPC440 platforms +----------------------------- + +This document describes the U-Boot NAND boot feature as it +is implemented for the AMCC Sequoia (PPC440EPx) board. + +The PPC440EP(x)/GR(x) cpu's can boot directly from NAND FLASH, +completely without NOR FLASH. This can be done by using the NAND +boot feature of the 440 NAND flash controller (NDFC). + +Here a short description of the different boot stages: + +a) IPL (Initial Program Loader, integrated inside CPU) +------------------------------------------------------ +Will load first 4k from NAND (SPL) into cache and execute it from there. + +b) SPL (Secondary Program Loader) +--------------------------------- +Will load special U-Boot version (NUB) from NAND and execute it. This SPL +has to fit into 4kByte. It sets up the CPU and configures the SDRAM +controller and the NAND controller so that the special U-Boot image can be +loaded from NAND to SDRAM. +This special image is build in the directory "nand_spl". + +c) NUB (NAND U-Boot) +-------------------- +This NAND U-Boot (NUB) is a special U-Boot version which can be started +from RAM. Therefore it mustn't (re-)configure the SDRAM controller. + +On 440EPx the SPL is copied to internal SRAM before the NAND controller +is set up. While still running from cache, I experienced problems accessing +the NAND controller. + + +Example: Build and install NAND boot image for Sequoia (440EPx): + +a) Configure for sequoia with NAND boot support: +# make sequoia_nand_config + +b) Build image(s) +# make + +This will generate the SPL image in the "nand_spl" directory: +nand_spl/u-boot-spl.bin +Also another image is created spanning a whole NAND block (16kBytes): +nand_spl/u-boot-spl-16k.bin +The main NAND U-Boot image is generated in the toplevel directory: +u-boot.bin +A combined image of u-boot-spl-16k.bin and u-boot.bin is also created: +u-boot-nand.bin + +This image should be programmed at offset 0 in the NAND flash: + +# tftp 100000 /tftpboot/sequoia/u-boot-nand.bin +# nand erase 0 60000 +# nand write 100000 0 60000 + + +September 07 2006, Stefan Roese <sr@denx.de> diff --git a/roms/u-boot/doc/README.nokia_rx51 b/roms/u-boot/doc/README.nokia_rx51 new file mode 100644 index 000000000..84d1912dd --- /dev/null +++ b/roms/u-boot/doc/README.nokia_rx51 @@ -0,0 +1,94 @@ +Board: Nokia RX-51 aka N900 + +This board definition results in a u-boot.bin which can be chainloaded +from NOLO in qemu or on a real N900. It does very little hardware config +because NOLO has already configured the board. Only needed is enabling +internal eMMC memory via twl4030 regulator which is not enabled by NOLO. + +NOLO is expecting a kernel image and will treat any image it finds in +onenand as such. This u-boot is intended to be flashed to the N900 like +a kernel. In order to transparently boot the original kernel, it will be +appended to u-boot.bin at 0x40000. NOLO will load the entire image into +(random) memory and execute u-boot, which saves hw revision, boot reason +and boot mode ATAGs set by NOLO. Then the bootscripts will attempt to load +uImage or boot.scr from a fat, ext2/ext3 or ext4 filesystem in external +SD card or internal eMMC memory. If this fails or keyboard is closed then +the appended kernel image will be booted using some generated and some +stored ATAGs (see boot order). + +For generating combined image of u-boot and kernel there is a simple script +called u-boot-gen-combined. It is available in following repository: + + https://github.com/pali/u-boot-maemo + +There is support for hardware watchdog. Hardware watchdog is started by +NOLO so u-boot must kick watchdog to prevent reboot device (but not very +often, max every 2 seconds). There is also support for framebuffer display +output with ANSI escape codes and the N900 HW keyboard input. + +When U-Boot is starting it enable IBE bit in Auxiliary Control Register, +which is needed for Thumb-2 ISA support. It is workaround for errata 430973. + +Default boot order: + + * 0. if keyboard is closed boot automatically attached kernel image + * 1. try boot from external SD card + * 2. try boot from internal eMMC memory + * 3. try boot from attached kernel image + +Boot from SD or eMMC in this order: + + * 1. + * 1.1 find boot.scr on first fat partition + * 1.2 find uImage on first fat partition + * 1.3 same order for 2. - 4. fat partition + * 2. same as 1. but for ext2/3 partition + * 3. same as 1. but for ext4 partition + + +Available additional commands/variables: + + * run sdboot - Boot from external SD card (see boot order) + * run emmcboot - Boot from internal eMMC memory (see boot order) + * run attachboot - Boot attached kernel image (attached to U-Boot binary) + + * run scriptload - Load boot script ${mmcscriptfile} + * run scriptboot - Run loaded boot script + * run kernload - Load kernel image ${mmckernfile} + * run initrdload - Load initrd image ${mmcinitrdfile} + * run kernboot - Boot loaded kernel image + * run kerninitrdboot - Boot loaded kernel image with loaded initrd image + + * run trymmcscriptboot - Try to load and boot script ${mmcscriptfile} + * run trymmckernboot - Try to load and boot kernel image ${mmckernfile} + * run trymmckerninitrdboot - Try to load and boot kernel image ${mmckernfile} + with initrd image ${mmcinitrdfile} + +Additional variables for loading files from mmc: + + * mmc ${mmcnum} (0 - external, 1 - internal) + * partition number ${mmcpart} (1 - 4) + * parition type ${mmctype} (fat, ext2, ext4) + +Additional variables for booting kernel: + + * setup_omap_atag - Add OMAP table into atags structure (needs maemo kernel) + * setup_console_atag - Enable serial console in OMAP table + * setup_boot_reason_atag - Change boot reason in OMAP table + * setup_boot_mode_atag - Change boot mode in OMAP table + + Variable setup_omap_atag is automatically set when booting attached kernel. + When variable setup_omap_atag is set, variable setup_console_atag is unset + and u-boot standard output is set to serial then setup_console_atag is + automatically set to 1. So output from Maemo kernel would go to serial port. + +UBIFS support: + + UBIFS support is disabled, because U-Boot image is too big and cannot be + flashed with attached zImage to RX-51 kernel nand area. For enabling UBIFS + support add following lines into file configs/nokia_rx51_defconfig + + CONFIG_CMD_UBI=y + CONFIG_CMD_UBIFS=y + CONFIG_MTD_UBI_FASTMAP=y + CONFIG_MTD_UBI_FASTMAP_AUTOCONVERT=1 diff --git a/roms/u-boot/doc/README.odroid b/roms/u-boot/doc/README.odroid new file mode 100644 index 000000000..bc77ae317 --- /dev/null +++ b/roms/u-boot/doc/README.odroid @@ -0,0 +1,332 @@ + U-Boot for Odroid X2/U3/XU3/XU4/HC1 +======================== + +1. Summary +========== +This is a quick instruction for setup Odroid boards. +Board config: odroid_config for X2/U3 +Board config: odroid-xu3_config for XU3/XU4/HC1 + +2. Supported devices +==================== +This U-BOOT config can be used on three boards: +- Odroid U3 +- Odroid X2 +with CPU Exynos 4412 rev 2.0 and 2GB of RAM +- Odroid XU3 +- Odroid XU4 +- Odroid HC1 +with CPU Exynos5422 and 2GB of RAM + +3. Boot sequence +================ +iROM->BL1->(BL2 + TrustZone)->U-BOOT + +This version of U-BOOT doesn't implement SPL. So, BL1, BL2, and TrustZone +binaries are needed to boot up. + +<< X2/U3 >> +It can be found in "boot.tar.gz" from here: +http://dev.odroid.com/projects/4412boot/wiki/FrontPage?action=download&value=boot.tar.gz +or here: +http://odroid.in/guides/ubuntu-lfs/boot.tar.gz + +<< XU3/XU4 >> +It can be downloaded from: +https://github.com/hardkernel/u-boot/tree/odroidxu3-v2012.07/sd_fuse/hardkernel_1mb_uboot + + +4. Boot media layout +==================== +The table below shows SD/eMMC cards layout for U-Boot. +The block offset is starting from 0 and the block size is 512B. + ------------------------------------- +| Binary | Block offset| part type | +| name | SD | eMMC |(eMMC only)| + ------------------------------------- +| Bl1 | 1 | 0 | 1 (boot) | +| Bl2 | 31 | 30 | 1 (boot) | +| U-Boot | 63 | 62 | 1 (boot) | +| Tzsw | 2111 | 2110 | 1 (boot) | +| Uboot Env | 2560 | 2560 | 0 (user) | + ------------------------------------- + +5. Prepare the SD boot card - with SD card reader +================================================= +To prepare bootable media you need boot binaries provided by hardkernel. +From the downloaded files, You can find: +- bl1.bin +- tzsw.bin +- bl2.bin +- sd_fusing.sh +- u-boot.bin +(The file names can be slightly different, but you can distinguish what they are +without problem) + +This is all you need to boot this board. But if you want to use your custom +U-Boot then you need to change u-boot.bin with your own U-Boot binary* +and run the script "sd_fusing.sh" - this script is valid only for SD card. + +*note: +The proper binary file of current U-Boot is u-boot-dtb.bin. + +quick steps for Linux: +- Download all files from the link at point 3 and extract it if needed. +- put any SD card into the SD reader +- check the device with "dmesg" +- run ./sd_fusing.sh /dev/sdX - where X is SD card device (but not a partition) +Check if Hardkernel U-Boot is booting, and next do the same with your U-Boot. + +6. Prepare the eMMC boot card + with a eMMC card reader (boot from eMMC card slot) +===================================================== +To boot the device from the eMMC slot you should use a special card reader +which supports eMMC partition switch. All of the boot binaries are stored +on the eMMC boot partition which is normally hidden. + +The "sd_fusing.sh" script can be used after updating offsets of binaries +according to the table from point 4. Be sure that you are working on the right +eMMC partition - its size is usually very small, about 1-4 MiB. + +7. Prepare the eMMC boot card + with a SD card reader (boot from SD card slot) +================================================= +If you have an eMMC->microSD adapter you can prepare the card as in point 5. +But then the device can boot only from the SD card slot. + +8. Prepare the boot media using Hardkernel U-Boot +================================================= +You can update the U-Boot to the custom one if you have a working bootloader +delivered with the board on the eMMC/SD card. Then follow the steps: +- install the android fastboot tool +- connect a micro usb cable to the board +- on the U-Boot prompt, run command: fastboot (as a root) +- on the host, run command: "fastboot flash bootloader u-boot-dtb.bin" +- the custom U-Boot should start after the board resets. + +9. Partition layout +==================== +Default U-Boot environment is setup for fixed partition layout. + +Partition table: MSDOS. Disk layout and files as listed in the table below. + ----- ------ ------ ------ -------- --------------------------------- +| Num | Name | FS | Size | Offset | Reguired files | +| | | Type | MiB | MiB | | + ----- ------ ------ ------ -------- --------------------------------- +| 1 | BOOT | fat | 100 | 2 | kernel, fdt** | +| 2 | ROOT | ext4 | - | | any Linux system | + ----- ------ ------ ------ -------- --------------------------------- + +**note: +Supported fdt files are: +- exynos4412-odroidx2.dtb +- exynos4412-odroidu3.dtb +- exynos5422-odroidxu3.dtb +- exynos5422-odroidxu3-lite.dtb +- exynos5422-odroidxu4.dtb +- exynos5422-odroidhc1.dtb + +Supported kernel files are: +- Image.itb +- zImage +- uImage + +The default environmental variable "dfu_alt_info" is set* for above layout. +Each partition size is just an example, dfu_alt_info tries init two partitions. +The size of each is not important. + +*note: +$dfu_alt_info is set on a boot time and it is concatenated using two variables: +- $dfu_alt_boot(set dynamically) +- $dfu_alt_system(from current env). + +To add any changes to dfu_alt_info - please modify $dfu_alt_system only. +Changes are visible after board reset. + +10. The environment and booting the kernel +========================================== +There are three macros defined in config for various boot options: +Two for both, kernel with device tree support and also without it: +- boot_uimg - load uImage +- boot_zimg - load zImage +If proper fdt file exists then it will be automatically loaded, +so for old kernel types, please remove fdt file from boot partition. + +The third boot option for multi image support (more info: doc/uImage.FIT/) +- boot_fit - for binary file: "Image.itb" + +Default boot command: "autoboot" +And the boot sequence is: +- boot_fit - if "Image.itb" exists +- boot_zimg - if "zImage" exists +- boot_uimg - if "uImage" exists + +11. USB host support +==================== +NOTE: This section is only for Odroid X2/U3. + +The ethernet can be accessed after starting the USB subsystem in U-Boot. +The adapter does not come with a preconfigured MAC address, and hence it needs +to be set before starting USB. +setenv usbethaddr 02:DE:AD:BE:EF:FF + +Note that in this example a locally managed MAC address is chosen. Care should +be taken to make these MAC addresses unique within the same subnet. + +Start the USB subsystem: +Odroid # setenv usbethaddr 02:DE:AD:BE:EF:FF +Odroid # usb start +(Re)start USB... +USB0: USB EHCI 1.00 +scanning bus 0 for devices... 4 USB Device(s) found + scanning usb for storage devices... 1 Storage Device(s) found + scanning usb for ethernet devices... 1 Ethernet Device(s) found +Odroid # + +Automatic IP assignment: +------------------------ +If the ethernet is connected to a DHCP server (router maybe with DHCP enabled), +then the below will automatically assign an ip address through DHCP. +setenv autoload no +dhcp + +Odroid # setenv autoload no +Odroid # dhcp +Waiting for Ethernet connection... done. +BOOTP broadcast 1 +DHCP client bound to address 192.168.1.10 (524 ms) +Odroid # + +Note that this automatically sets the many IP address related variables in +U-Boot that is obtained from the DHCP server. + +Odroid # printenv ipaddr netmask gatewayip dnsip +ipaddr=192.168.1.10 +netmask=255.255.255.0 +gatewayip=192.168.1.1 +dnsip=192.168.1.1 + +Ping example: +The ping command can be used a test to check connectivity. In this example, +192.168.1.27 is a pingable server in the network. +Odroid # ping 192.168.1.27 +Waiting for Ethernet connection... done. +Using sms0 device +host 192.168.1.27 is alive +Odroid # + +Static IP assignment: +--------------------- +In the case where there are no DHCP servers in the network, or you want to +set the IP address statically, it can be done by: +Odroid # setenv ipaddr 192.168.1.10 +Odroid # ping 192.168.1.27 +Waiting for Ethernet connection... done. +Using sms0 device +host 192.168.1.27 is alive + +TFTP booting: +------------- +Say there exists a tftp server in the network with address 192.168.1.27 and +it serves a kernel image (zImage.3.17) and a DTB blob (exynos4412-odroidu3.dtb) +that needs to be loaded and booted. It can be accomplished as below: +(Assumes that you have setenv usbethaddr, and have not set autoload to no) + +Odroid # setenv serverip 192.168.1.27 +Odroid # tftpboot 0x40080000 zImage.3.17 +Waiting for Ethernet connection... done. +Using sms0 device +TFTP from server 192.168.1.27; our IP address is 192.168.1.10 +Filename 'zImage.3.17'. +Load address: 0x40080000 +Loading: ################################################################# + ################################################################# + ################################################################# + ####################### + 52.7 KiB/s +done +Bytes transferred = 3194200 (30bd58 hex) +Odroid # tftpboot 0x42000000 exynos4412-odroidu3.dtb +Waiting for Ethernet connection... done. +Using sms0 device +TFTP from server 192.168.1.27; our IP address is 192.168.1.10 +Filename 'exynos4412-odroidu3.dtb'. +Load address: 0x42000000 +Loading: #### + 40 KiB/s +done +Bytes transferred = 46935 (b757 hex) +Odroid # printenv bootargs +bootargs=Please use defined boot +Odroid # setenv bootargs console=ttySAC1,115200n8 root=/dev/mmcblk0p2 rootwait +Odroid # bootz 40080000 - 42000000 +Kernel image @ 0x40080000 [ 0x000000 - 0x30bd58 ] +## Flattened Device Tree blob at 42000000 + Booting using the fdt blob at 0x42000000 + Loading Device Tree to 4fff1000, end 4ffff756 ... OK + +Starting kernel ... + +[ 0.000000] Booting Linux on physical CPU 0xa00 +... etc ... + +In the above example you can substitute 'dhcp' for 'tftpboot' as well. + +USB Storage booting: +-------------------- +Similarly we can use the USB storage to load the kernel image/initrd/fdt etc +and boot. For this example, there is a USB drive plugged in. It has a FAT +1st partition and an EXT 2nd partition. Using the generic FS (ls/load) makes +it even easier to work with FAT/EXT file systems. +For this example the second EXT partition is used for booting and as rootfs. +The boot files - kernel and the dtb are present in the /boot directory of the +second partition. + +Odroid # usb start +(Re)start USB... +USB0: USB EHCI 1.00 +scanning bus 0 for devices... 4 USB Device(s) found + scanning usb for storage devices... 1 Storage Device(s) found + scanning usb for ethernet devices... +Error: sms0 address not set. <----- Note the error as usbethaddr +Warning: failed to set MAC address <----- is not set. +1 Ethernet Device(s) found +Odroid # usb part 0 + +Partition Map for USB device 0 -- Partition Type: DOS + +Part Start Sector Num Sectors UUID Type + 1 3072 263168 000c4046-01 06 + 2 266240 13457408 000c4046-02 83 + +Odroid # ls usb 0:2 /boot +<DIR> 4096 . +<DIR> 4096 .. + 353 boot.scr + 281 boot.txt + 101420 config-3.8.13.23 + 2127254 initrd.img-3.8.13.23 + 2194825 uInitrd + 2194825 uInitrd-3.8.13.23 + 2453112 zImage + 101448 config-3.8.13.26 + 2127670 uInitrd-3.8.13.26 + 2127606 initrd.img-3.8.13.26 + 3194200 zImage.3.17 <--- Kernel + 46935 exynos4412-odroidu3.dtb <--- DTB +Odroid # load usb 0:2 40080000 /boot/zImage.3.17 +3194200 bytes read in 471 ms (6.5 MiB/s) +Odroid # load usb 0:2 42000000 /boot/exynos4412-odroidu3.dtb +46935 bytes read in 233 ms (196.3 KiB/s) +Odroid # setenv bootargs console=ttySAC1,115200n8 root=/dev/sda2 rootwait +Odroid # bootz 40080000 - 42000000 +Kernel image @ 0x40080000 [ 0x000000 - 0x30bd58 ] +## Flattened Device Tree blob at 42000000 + Booting using the fdt blob at 0x42000000 + Loading Device Tree to 4fff1000, end 4ffff756 ... OK + +Starting kernel ... + +[ 0.000000] Booting Linux on physical CPU 0xa00 + +Please refer to README.usb for additional information. diff --git a/roms/u-boot/doc/README.omap-ulpi-viewport b/roms/u-boot/doc/README.omap-ulpi-viewport new file mode 100644 index 000000000..a5240b9e2 --- /dev/null +++ b/roms/u-boot/doc/README.omap-ulpi-viewport @@ -0,0 +1,27 @@ +Reference code ""drivers/usb/ulpi/omap-ulpi-viewport.c" + +Contains the ulpi read write api's to perform +any ulpi phy port access on omap platform. + +On omap ehci reg map contains INSNREG05_ULPI +register which offers the ulpi phy access so +any ulpi phy commands should be passsed using this +register. + +omap-ulpi-viewport.c is a low level function +implementation of "drivers/usb/ulpi/ulpi.c" + +To enable and use omap-ulpi-viewport.c +we require CONFIG_USB_ULPI_VIEWPORT_OMAP and +CONFIG_USB_ULPI be enabled in config file. + +Any ulpi ops request can be done with ulpi.c +and soc specific binding and usage is done with +omap-ulpi-viewport implementation. + +Ex: scenario: +omap-ehci driver code requests for ulpi phy reset if +ehci is used in phy mode, which will call ulpi phy reset +the ulpi phy reset does ulpi_read/write from viewport +implementation which will do ulpi reset using the +INSNREG05_ULPI register. diff --git a/roms/u-boot/doc/README.omap3 b/roms/u-boot/doc/README.omap3 new file mode 100644 index 000000000..208714ad6 --- /dev/null +++ b/roms/u-boot/doc/README.omap3 @@ -0,0 +1,199 @@ + +Summary +======= + +This README is about U-Boot support for TI's ARM Cortex-A8 based OMAP3 [1] +family of SoCs. TI's OMAP3 SoC family contains an ARM Cortex-A8. Additionally, +some family members contain a TMS320C64x+ DSP and/or an Imagination SGX 2D/3D +graphics processor and various other standard peripherals. + +Currently the following boards are supported: + +* OMAP3530 BeagleBoard [2] + +* Gumstix Overo [3] + +* TI EVM [4] + +* OpenPandora Ltd. Pandora [5] + +* TI/Logic PD Zoom MDK [6] + +* TI/Logic PD Zoom 2 [7] + +* CompuLab Ltd. CM-T35 [8] + +Build +===== + +* BeagleBoard: + +make omap3_beagle_config +make + +* Gumstix Overo: + +make omap3_overo_config +make + +* TI EVM: + +make omap3_evm_config +make + +* Zoom 2: + +make omap3_zoom2_config +make + +* CM-T35: + +make cm_t35_config +make + + +Custom commands +=============== + +To make U-Boot for OMAP3 support NAND device SW or HW ECC calculation, U-Boot +for OMAP3 supports custom user command + +nandecc hw/sw + +To be compatible with NAND drivers using SW ECC (e.g. kernel code) + +nandecc sw + +enables SW ECC calculation. HW ECC enabled with + +nandecc hw + +is typically used to write 2nd stage bootloader (known as 'x-loader') which is +executed by OMAP3's boot rom and therefore has to be written with HW ECC. + +For all other commands see + +help + +Interfaces +========== + +gpio +---- + +To set a bit : + + if (!gpio_request(N, "")) { + gpio_direction_output(N, 0); + gpio_set_value(N, 1); + } + +To clear a bit : + + if (!gpio_request(N, "")) { + gpio_direction_output(N, 0); + gpio_set_value(N, 0); + } + +To read a bit : + + if (!gpio_request(N, "")) { + gpio_direction_input(N); + val = gpio_get_value(N); + gpio_free(N); + } + if (val) + printf("GPIO N is set\n"); + else + printf("GPIO N is clear\n"); + +dma +--- +void omap3_dma_init(void) + Init the DMA module +int omap3_dma_get_conf_chan(uint32_t chan, struct dma4_chan *config); + Read config of the channel +int omap3_dma_conf_chan(uint32_t chan, struct dma4_chan *config); + Write config to the channel +int omap3_dma_conf_transfer(uint32_t chan, uint32_t *src, uint32_t *dst, + uint32_t sze) + Config source, destination and size of a transfer +int omap3_dma_wait_for_transfer(uint32_t chan) + Wait for a transfer to end - this hast to be called before a channel + or the data the channel transferd are used. +int omap3_dma_get_revision(uint32_t *minor, uint32_t *major) + Read silicon Revision of the DMA module + +NAND +==== + +There are some OMAP3 devices out there with NAND attached. Due to the fact that +OMAP3 ROM code can only handle 1-bit hamming ECC for accessing first page +(place where SPL lives) we require this setup for u-boot at least when reading +the second progam within SPL. A lot of newer NAND chips however require more +than 1-bit ECC for the pages, some can live with 1-bit for the first page. To +handle this we can switch to another ECC algorithm after reading the payload +within SPL. + +BCH8 +---- + +To enable hardware assisted BCH8 (8-bit BCH [Bose, Chaudhuri, Hocquenghem]) on +OMAP3 devices we can use the BCH library in lib/bch.c. To do so add CONFIG_BCH +and set CONFIG_NAND_OMAP_ECCSCHEME=5 (refer README.nand) for selecting BCH8_SW. +The NAND OOB layout is the same as in linux kernel, if the linux kernel BCH8 +implementation for OMAP3 works for you so the u-boot version should also. +When you require the SPL to read with BCH8 there are two more configs to +change: + + * CONFIG_SYS_NAND_ECCPOS (must be the same as .eccpos in + GPMC_NAND_HW_BCH8_ECC_LAYOUT defined in + arch/arm/include/asm/arch-omap3/omap_gpmc.h) + * CONFIG_SYS_NAND_ECCSIZE must be 512 + * CONFIG_SYS_NAND_ECCBYTES must be 13 for this BCH8 setup + +Acknowledgements +================ + +OMAP3 U-Boot is based on U-Boot tar ball [9] for BeagleBoard and EVM done by +several TI employees. + +Links +===== + +[1] OMAP3: + +http://www.ti.com/omap3 (high volume) and +http://www.ti.com/omap35x (broad market) + +[2] OMAP3530 BeagleBoard: + +http://beagleboard.org/ + +[3] Gumstix Overo: + +http://www.gumstix.net/Overo/ + +[4] TI EVM: + +http://focus.ti.com/docs/toolsw/folders/print/tmdxevm3503.html + +[5] OpenPandora Ltd. Pandora: + +http://openpandora.org/ + +[6] TI/Logic PD Zoom MDK: + +http://www.logicpd.com/products/devkit/ti/zoom_mobile_development_kit + +[7] TI/Logic PD Zoom 2 + +http://www.logicpd.com/sites/default/files/1012659A_Zoom_OMAP34x-II_MDP_Brief.pdf + +[8] CompuLab Ltd. CM-T35: + +http://www.compulab.co.il/t3530/html/t3530-cm-datasheet.htm + +[9] TI OMAP3 U-Boot: + +http://beagleboard.googlecode.com/files/u-boot_beagle_revb.tar.gz diff --git a/roms/u-boot/doc/README.pblimage b/roms/u-boot/doc/README.pblimage new file mode 100644 index 000000000..7fdd26b71 --- /dev/null +++ b/roms/u-boot/doc/README.pblimage @@ -0,0 +1,111 @@ +------------------------------------------------------------------ +Freescale PBL(pre-boot loader) Boot Image generation using mkimage +------------------------------------------------------------------ + +The CoreNet SoC's can boot directly from eSPI FLASH, SD/MMC and +NAND, etc. These SoCs use PBL to load RCW and/or pre-initialization +instructions. For more details refer section 5 Pre-boot loader +specifications of reference manual P3041RM/P4080RM/P5020RM at link: +http://www.freescale.com/webapp/search/Serp.jsp?Reference+Manuals + +Building PBL Boot Image and boot steps +-------------------------------------- + +1. Building PBL Boot Image. + The default Image is u-boot.pbl. + + For eSPI boot(available on P2041/P3041/P4080/P5020/P5040/T4240): + To build the eSPI boot image: + make <board_name>_SPIFLASH + + For SD boot(available on P2041/P3041/P4080/P5020/P5040/T4240): + To build the SD boot image: + make <board_name>_SDCARD + + For Nand boot(available on P2041/P3041/P5020/P5040): + To build the NAND boot image: + make <board_name>_NAND + + +2. pblimage support available with mkimage utility will generate Freescale PBL +boot image that can be flashed on the board eSPI flash, SD/MMC and NAND. +Following steps describe it in detail. + + 1). Boot from eSPI flash + Write u-boot.pbl to eSPI flash from offset 0x0. + for ex in u-boot: + =>tftp 100000 u-boot.pbl + =>sf probe 0 + =>sf erase 0 100000 + =>sf write 100000 0 $filesize + Change SW1[1:5] = off off on off on. + + 2). Boot from SD/MMC + Write u-boot.pbl to SD/MMC from offset 0x1000. + for ex in u-boot: + =>tftp 100000 u-boot.pbl + =>mmcinfo + =>mmc write 100000 8 441 + Change SW1[1:5] = off off on on off. + + 3). Boot from Nand + Write u-boot.pbl to Nand from offset 0x0. + for ex in u-boot: + =>tftp 100000 u-boot.pbl + =>nand info + =>nand erase 0 100000 + =>nand write 100000 0 $filesize + Change SW1[1:5] = off on off off on + Change SW7[1:4] = on off off on + +Board specific configuration file specifications: +------------------------------------------------ +1. Configuration files rcw.cfg and pbi.cfg must present in the +board/freescale/corenet_ds/, rcw.cfg is for RCW, pbi.cfg is for +PBI instructions. File name must not be changed since they are used +in Makefile. +2. These files can have empty lines and lines starting with "#" as first +character to put comments + +Typical example of rcw.cfg file: +----------------------------------- + +#PBL preamble and RCW header +aa55aa55 010e0100 +#64 bytes RCW data +4c580000 00000000 18185218 0000cccc +40464000 3c3c2000 58000000 61000000 +00000000 00000000 00000000 008b6000 +00000000 00000000 00000000 00000000 + +Typical example of pbi.cfg file: +----------------------------------- + +#PBI commands +#Initialize CPC1 +09010000 00200400 +09138000 00000000 +091380c0 00000100 +09010100 00000000 +09010104 fff0000b +09010f00 08000000 +09010000 80000000 +#Configure LAW for CPC1 +09000d00 00000000 +09000d04 fff00000 +09000d08 81000013 +09000010 00000000 +09000014 ff000000 +09000018 81000000 +#Initialize eSPI controller +09110000 80000403 +09110020 2d170008 +09110024 00100008 +09110028 00100008 +0911002c 00100008 +#Flush PBL data +09138000 00000000 +091380c0 00000000 + +------------------------------------------------ +Author: Shaohui Xie<Shaohui.Xie@freescale.com> diff --git a/roms/u-boot/doc/README.pcap b/roms/u-boot/doc/README.pcap new file mode 100644 index 000000000..97b3e55fd --- /dev/null +++ b/roms/u-boot/doc/README.pcap @@ -0,0 +1,62 @@ +PCAP: + +U-boot supports live Ethernet packet capture in PCAP(2.4) format. +This is enabled by CONFIG_CMD_PCAP. + +The capture is stored on physical memory, and should be copied to +a machine capable of parsing and displaying PCAP files (IE. wireshark) +If networking works properly one can copy the capture file from physical memory +using tftpput, or save it to local storage with (sf write, mmc write, fatwrite, etc) + +the pcap capturing requires maximum buffer size. +when the buffer is full an error message will be displayed and then packets +will silently drop. +the actual capture file size is populate in the environment variable "pcapsize". + +Usage example: + +# Initialize pcap capture to physical address (0x100000) with maximum size of +# 100000 bytes. + +# Start capture +pcap start + +# Initialize network activity +env set ipaddr 10.0.2.15; env set serverip 10.0.2.2; tftp uImage64 + +# Stop capture +pcap stop + +# pcap init 0x100000 100000 +PCAP capture initialized: addr: 0xffffffff80100000 max length: 100000 + +# pcap start +# env set ipaddr 10.0.2.15; env set serverip 10.0.2.2; tftp uImage64 +eth0@10000000: PHY present at 0 +eth0@10000000: link up, 1000Mbps full-duplex (lpa: 0x7c00) +Using eth0@10000000 device +TFTP from server 10.0.2.2; our IP address is 10.0.2.15 +Filename 'uImage64'. +Load address: 0xffffffff88000000 +Loading: ################################################################# + ################################################################# + ################################################################# + ################################################################# +!!! Buffer is full, consider increasing buffer size !!! + ################################################################# + ################################################################# + ################################################################# + ################################################################# + ################################################################# + # + 18.2 MiB/s +done +Bytes transferred = 8359376 (7f8dd0 hex) +PCAP status: + Initialized addr: 0xffffffff80100000 max length: 100000 + Status: Active. file size: 99991 + Incoming packets: 66 Outgoing packets: 67 + +# pcap stop +# tftpput 0xffffffff80100000 $pcapsize 10.0.2.2:capture.pcap + diff --git a/roms/u-boot/doc/README.plan9 b/roms/u-boot/doc/README.plan9 new file mode 100644 index 000000000..2d3d0e0cf --- /dev/null +++ b/roms/u-boot/doc/README.plan9 @@ -0,0 +1,18 @@ +Plan 9 from Bell Labs kernel images require additional setup to pass +configuration information to the kernel. An environment variable named +confaddr must be defined with the same value as CONFADDR (see mem.h). +Use of this facility is optional, but should be preferable to manual +configuration. + +When booting an image, arguments supplied to the bootm command will be +copied to CONFADDR. If no arguments are specified, the contents of the +bootargs environment variable will be copied. + +If no command line arguments or bootargs are defined, CONFADDR is left +uninitialized to permit manual configuration. For example, PC-style +configuration could be simulated by issuing a fatload in bootcmd: + + # setenv bootcmd fatload mmc 0 $confaddr plan9.ini; ...; bootm + +Steven Stallion +June 2013 diff --git a/roms/u-boot/doc/README.power-framework b/roms/u-boot/doc/README.power-framework new file mode 100644 index 000000000..1f6fd4320 --- /dev/null +++ b/roms/u-boot/doc/README.power-framework @@ -0,0 +1,166 @@ +# +# (C) Copyright 2014 Samsung Electronics +# Lukasz Majewski <l.majewski@samsung.com> +# +# SPDX-License-Identifier: GPL-2.0+ +# + +Introduction +------------ + +This document describes the second version of the u-boot's PMIC (Power +Management IC) framework. As a reference boards please consider Samsungs' Trats +and Trats2. + +Background +---------- + +Boards supported by u-boot are getting increasingly complex. Developers and +designers strive to cut down power consumption. Hence several different types of +devices are now available on the board - namely power managers (PMIC), fuel +gauges (FG), micro USB interface controllers (MUIC), batteries, multi-function +devices (MFD). + +Explanation of key design decisions +----------------------------------- + +One package can integrate PMIC and MUIC with different addresses on the I2C bus. +The same device - e.g. MAX8997 uses two different I2C busses and addresses. + +Power devices use not only I2C for communication, but SPI as well. Additionally +different ICs use different endianess. For this reason struct pmic holds +information about I2C/SPI transmission, which is used with generic +pmic_req_write() function. + +The "flat" hierarchy for power devices works well when each device performs only +one operation - e.g. PMIC enables LDO. + +The problem emerges when we have a device (battery) which conceptually shall be +the master and uses methods exported by other devices. We need to control MUIC +to start charging the battery, use PMIC to reduce board's overall power +consumption (by disabling not needed LDOs, BUCKs) and get current state of +energy on the battery from FG. +Up till now u-boot doesn't support device model, so a simple one had to be +added. + +The directory hierarchy has following structure: +./include/power/<device_name>_<device_function>.h +e.g. ./include/power/max8997_pmic.h + +./drivers/power/pmic/power_{core files}.c +e.g. ./drivers/power/pmic/power_core.c + +./drivers/power/pmic/<device_function>/<device_function>_<device_name>.c +e.g. ./drivers/power/pmic/pmic_max8997.c +e.g. ./drivers/power/battery/trats/bat_trats.c +e.g. ./drivers/power/fuel_gauge/fg_max17042.c + +The framework classifies devices by their function - separate directories should +be maintained for different classes of devices. + +Current design +-------------- + +Everything is a power device described by struct pmic. Even battery is +considered as a valid power device. This helps for better management of those +devices. + +- Block diagram of the hierarchy: + ----------------- + --------| BAT |------------ + | | | | + | ----------------- | + | | | + \|/ \|/ \|/ + ----------- ----------------- --------- + |FG | |MUIC | |CHRG | + | | | | | | + ----------- ----------------- --------- + + +1. When hierarchy is not needed (no complex battery charge): + +Definition of the struct pmic is only required with proper name and parameters +for communication. This is enough to use the "pmic" command in the u-boot +prompt to change values of device's register (enable/disable LDO, BUCK). + +The PG, MUIC and CHRG above are regarded to be in the same level in the +hierarchy. + +2. Complex battery charging. + +To charge a battery, information from several "abstract" power devices is +needed (defined at ./include/power/pmic.h): +- FG device (struct power_fg): + -- *fg_battery_check - check if battery is not above its limits + -- *fg_battery_update - update the pmic framework with current + battery state(voltage and current capacity) + +- Charger device (struct power_chrq): + -- *chrg_type - type/capacity of the charger (including information + about USB cable disconnection) + -- *chrg_bat_present - detection if battery to be charged is + present + -- *chrg_state - status of the charger - if it is enabled or + disabled + +- Battery device (struct power_battery): + -- *battery_init - assign proper callbacks to be used by top + hierarchy battery device + -- *battery_charge - called from "pmic" command, responsible + for performing the charging + +Now two batteries are supported; trats and trats2 [*]. Those differ in the way +how they handle the exact charging. Trats uses polling (MAX8997) and trats2 +relies on the PMIC/MUIC HW completely (MAX77693). + +__Example for trats (this can be very different for other board):__ + -- *fg_battery_check -> FG device (fg_max17042.c) + -- *fg_battery_update -> FG device (fg_max17042.c) + -- *chrg_type -> MUIC device (muic_max8997.c) + -- *chrg_bat_present -> PMIC device (pmic_max8997.c) + -- *chrg_state -> PMIC device (pmic_max8997.c) + -- *battery_init -> BAT device (bat_trats.c) + -- *battery_charge -> BAT device (bat_trats.c) + +Also the struct pmic holds method (*low_power_mode) for reducing board's +power consumption when one calls "pmic BAT_TRATS bat charge" command. + +How to add a new power device +----------------------------- + +1. Simple device should be added with creation of file +<pmic_function>_<pmic_name>.c, <pmic_name>_<pmic_function>.h according to the +proposed and described above scheme. + +Then "pmic" command supports reading/writing/dump of device's internal +registers. + +2. Charging battery with hierarchy +Define devices as listed at 1. + +Define battery file (bat_<board>.c). Please also note that one might need a +corresponding battery model description for FG. + +For points 1 and 2 use a generic function power_init_board() to initialise the +power framework on your board. + +For reference, please look into the trats/trats2 boards. + +TO DO list (for PMICv3) - up till v2014.04 +------------------------------------------ + +1. Description of the devices related to power via device tree is not available. +This is the main problem when a developer tries to build a multi-boot u-boot +binary. The best would be to parse the DTS from Linux kernel. + +2. To support many instances of the same IC, like two MAX8997, one needs to +copy the corresponding pmic_max8997.c file with changed name to "MAX8997_PMICX", +where X is the device number. This problem will be addressed when extended +pmic_core.c will support storing available devices in a list. + +3. Definition of batteries [*] (for trats/trats2) should be excluded from the +code responsible for charging them and since it in fact describes the charging +profile it should be put to a separate file. + +4. Adjust the framework to work with the device model. diff --git a/roms/u-boot/doc/README.pxe b/roms/u-boot/doc/README.pxe new file mode 100644 index 000000000..b67151ca5 --- /dev/null +++ b/roms/u-boot/doc/README.pxe @@ -0,0 +1,258 @@ +SPDX-License-Identifier: GPL-2.0+ +/* + * Copyright 2010-2011 Calxeda, Inc. + */ + +The 'pxe' commands provide a near subset of the functionality provided by +the PXELINUX boot loader. This allows U-Boot based systems to be controlled +remotely using the same PXE based techniques that many non U-Boot based servers +use. + +Commands +======== + +pxe get +------- + syntax: pxe get + + follows PXELINUX's rules for retrieving configuration files from a tftp + server, and supports a subset of PXELINUX's config file syntax. + + Environment + ----------- + 'pxe get' requires two environment variables to be set: + + pxefile_addr_r - should be set to a location in RAM large enough to hold + pxe files while they're being processed. Up to 16 config files may be + held in memory at once. The exact number and size of the files varies with + how the system is being used. A typical config file is a few hundred bytes + long. + + bootfile,serverip - these two are typically set in the DHCP response + handler, and correspond to fields in the DHCP response. + + 'pxe get' optionally supports these two environment variables being set: + + ethaddr - this is the standard MAC address for the ethernet adapter in use. + 'pxe get' uses it to look for a configuration file specific to a system's + MAC address. + + pxeuuid - this is a UUID in standard form using lower case hexadecimal + digits, for example, 550e8400-e29b-41d4-a716-446655440000. 'pxe get' uses + it to look for a configuration file based on the system's UUID. + + File Paths + ---------- + 'pxe get' repeatedly tries to download config files until it either + successfully downloads one or runs out of paths to try. The order and + contents of paths it tries mirrors exactly that of PXELINUX - you can + read in more detail about it at: + + http://syslinux.zytor.com/wiki/index.php/Doc/pxelinux + +pxe boot +-------- + syntax: pxe boot [pxefile_addr_r] + + Interprets a pxe file stored in memory. + + pxefile_addr_r is an optional argument giving the location of the pxe file. + The file must be terminated with a NUL byte. + + Environment + ----------- + There are some environment variables that may need to be set, depending + on conditions. + + pxefile_addr_r - if the optional argument pxefile_addr_r is not supplied, + an environment variable named pxefile_addr_r must be supplied. This is + typically the same value as is used for the 'pxe get' command. + + bootfile - typically set in the DHCP response handler based on the + same field in the DHCP respone, this path is used to generate the base + directory that all other paths to files retrieved by 'pxe boot' will use. + If no bootfile is specified, paths used in pxe files will be used as is. + + serverip - typically set in the DHCP response handler, this is the IP + address of the tftp server from which other files will be retrieved. + + kernel_addr_r, initrd_addr_r - locations in RAM at which 'pxe boot' will + store the kernel(or FIT image) and initrd it retrieves from tftp. These + locations will be passed to the bootm command to boot the kernel. These + environment variables are required to be set. + + fdt_addr_r - location in RAM at which 'pxe boot' will store the fdt blob it + retrieves from tftp. The retrieval is possible if 'fdt' label is defined in + pxe file and 'fdt_addr_r' is set. If retrieval is possible, 'fdt_addr_r' + will be passed to bootm command to boot the kernel. + + fdt_addr - the location of a fdt blob. 'fdt_addr' will be passed to bootm + command if it is set and 'fdt_addr_r' is not passed to bootm command. + + fdtoverlay_addr_r - location in RAM at which 'pxe boot' will temporarily store + fdt overlay(s) before applying them to the fdt blob stored at 'fdt_addr_r'. + +pxe file format +=============== +The pxe file format is nearly a subset of the PXELINUX file format; see +http://syslinux.zytor.com/wiki/index.php/PXELINUX. It's composed of one line +commands - global commands, and commands specific to labels. Lines begining +with # are treated as comments. White space between and at the beginning of +lines is ignored. + +The size of pxe files and the number of labels is only limited by the amount +of RAM available to U-Boot. Memory for labels is dynamically allocated as +they're parsed, and memory for pxe files is statically allocated, and its +location is given by the pxefile_addr_r environment variable. The pxe code is +not aware of the size of the pxefile memory and will outgrow it if pxe files +are too large. + +Supported global commands +------------------------- +Unrecognized commands are ignored. + +default <label> - the label named here is treated as the default and is + the first label 'pxe boot' attempts to boot. + +menu title <string> - sets a title for the menu of labels being displayed. + +menu include <path> - use tftp to retrieve the pxe file at <path>, which + is then immediately parsed as if the start of its + contents were the next line in the current file. nesting + of include up to 16 files deep is supported. + +prompt <flag> - if 1, always prompt the user to enter a label to boot + from. if 0, only prompt the user if timeout expires. + +timeout <num> - wait for user input for <num>/10 seconds before + auto-booting a node. + +label <name> - begin a label definition. labels continue until + a command not recognized as a label command is seen, + or EOF is reached. + +Supported label commands +------------------------ +labels end when a command not recognized as a label command is reached, or EOF. + +menu default - set this label as the default label to boot; this is + the same behavior as the global default command but + specified in a different way + +kernel <path> - if this label is chosen, use tftp to retrieve the kernel + (or FIT image) at <path>. it will be stored at the address + indicated in the kernel_addr_r environment variable, and + that address will be passed to bootm to boot this kernel. + For FIT image, The configuration specification can be + appended to the file name, with the format: + <path>#<conf>[#<extra-conf[#...]] + It will passed to bootm with that address. + (see: doc/uImage.FIT/command_syntax_extensions.txt) + It useful for overlay selection in pxe file + (see: doc/uImage.FIT/overlay-fdt-boot.txt) + +fdtoverlays <path> [...] - if this label is chosen, use tftp to retrieve the DT + overlay(s) at <path>. it will be temporarily stored at the + address indicated in the fdtoverlay_addr_r environment variable, + and then applied in the load order to the fdt blob stored at the + address indicated in the fdt_addr_r environment variable. + +append <string> - use <string> as the kernel command line when booting this + label. + +initrd <path> - if this label is chosen, use tftp to retrieve the initrd + at <path>. it will be stored at the address indicated in + the initrd_addr_r environment variable, and that address + will be passed to bootm. + +fdt <path> - if this label is chosen, use tftp to retrieve the fdt blob + at <path>. it will be stored at the address indicated in + the fdt_addr_r environment variable, and that address will + be passed to bootm. + +fdtdir <path> - if this label is chosen, use tftp to retrieve a fdt blob + relative to <path>. If the fdtfile environment variable + is set, <path>/<fdtfile> is retrieved. Otherwise, the + filename is generated from the soc and board environment + variables, i.e. <path>/<soc>-<board>.dtb is retrieved. + If the fdt command is specified, fdtdir is ignored. + +localboot <flag> - Run the command defined by "localcmd" in the environment. + <flag> is ignored and is only here to match the syntax of + PXELINUX config files. + +Example +------- +Here's a couple of example files to show how this works. + +------------/tftpboot/pxelinux.cfg/menus/base.menu----------- +menu title Linux selections + +# This is the default label +label install + menu label Default Install Image + kernel kernels/install.bin + append console=ttyAMA0,38400 debug earlyprintk + initrd initrds/uzInitrdDebInstall + +# Just another label +label linux-2.6.38 + kernel kernels/linux-2.6.38.bin + append root=/dev/sdb1 + +# The locally installed kernel +label local + menu label Locally installed kernel + append root=/dev/sdb1 + localboot 1 +------------------------------------------------------------- + +------------/tftpboot/pxelinux.cfg/default------------------- +menu include pxelinux.cfg/menus/base.menu +timeout 500 + +default linux-2.6.38 +------------------------------------------------------------- + +When a pxe client retrieves and boots the default pxe file, +'pxe boot' will wait for user input for 5 seconds before booting +the linux-2.6.38 label, which will cause /tftpboot/kernels/linux-2.6.38.bin +to be downloaded, and boot with the command line "root=/dev/sdb1" + +Differences with PXELINUX +========================= +The biggest difference between U-Boot's pxe and PXELINUX is that since +U-Boot's pxe support is written entirely in C, it can run on any platform +with network support in U-Boot. Here are some other differences between +PXELINUX and U-Boot's pxe support. + +- U-Boot's pxe does not support the PXELINUX DHCP option codes specified + in RFC 5071, but could be extended to do so. + +- when U-Boot's pxe fails to boot, it will return control to U-Boot, + allowing another command to run, other U-Boot command, instead of resetting + the machine like PXELINUX. + +- U-Boot's pxe doesn't rely on or provide an UNDI/PXE stack in memory, it + only uses U-Boot. + +- U-Boot's pxe doesn't provide the full menu implementation that PXELINUX + does, only a simple text based menu using the commands described in + this README. With PXELINUX, it's possible to have a graphical boot + menu, submenus, passwords, etc. U-Boot's pxe could be extended to support + a more robust menuing system like that of PXELINUX's. + +- U-Boot's pxe expects U-Boot uimg's as kernels. Anything that would work + with the 'bootm' command in U-Boot could work with the 'pxe boot' command. + +- U-Boot's pxe only recognizes a single file on the initrd command line. It + could be extended to support multiple. + +- in U-Boot's pxe, the localboot command doesn't necessarily cause a local + disk boot - it will do whatever is defined in the 'localcmd' env + variable. And since it doesn't support a full UNDI/PXE stack, the + type field is ignored. + +- the interactive prompt in U-Boot's pxe only allows you to choose a label + from the menu. If you want to boot something not listed, you can ctrl+c + out of 'pxe boot' and use existing U-Boot commands to accomplish it. diff --git a/roms/u-boot/doc/README.ramboot-ppc85xx b/roms/u-boot/doc/README.ramboot-ppc85xx new file mode 100644 index 000000000..c9fef533a --- /dev/null +++ b/roms/u-boot/doc/README.ramboot-ppc85xx @@ -0,0 +1,102 @@ + RAMBOOT for MPC85xx Platforms + ============================== + +RAMBOOT literally means boot from DDR. But since DDR is volatile memory some +pre-mechanism is required to load the DDR with the bootloader binary. +- In case of SD and SPI boot this is done by BootROM code inside the chip + itself. +- In case of NAND boot FCM supports loading initial 4K code from NAND flash + which can initialize the DDR and get the complete bootloader copied to DDR. + +In addition to the above there could be some more methods to initialize the DDR +and load it manually. +Two of them are described below.There is also an explanation as to where these +methods could be handy. +1. Load the RAM based bootloader onto DDR via JTAG/BDI interface. And then + execute the bootloader from DDR. + This may be handy in the following cases: + - In very early stage of platform bringup where other boot options are not + functional because of various reasons. + - In case the support to program the flashes on the board is not available. + +2. Load the RAM based bootloader onto DDR using already existing bootloader on + the board.And then execute the bootloader from DDR. + Some usecases where this may be used: + - While developing some new feature of u-boot, for example USB driver or + SPI driver. + Suppose the board already has a working bootloader on it. And you would + prefer to keep it intact, at the same time want to test your bootloader. + In this case you can get your test bootloader binary into DDR via tftp + for example. Then execute the test bootloader. + - Suppose a platform already has a propreitery bootloader which does not + support for example AMP boot. In this case also RAM boot loader can be + utilized. + + So basically when the original bootloader is required to be kept intact + RAM based bootloader can offer an updated bootloader on the system. + +Both the above Bootloaders are slight variants of SDcard or SPI Flash +bootloader or for that matter even NAND bootloader. +All of them define CONFIG_SYS_RAMBOOT. +The main difference among all of them is the way the pre-environment is getting +configured and who is doing that. +- In case of SD card and SPI flash bootloader this is done by On Chip BootROM inside the Si itself. +- In case of NAND boot SPL/TPL code does it with some support from Si itself. +- In case of the pure RAM based bootloaders we have to do it by JTAG manually or already existing bootloader. + +How to use them: +1. Using JTAG + Boot up in core hold off mode or stop the core after reset using JTAG + interface. + Preconfigure DDR/L2SRAM through JTAG interface. + - setup DDR controller registers. + - setup DDR LAWs + - setup DDR TLB + Load the RAM based boot loader to the proper location in DDR/L2SRAM. + set up IAR (Instruction counter properly) + Enable the core to execute. + +2. Using already existing bootloader. + get the rambased boot loader binary into DDR/L2SRAM via tftp. + execute the RAM based bootloader. + => tftp 11000000 u-boot-ram.bin + => go 1107f000 + +Please note that L2SRAM can also be used instead of DDR if the SOC has +sufficient size of L2SRAM. + +Necessary Code changes Required: +===================================== +Please note that below mentioned changes are for 85xx platforms. +They have been tested on P1020/P2020/P1010 RDB. + +The main difference between the above two methods from technical perspective is +that in 1st case SOC is just out of reset so it is in default configuration. +(CCSRBAR is at 0xff700000). +In the 2nd case bootloader has already re-located CCSRBAR to 0xffe00000 + +1. File name-> boards.cfg + There can be added specific Make options for RAMBoot. We can keep different + options for the two cases mentioned above. + for example + P1020RDB_JTAG_RAMBOOT and P1020RDB_GO_RAMBOOT. + +2. platform config file + for example include/configs/P1_P2_RDB.h + + #ifdef CONFIG_RAMBOOT + #define CONFIG_SDCARD + #endif + + This will finally use the CONFIG_SYS_RAMBOOT. + +3. Change CONFIG_SYS_CCSRBAR_DEFAULT in menuconfig accordingly. + In the section of the particular SOC, for example P1020, pseudo code + + #if defined(CONFIG_GO) + #define CONFIG_SYS_CCSRBAR_DEFAULT 0xffe00000 + #else + #define CONFIG_SYS_CCSRBAR_DEFAULT 0xff700000 + #endif + +For JTAG RAMBOOT this is not required because CCSRBAR is at ff700000. diff --git a/roms/u-boot/doc/README.rmobile b/roms/u-boot/doc/README.rmobile new file mode 100644 index 000000000..ea170a25a --- /dev/null +++ b/roms/u-boot/doc/README.rmobile @@ -0,0 +1,98 @@ +Summary +======= + +This README is about U-Boot support for Renesas's ARM Cortex-A9 based RMOBILE[1] +and Cortex-A9/A53/A57 based R-Car[2] family of SoCs. Renesas's RMOBILE/R-Car SoC +family contains an ARM Cortex-A9/A53/A57. + +Currently the following boards are supported: + +| SoC | Board | defconfig +|===============+========================================+=================== +| R8A73A0 | KMC KZM-A9-GT [3] | kzm9g_config +| R8A7734 | Atmark-Techno Armadillo-800-EVA [4] | armadillo-800eva_config +|===============+========================================+=================== +| R8A7790 H2 | Renesas Electronics Lager | lager_defconfig +| | Renesas Electronics Stout | stout_defconfig +|---------------+----------------------------------------+------------------- +| R8A7791 M2-W | Renesas Electronics Koelsch | koelsch_defconfig +| | Renesas Electronics Porter | porter_defconfig +|---------------+----------------------------------------+------------------- +| R8A7792 V2H | Renesas Electronics Blanche | blanche_defconfig +|---------------+----------------------------------------+------------------- +| R8A7793 M2-N | Renesas Electronics Gose | gose_defconfig +|---------------+----------------------------------------+------------------- +| R8A7794 E2 | Renesas Electronics Alt | alt_defconfig +| | Renesas Electronics Silk | silk_defconfig +|===============+========================================+=================== +| R8A7795 H3 | Renesas Electronics Salvator-XS ES2.0+ | r8a7795_salvator-x_defconfig +| R8A7795 H3 | Renesas Electronics ULCB ES2.0+ | r8a7795_ulcb +|---------------+----------------------------------------+------------------- +| R8A7796 M3-W | Renesas Electronics Salvator-X | r8a7796_salvator-x_defconfig +| R8A7796 M3-W | Renesas Electronics ULCB | r8a7796_ulcb +|---------------+----------------------------------------+------------------- +| R8A77965 M3-N | Renesas Electronics Salvator-XS | r8a77965_salvator-x_defconfig +| R8A77965 M3-N | Renesas Electronics ULCB | r8a77965_ulcb +|---------------+----------------------------------------+------------------- +| R8A77970 V3M | Renesas Electronics Eagle | r8a77970_eagle_defconfig +|---------------+----------------------------------------+------------------- +| R8A77995 D3 | Renesas Electronics Draak | r8a77995_draak_defconfig +'===============+========================================+=================== + +Toolchain +========= + +Either ARMv7 toolchain for 32bit Cortex-A9 systems or ARMv8 (aarch64) +toolchain for 64bit Cortex-A53/A57 systems. Currently we compile the +32bit systems with -march=armv5 to allow more compilers to work. (For +U-Boot code this has no performance impact.) + +Currently, ELDK[5], Linaro[6], CodeSourcery[7] and Emdebian[8] supports +ARMv7. Modern distributions also contain ARMv7 and ARMv8 crosstoolchains +in their package feeds. + +Build +===== + +Locate defconfig in the table above. Then apply standard build procedure: + + make <board>_defconfig + make + + Note: Armadillo-800-EVA's U-Boot supports booting from SDcard only. + Please see "B.2 Appendix B Boot Specifications" in hardware manual. + +Links +===== + +[1] Renesas RMOBILE: + +http://am.renesas.com/products/soc/assp/mobile/r_mobile/index.jsp + +[2] Renesas R-Car: + +http://am.renesas.com/products/soc/assp/automotive/index.jsp + +[3] KZM-A9-GT + +http://www.kmckk.co.jp/kzma9-gt/index.html + +[4] Armadillo-800-EVA + +http://armadillo.atmark-techno.com/armadillo-800-EVA + +[5] ELDK + +http://www.denx.de/wiki/view/ELDK-5/WebHome#Section_1.6. + +[6] Linaro + +http://www.linaro.org/downloads/ + +[7] CodeSourcey + +http://www.mentor.com/embedded-software/codesourcery + +[8] Emdebian + +http://www.emdebian.org/crosstools.html diff --git a/roms/u-boot/doc/README.rockchip b/roms/u-boot/doc/README.rockchip new file mode 100644 index 000000000..154166ec7 --- /dev/null +++ b/roms/u-boot/doc/README.rockchip @@ -0,0 +1,703 @@ +# SPDX-License-Identifier: GPL-2.0+ +# +# Copyright (C) 2015 Google. Inc +# Written by Simon Glass <sjg@chromium.org> + +U-Boot on Rockchip +================== + +A wide range of Rockchip SoCs are supported in mainline U-Boot + +Warning +======= +This document is being moved to doc/board/rockchip, so information on it +might be incomplete or outdated. + +Prerequisites +============= + +You will need: + + - Firefly RK3288 board or something else with a supported RockChip SoC + - Power connection to 5V using the supplied micro-USB power cable + - Separate USB serial cable attached to your computer and the Firefly + (connect to the micro-USB connector below the logo) + - rkflashtool [3] + - openssl (sudo apt-get install openssl) + - Serial UART connection [4] + - Suitable ARM cross compiler, e.g.: + sudo apt-get install gcc-4.7-arm-linux-gnueabi + +Building +======== + +1. To build RK3288 board: + + CROSS_COMPILE=arm-linux-gnueabi- make O=firefly firefly-rk3288_defconfig all + + (or you can use another cross compiler if you prefer) + +2. To build RK3308 board: + - Get the rkbin + => git clone https://github.com/rockchip-linux/rkbin.git + + - Compile U-Boot + => cd /path/to/u-boot + => export BL31=/path/to/rkbin/bin/rk33/rk3308_bl31_v2.22.elf + => make roc-cc-rk3308_defconfig + => make CROSS_COMPILE=aarch64-linux-gnu- all + => ./tools/mkimage -n rk3308 -T rksd -d /path/to/rkbin/bin/rk33/rk3308_ddr_589MHz_uart2_m0_v1.26.bin idbloader.img + => cat spl/u-boot-spl.bin >> idbloader.img + +3. To build RK3399 board: + + Option 1: Package the image with Rockchip miniloader: + + - Compile U-Boot + + => cd /path/to/u-boot + => make nanopi-neo4-rk3399_defconfig + => make + + - Get the rkbin + + => git clone https://github.com/rockchip-linux/rkbin.git + + - Create trust.img + + => cd /path/to/rkbin + => ./tools/trust_merger RKTRUST/RK3399TRUST.ini + + - Create uboot.img + + => cd /path/to/rkbin + => ./tools/loaderimage --pack --uboot /path/to/u-boot/u-boot-dtb.bin uboot.img + + (Get trust.img and uboot.img) + + Option 2: Package the image with SPL: + + - Export cross compiler path for aarch64 + + - Compile ATF + + For Puma board. + + => git clone git://git.theobroma-systems.com/arm-trusted-firmware.git + => cd arm-trusted-firmware + => make CROSS_COMPILE=aarch64-linux-gnu- PLAT=rk3399 bl31 + + (export bl31.bin) + => export BL31=/path/to/arm-trusted-firmware/build/rk3399/release/bl31/bl31.bin + + For rest of rk3399 boards. + + => git clone https://github.com/ARM-software/arm-trusted-firmware.git + => cd arm-trusted-firmware + + (export cross compiler path for Cortex-M0 MCU likely arm-none-eabi-) + => make realclean + => make CROSS_COMPILE=aarch64-linux-gnu- PLAT=rk3399 + + (export bl31.elf) + => export BL31=/path/to/arm-trusted-firmware/build/rk3399/release/bl31/bl31.elf + + - Compile PMU M0 firmware + + This is optional for most of the rk3399 boards and required only for Puma board. + + => git clone git://git.theobroma-systems.com/rk3399-cortex-m0.git + => cd rk3399-cortex-m0 + + (export cross compiler path for Cortex-M0 PMU) + => make CROSS_COMPILE=arm-cortex_m0-eabi- + + (export rk3399m0.bin) + => export PMUM0=/path/to/rk3399-cortex-m0/rk3399m0.bin + + - Compile U-Boot + + => cd /path/to/u-boot + => make orangepi-rk3399_defconfig + => make + + (Get spl/u-boot-spl-dtb.bin, u-boot.itb images and some boards would get + spl/u-boot-spl.bin since it doesn't enable CONFIG_SPL_OF_CONTROL + + If TPL enabled on the target, get tpl/u-boot-tpl-dtb.bin or tpl/u-boot-tpl.bin + if CONFIG_TPL_OF_CONTROL not enabled) + +Writing to the board with USB +============================= + +For USB to work you must get your board into ROM boot mode, either by erasing +your MMC or (perhaps) holding the recovery button when you boot the board. +To erase your MMC, you can boot into Linux and type (as root) + + dd if=/dev/zero of=/dev/mmcblk0 bs=1M + +Connect your board's OTG port to your computer. + +To create a suitable image and write it to the board: + + ./firefly-rk3288/tools/mkimage -n rk3288 -T rkimage -d \ + ./firefly-rk3288/spl/u-boot-spl-dtb.bin out && \ + cat out | openssl rc4 -K 7c4e0304550509072d2c7b38170d1711 | rkflashtool l + +If all goes well you should something like: + + U-Boot SPL 2015.07-rc1-00383-ge345740-dirty (Jun 03 2015 - 10:06:49) + Card did not respond to voltage select! + spl: mmc init failed with error: -17 + ### ERROR ### Please RESET the board ### + +You will need to reset the board before each time you try. Yes, that's all +it does so far. If support for the Rockchip USB protocol or DFU were added +in SPL then we could in principle load U-Boot and boot to a prompt from USB +as several other platforms do. However it does not seem to be possible to +use the existing boot ROM code from SPL. + + +Writing to the eMMC with USB on ROC-RK3308-CC +============================================= +For USB to work you must get your board into Bootrom mode, +either by erasing the eMMC or short circuit the GND and D0 +on core board. + +Connect the board to your computer via tyepc. +=> rkdeveloptool db rk3308_loader_v1.26.117.bin +=> rkdeveloptool wl 0x40 idbloader.img +=> rkdeveloptool wl 0x4000 u-boot.itb +=> rkdeveloptool rd + +Then you will see the boot log from Debug UART at baud rate 1500000: +DDR Version V1.26 +REGFB: 0x00000032, 0x00000032 +In +589MHz +DDR3 + Col=10 Bank=8 Row=14 Size=256MB +msch:1 +Returning to boot ROM... + +U-Boot SPL 2020.01-rc1-00225-g34b681327f (Nov 14 2019 - 10:58:04 +0800) +Trying to boot from MMC1 +INFO: Preloader serial: 2 +NOTICE: BL31: v1.3(release):30f1405 +NOTICE: BL31: Built : 17:08:28, Sep 23 2019 +INFO: Lastlog: last=0x100000, realtime=0x102000, size=0x2000 +INFO: ARM GICv2 driver initialized +INFO: Using opteed sec cpu_context! +INFO: boot cpu mask: 1 +INFO: plat_rockchip_pmu_init: pd status 0xe b +INFO: BL31: Initializing runtime services +WARNING: No OPTEE provided by BL2 boot loader, Booting device without OPTEE initialization. SMC`s destined for OPTEE will rK +ERROR: Error initializing runtime service opteed_fast +INFO: BL31: Preparing for EL3 exit to normal world +INFO: Entry point address = 0x600000 +INFO: SPSR = 0x3c9 + + +U-Boot 2020.01-rc1-00225-g34b681327f (Nov 14 2019 - 10:58:47 +0800) + +Model: Firefly ROC-RK3308-CC board +DRAM: 254 MiB +MMC: dwmmc@ff480000: 0, dwmmc@ff490000: 1 +rockchip_dnl_key_pressed read adc key val failed +Net: No ethernet found. +Hit any key to stop autoboot: 0 +Card did not respond to voltage select! +switch to partitions #0, OK +mmc1(part 0) is current device +Scanning mmc 1:4... +Found /extlinux/extlinux.conf +Retrieving file: /extlinux/extlinux.conf +151 bytes read in 3 ms (48.8 KiB/s) +1: kernel-mainline +Retrieving file: /Image +14737920 bytes read in 377 ms (37.3 MiB/s) +append: earlycon=uart8250,mmio32,0xff0c0000 console=ttyS2,1500000n8 +Retrieving file: /rk3308-roc-cc.dtb +28954 bytes read in 4 ms (6.9 MiB/s) +Flattened Device Tree blob at 01f00000 +Booting using the fdt blob at 0x1f00000 +## Loading Device Tree to 000000000df3a000, end 000000000df44119 ... OK + +Starting kernel ... +[ 0.000000] Booting Linux on physical CPU 0x0000000000 [0x410fd042] +[ 0.000000] Linux version 5.4.0-rc1-00040-g4dc2d508fa47-dirty (andy@B150) (gcc version 6.3.1 20170404 (Linaro GCC 6.3-209 +[ 0.000000] Machine model: Firefly ROC-RK3308-CC board +[ 0.000000] earlycon: uart8250 at MMIO32 0x00000000ff0c0000 (options '') +[ 0.000000] printk: bootconsole [uart8250] enabled + +Booting from an SD card +======================= + +To write an image that boots from an SD card (assumed to be /dev/sdc): + + ./firefly-rk3288/tools/mkimage -n rk3288 -T rksd -d \ + firefly-rk3288/spl/u-boot-spl-dtb.bin out && \ + sudo dd if=out of=/dev/sdc seek=64 && \ + sudo dd if=firefly-rk3288/u-boot-dtb.img of=/dev/sdc seek=16384 + +This puts the Rockchip header and SPL image first and then places the U-Boot +image at block 16384 (i.e. 8MB from the start of the SD card). This +corresponds with this setting in U-Boot: + + #define CONFIG_SYS_MMCSD_RAW_MODE_U_BOOT_SECTOR 0x4000 + +Put this SD (or micro-SD) card into your board and reset it. You should see +something like: + + U-Boot 2016.01-rc2-00309-ge5bad3b-dirty (Jan 02 2016 - 23:41:59 -0700) + + Model: Radxa Rock 2 Square + DRAM: 2 GiB + MMC: dwmmc@ff0f0000: 0, dwmmc@ff0c0000: 1 + *** Warning - bad CRC, using default environment + + In: serial + Out: vop@ff940000.vidconsole + Err: serial + Net: Net Initialization Skipped + No ethernet found. + Hit any key to stop autoboot: 0 + => + +The rockchip bootrom can load and boot an initial spl, then continue to +load a second-stage bootloader (ie. U-Boot) as soon as the control is returned +to the bootrom. Both the RK3288 and the RK3036 use this special boot sequence. +The configuration option enabling this is: + + CONFIG_SPL_ROCKCHIP_BACK_TO_BROM=y + +You can create the image via the following operations: + + ./firefly-rk3288/tools/mkimage -n rk3288 -T rksd -d \ + firefly-rk3288/spl/u-boot-spl-dtb.bin out && \ + cat firefly-rk3288/u-boot-dtb.bin >> out && \ + sudo dd if=out of=/dev/sdc seek=64 + +Or: + ./firefly-rk3288/tools/mkimage -n rk3288 -T rksd -d \ + firefly-rk3288/spl/u-boot-spl-dtb.bin:firefly-rk3288/u-boot-dtb.bin \ + out && \ + sudo dd if=out of=/dev/sdc seek=64 + +If you have an HDMI cable attached you should see a video console. + +For evb_rk3036 board: + ./evb-rk3036/tools/mkimage -n rk3036 -T rksd -d evb-rk3036/spl/u-boot-spl.bin out && \ + cat evb-rk3036/u-boot-dtb.bin >> out && \ + sudo dd if=out of=/dev/sdc seek=64 + +Or: + ./evb-rk3036/tools/mkimage -n rk3036 -T rksd -d \ + evb-rk3036/spl/u-boot-spl.bin:evb-rk3036/u-boot-dtb.bin out && \ + sudo dd if=out of=/dev/sdc seek=64 + +Note: rk3036 SDMMC and debug uart use the same iomux, so if you boot from SD, the + debug uart must be disabled + + +Booting from an SD card on RK3288 with TPL +========================================== + +Since the size of SPL can't be exceeded 0x8000 bytes in RK3288, it is not possible add +new SPL features like Falcon mode or etc. + +So introduce TPL so-that adding new features to SPL is possible because now TPL should +run minimal with code like DDR, clock etc and rest of new features in SPL. + +As of now TPL is added on Vyasa-RK3288 board. + +To write an image that boots from an SD card (assumed to be /dev/mmcblk0): + + sudo dd if=idbloader.img of=/dev/mmcblk0 seek=64 && + sudo dd if=u-boot-dtb.img of=/dev/mmcblk0 seek=16384 + +Booting from an SD card on RK3188 +================================= + +For rk3188 boards the general storage onto the card stays the same as +described above, but the image creation needs a bit more care. + +The bootrom of rk3188 expects to find a small 1kb loader which returns +control to the bootrom, after which it will load the real loader, which +can then be up to 29kb in size and does the regular ddr init. This is +handled by a single image (built as the SPL stage) that tests whether +it is handled for the first or second time via code executed from the +boot0-hook. + +Additionally the rk3188 requires everything the bootrom loads to be +rc4-encrypted. Except for the very first stage the bootrom always reads +and decodes 2kb pages, so files should be sized accordingly. + +# copy tpl, pad to 1020 bytes and append spl +tools/mkimage -n rk3188 -T rksd -d spl/u-boot-spl.bin out + +# truncate, encode and append u-boot.bin +truncate -s %2048 u-boot.bin +cat u-boot.bin | split -b 512 --filter='openssl rc4 -K 7C4E0304550509072D2C7B38170D1711' >> out + +Booting from an SD card on Pine64 Rock64 (RK3328) +================================================= + +For Rock64 rk3328 board the following three parts are required: +TPL, SPL, and the u-boot image tree blob. + + - Write TPL/SPL image at 64 sector + + => sudo dd if=idbloader.img of=/dev/mmcblk0 seek=64 + + - Write u-boot image tree blob at 16384 sector + + => sudo dd if=u-boot.itb of=/dev/mmcblk0 seek=16384 + +Booting from an SD card on RK3399 +================================= + +To write an image that boots from an SD card (assumed to be /dev/sdc): + +Option 1: Package the image with Rockchip miniloader: + + - Create idbloader.img + + => cd /path/to/u-boot + => ./tools/mkimage -n rk3399 -T rksd -d /path/to/rkbin/bin/rk33/rk3399_ddr_800MHz_v1.20.bin idbloader.img + => cat /path/to/rkbin/bin/rk33/rk3399_miniloader_v1.19.bin >> idbloader.img + + - Write idbloader.img at 64 sector + + => sudo dd if=idbloader.img of=/dev/sdc seek=64 + + - Write trust.img at 24576 + + => sudo dd if=trust.img of=/dev/sdc seek=24576 + + - Write uboot.img at 16384 sector + + => sudo dd if=uboot.img of=/dev/sdc seek=16384 + => sync + +Put this SD (or micro-SD) card into your board and reset it. You should see +something like: + +DDR Version 1.20 20190314 +In +Channel 0: DDR3, 933MHz +Bus Width=32 Col=10 Bank=8 Row=15 CS=1 Die Bus-Width=16 Size=1024MB +no stride +ch 0 ddrconfig = 0x101, ddrsize = 0x20 +pmugrf_os_reg[2] = 0x10006281, stride = 0x17 +OUT +Boot1: 2019-03-14, version: 1.19 +CPUId = 0x0 +ChipType = 0x10, 239 +mmc: ERROR: SDHCI ERR:cmd:0x102,stat:0x18000 +mmc: ERROR: Card did not respond to voltage select! +emmc reinit +mmc: ERROR: SDHCI ERR:cmd:0x102,stat:0x18000 +mmc: ERROR: Card did not respond to voltage select! +emmc reinit +mmc: ERROR: SDHCI ERR:cmd:0x102,stat:0x18000 +mmc: ERROR: Card did not respond to voltage select! +SdmmcInit=2 1 +mmc0:cmd5,20 +SdmmcInit=0 0 +BootCapSize=0 +UserCapSize=60543MB +FwPartOffset=2000 , 0 +StorageInit ok = 45266 +SecureMode = 0 +SecureInit read PBA: 0x4 +SecureInit read PBA: 0x404 +SecureInit read PBA: 0x804 +SecureInit read PBA: 0xc04 +SecureInit read PBA: 0x1004 +SecureInit read PBA: 0x1404 +SecureInit read PBA: 0x1804 +SecureInit read PBA: 0x1c04 +SecureInit ret = 0, SecureMode = 0 +atags_set_bootdev: ret:(0) +GPT 0x3380ec0 signature is wrong +recovery gpt... +GPT 0x3380ec0 signature is wrong +recovery gpt fail! +LoadTrust Addr:0x4000 +No find bl30.bin +Load uboot, ReadLba = 2000 +hdr 0000000003380880 + 0x0:0x88,0x41,0x3e,0x97,0xe6,0x61,0x54,0x23,0xe9,0x5a,0xd1,0x2b,0xdc,0x2f,0xf9,0x35, + +Load OK, addr=0x200000, size=0x9c9c0 +RunBL31 0x10000 +NOTICE: BL31: v1.3(debug):370ab80 +NOTICE: BL31: Built : 09:23:41, Mar 4 2019 +NOTICE: BL31: Rockchip release version: v1.1 +INFO: GICv3 with legacy support detected. ARM GICV3 driver initialized in EL3 +INFO: Using opteed sec cpu_context! +INFO: boot cpu mask: 0 +INFO: plat_rockchip_pmu_init(1181): pd status 3e +INFO: BL31: Initializing runtime services +INFO: BL31: Initializing BL32 +INF [0x0] TEE-CORE:init_primary_helper:337: Initializing (1.1.0-195-g8f090d20 #6 Fri Dec 7 06:11:20 UTC 2018 aarch64) + +INF [0x0] TEE-CORE:init_primary_helper:338: Release version: 1.2 + +INF [0x0] TEE-CORE:init_teecore:83: teecore inits done +INFO: BL31: Preparing for EL3 exit to normal world +INFO: Entry point address = 0x200000 +INFO: SPSR = 0x3c9 + + +U-Boot 2019.04-rc4-00136-gfd121f9641-dirty (Apr 16 2019 - 14:02:47 +0530) + +Model: FriendlyARM NanoPi NEO4 +DRAM: 1022 MiB +MMC: dwmmc@fe310000: 2, dwmmc@fe320000: 1, sdhci@fe330000: 0 +Loading Environment from MMC... *** Warning - bad CRC, using default environment + +In: serial@ff1a0000 +Out: serial@ff1a0000 +Err: serial@ff1a0000 +Model: FriendlyARM NanoPi NEO4 +Net: eth0: ethernet@fe300000 +Hit any key to stop autoboot: 0 +=> + +Option 2: Package the image with SPL: + + - Prefix rk3399 header to SPL image + + => cd /path/to/u-boot + => ./tools/mkimage -n rk3399 -T rksd -d spl/u-boot-spl-dtb.bin out + + - Write prefixed SPL at 64th sector + + => sudo dd if=out of=/dev/sdc seek=64 + + - Write U-Boot proper at 16384 sector + + => sudo dd if=u-boot.itb of=/dev/sdc seek=16384 + => sync + +Put this SD (or micro-SD) card into your board and reset it. You should see +something like: + +U-Boot SPL board init +Trying to boot from MMC1 + + +U-Boot 2019.01-00004-g14db5ee998 (Mar 11 2019 - 13:18:41 +0530) + +Model: Orange Pi RK3399 Board +DRAM: 2 GiB +MMC: dwmmc@fe310000: 2, dwmmc@fe320000: 1, sdhci@fe330000: 0 +Loading Environment from MMC... OK +In: serial@ff1a0000 +Out: serial@ff1a0000 +Err: serial@ff1a0000 +Model: Orange Pi RK3399 Board +Net: eth0: ethernet@fe300000 +Hit any key to stop autoboot: 0 +=> + +Option 3: Package the image with TPL: + + - Write tpl+spl at 64th sector + + => sudo dd if=idbloader.img of=/dev/sdc seek=64 + + - Write U-Boot proper at 16384 sector + + => sudo dd if=u-boot.itb of=/dev/sdc seek=16384 + => sync + +Put this SD (or micro-SD) card into your board and reset it. You should see +something like: + +U-Boot TPL board init +Trying to boot from BOOTROM +Returning to boot ROM... + +U-Boot SPL board init +Trying to boot from MMC1 + + +U-Boot 2019.07-rc1-00241-g5b3244767a (May 08 2019 - 10:51:06 +0530) + +Model: Orange Pi RK3399 Board +DRAM: 2 GiB +MMC: dwmmc@fe310000: 2, dwmmc@fe320000: 1, sdhci@fe330000: 0 +Loading Environment from MMC... OK +In: serial@ff1a0000 +Out: serial@ff1a0000 +Err: serial@ff1a0000 +Model: Orange Pi RK3399 Board +Net: eth0: ethernet@fe300000 +Hit any key to stop autoboot: 0 +=> + +Using fastboot on rk3288 +======================== +- Write GPT partition layout to mmc device which fastboot want to use it to +store the image + + => gpt write mmc 1 $partitions + +- Invoke fastboot command to prepare + + => fastboot 1 + +- Start fastboot request on PC + + fastboot -i 0x2207 flash loader evb-rk3288/spl/u-boot-spl-dtb.bin + +You should see something like: + + => fastboot 1 + WARNING: unknown variable: partition-type:loader + Starting download of 357796 bytes + .. + downloading of 357796 bytes finished + Flashing Raw Image + ........ wrote 357888 bytes to 'loader' + +Booting from SPI +================ + +To write an image that boots from SPI flash (e.g. for the Haier Chromebook or +Bob): + + ./chromebook_jerry/tools/mkimage -n rk3288 -T rkspi \ + -d chromebook_jerry/spl/u-boot-spl-dtb.bin spl.bin && \ + dd if=spl.bin of=spl-out.bin bs=128K conv=sync && \ + cat spl-out.bin chromebook_jerry/u-boot-dtb.img >out.bin && \ + dd if=out.bin of=out.bin.pad bs=4M conv=sync + +This converts the SPL image to the required SPI format by adding the Rockchip +header and skipping every second 2KB block. Then the U-Boot image is written at +offset 128KB and the whole image is padded to 4MB which is the SPI flash size. +The position of U-Boot is controlled with this setting in U-Boot: + + #define CONFIG_SYS_SPI_U_BOOT_OFFS 0x20000 + +If you have a Dediprog em100pro connected then you can write the image with: + + sudo em100 -s -c GD25LQ32 -d out.bin.pad -r + +When booting you should see something like: + + U-Boot SPL 2015.07-rc2-00215-g9a58220-dirty (Jun 23 2015 - 12:11:32) + + + U-Boot 2015.07-rc2-00215-g9a58220-dirty (Jun 23 2015 - 12:11:32 -0600) + + Model: Google Jerry + DRAM: 2 GiB + MMC: + Using default environment + + In: serial@ff690000 + Out: serial@ff690000 + Err: serial@ff690000 + => + +Future work +=========== + +Immediate priorities are: + +- USB host +- USB device +- Run CPU at full speed (code exists but we only see ~60 DMIPS maximum) +- NAND flash +- Boot U-Boot proper over USB OTG (at present only SPL works) + + +Development Notes +================= + +There are plenty of patches in the links below to help with this work. + +[1] https://github.com/rkchrome/uboot.git +[2] https://github.com/linux-rockchip/u-boot-rockchip.git branch u-boot-rk3288 +[3] https://github.com/linux-rockchip/rkflashtool.git +[4] http://wiki.t-firefly.com/index.php/Firefly-RK3288/Serial_debug/en + +rkimage +------- + +rkimage.c produces an SPL image suitable for sending directly to the boot ROM +over USB OTG. This is a very simple format - just the string RK32 (as 4 bytes) +followed by u-boot-spl-dtb.bin. + +The boot ROM loads image to 0xff704000 which is in the internal SRAM. The SRAM +starts at 0xff700000 and extends to 0xff718000 where we put the stack. + +rksd +---- + +rksd.c produces an image consisting of 32KB of empty space, a header and +u-boot-spl-dtb.bin. The header is defined by 'struct header0_info' although +most of the fields are unused by U-Boot. We just need to specify the +signature, a flag and the block offset and size of the SPL image. + +The header occupies a single block but we pad it out to 4 blocks. The header +is encoding using RC4 with the key 7c4e0304550509072d2c7b38170d1711. The SPL +image can be encoded too but we don't do that. + +The maximum size of u-boot-spl-dtb.bin which the boot ROM will read is 32KB, +or 0x40 blocks. This is a severe and annoying limitation. There may be a way +around this limitation, since there is plenty of SRAM, but at present the +board refuses to boot if this limit is exceeded. + +The image produced is padded up to a block boundary (512 bytes). It should be +written to the start of an SD card using dd. + +Since this image is set to load U-Boot from the SD card at block offset, +CONFIG_SYS_MMCSD_RAW_MODE_U_BOOT_SECTOR, dd should be used to write +u-boot-dtb.img to the SD card at that offset. See above for instructions. + +rkspi +----- + +rkspi.c produces an image consisting of a header and u-boot-spl-dtb.bin. The +resulting image is then spread out so that only the first 2KB of each 4KB +sector is used. The header is the same as with rksd and the maximum size is +also 32KB (before spreading). The image should be written to the start of +SPI flash. + +See above for instructions on how to write a SPI image. + +rkmux.py +-------- + +You can use this script to create #defines for SoC register access. See the +script for usage. + + +Device tree and driver model +---------------------------- + +Where possible driver model is used to provide a structure to the +functionality. Device tree is used for configuration. However these have an +overhead and in SPL with a 32KB size limit some shortcuts have been taken. +In general all Rockchip drivers should use these features, with SPL-specific +modifications where required. + +GPT partition layout +---------------------------- + +Rockchip use a unified GPT partition layout in open source support. +With this GPT partition layout, uboot can be compatilbe with other components, +like miniloader, trusted-os, arm-trust-firmware. + +There are some documents about partitions in the links below. +http://rockchip.wikidot.com/partitions + +-- +Jagan Teki <jagan@amarulasolutions.com> +27 Mar 2019 +Simon Glass <sjg@chromium.org> +24 June 2015 diff --git a/roms/u-boot/doc/README.rockusb b/roms/u-boot/doc/README.rockusb new file mode 100644 index 000000000..66437e17e --- /dev/null +++ b/roms/u-boot/doc/README.rockusb @@ -0,0 +1,56 @@ +Rockusb (Rockchip USB protocol) +===================================================== + +Overview +-------- + +Rockusb protocol is widely used by Rockchip SoC based devices. It can +read/write info, image to/from devices. This document briefly describes how to +use Rockusb for upgrading firmware (e.g. kernel, u-boot, rootfs, etc.). + +Tools +-------- +There are many tools can support Rockusb protocol. rkdeveloptool +(https://github.com/rockchip-linux/rkdeveloptool) is open source, +It is maintained by Rockchip. People don't want to build from source +can download from here +(https://github.com/rockchip-linux/rkbin/blob/master/tools/rkdeveloptool) + +Usage +-------- +The Usage of Rockusb command is: + +rockusb <USB_controller> <devtype> <dev[:part]> + +e.g. rockusb 0 mmc 0 + +On your U-Boot console, type this command to enter rockusb mode. +On your host PC. use lsusb command. you should see a usb device +using 0x2207 as its USB verdor id. + +for more detail about the rkdeveloptool. please read the usage. + +rkdeveloptool -h + +use rkdeveloptool wl command to write lba. BeginSec is the lba on device +you want to write. + +sudo rkdeveloptool wl <BeginSec> <File> + +to flash U-Boot image use below command. U-Boot binary is made by mkimage. +see doc/README.rockchip for more detail about how to get U-Boot binary. + +sudo rkdeveloptool wl 64 <U-Boot binary> + +Current set of rkdeveloptool commands supported: +- rci: Read Chip Info +- rfi: Read Flash Id +- rd : Reset Device +- td : Test Device Ready +- rl : Read blocks using LBA +- wl : Write blocks using LBA +- wlx: Write partition + +To do +----- +* Fully support Rockusb protocol diff --git a/roms/u-boot/doc/README.s5p4418 b/roms/u-boot/doc/README.s5p4418 new file mode 100644 index 000000000..ac724d08a --- /dev/null +++ b/roms/u-boot/doc/README.s5p4418 @@ -0,0 +1,63 @@ + +Summary +======= + +This README is about U-Boot support for SAMSUNG's/NEXELL's ARM Cortex-A9 based +S5P4418 SoC. It is based on FriendlyARM's U-Boot v2016.01 for the NanoPi2 +(and other) boards [1]. + +Currently the following boards are supported: + +* FriendlyArm NanoPi2 [2] +* FriendlyArm NanoPC-T2 [3] + + +Build +===== + +* NanoPi2 and NanoPC-T2 + +make s5p4418_nanopi2_defconfig +make + + +Installation +============ + +- Download Official-ROMs-SDCard-20190718.7z from [4] (images files for android, + friendlyCore and LUbuntu) +- Use s5p4418-sd-lubuntu-desktop-xenial-4.4-armhf-20190718.img to make a SD-card +- Use dd in the directory where U-Boot has been built to update U-Boot: + (replace <SD-card> with the device used for the SD-card, e.g. sdc) + sudo dd seek=3841 if=u-boot.bin of=/dev/<SD-card> +- Boot the board from this SD-card + +The source code for (the used?) LUbuntu 16.04 can be found at [5]. + + +Links +===== + +[1] FriendlyArm U-boot v2016.01: + +https://github.com/friendlyarm/u-boot/tree/nanopi2-v2016.01 + + +[2] NanoPi2: + +http://wiki.friendlyarm.com/wiki/index.php/NanoPi_2 + + +[3] NanoPC-T2: + +http://wiki.friendlyarm.com/wiki/index.php/NanoPC-T2 + + +[4] FriendlyArm image files for NanoPi2: + +http://download.friendlyarm.com//NanoPi2 + + +[5] FriendlyArm LUbuntu 16.04 Source Code for NanoPi2: + +https://github.com/friendlyarm/linux/tree/nanopi2-v4.4.y diff --git a/roms/u-boot/doc/README.s5pc1xx b/roms/u-boot/doc/README.s5pc1xx new file mode 100644 index 000000000..ab1f02469 --- /dev/null +++ b/roms/u-boot/doc/README.s5pc1xx @@ -0,0 +1,72 @@ + +Summary +======= + +This README is about U-Boot support for SAMSUNG's ARM Cortex-A8 based S5PC1xx +family of SoCs (S5PC100 [1] and S5PC110). + +Currently the following board is supported: + +* SMDKC100 [2] + +Toolchain +========= + +While ARM Cortex-A8 support ARM v7 instruction set (-march=armv7a) we compile +with -march=armv5 to allow more compilers to work. For U-Boot code this has +no performance impact. + +Build +===== + +* SMDKC100 + +make smdkc100_config +make + + +Interfaces +========== + +cpu + +To check SoC: + + if (cpu_is_s5pc100()) + printf("cpu is s5pc100\n"); + + or + + if (cpu_is_s5pc110()) + printf("cpu is s5pc110\n"); + +gpio + + struct s5pc100_gpio *gpio = (struct s5pc100_gpio*)S5PC100_GPIO_BASE; + + /* GPA[0] pin set to irq */ + gpio_cfg_pin(&gpio->gpio_a, 0, GPIO_IRQ); + + /* GPA[0] pin set to input */ + gpio_direction_input(&gpio->gpio_a, 0); + + /* GPA[0] pin set to output/high */ + gpio_direction_output(&gpio->gpio_a, 0, 1); + + /* GPA[0] value set to low */ + gpio_set_value(&gpio->gpio_a, 0, 0); + + /* get GPA[0] value */ + value = gpio_get_value(&gpio->gpio_a, 0); + +Links +===== + +[1] S5PC100: + +http://www.samsung.com/global/business/semiconductor/productInfo.do? +fmly_id=229&partnum=S5PC100 + +[2] SMDKC100: + +http://meritech.co.kr/eng/products/product_view.php?num=28 diff --git a/roms/u-boot/doc/README.sata b/roms/u-boot/doc/README.sata new file mode 100644 index 000000000..b1104bbd3 --- /dev/null +++ b/roms/u-boot/doc/README.sata @@ -0,0 +1,68 @@ +1. SATA usage in U-Boot + + There are two ways to operate the hard disk + + * Read/write raw blocks from/to SATA hard disk + * ext2load to read a file from ext2 file system + +1.0 How to read the SATA hard disk's information? + + => sata info + +SATA device 0: Model: ST3320620AS Firm: 3.AAD Ser#: 4QF01ZTN + Type: Hard Disk + Supports 48-bit addressing + Capacity: 305245.3 MB = 298.0 GB (625142448 x 512) + +1.1 How to raw write the kernel, file system, dtb to a SATA hard disk? + + Notes: Hard disk sectors are normally 512 bytes, so + 0x1000 sectors = 2 MBytes + + write kernel + => tftp 40000 /tftpboot/uImage.837x + => sata write 40000 0 2000 + + write ramdisk + => tftp 40000 /tftpboot/ramdisk.837x + => sata write 40000 2000 8000 + + write dtb + => tftp 40000 /tftpboot/mpc837xemds.dtb + => sata write 40000 a000 1000 + +1.2 How to raw read the kernel, file system, dtb from a SATA hard disk? + + load kernel + => sata read 200000 0 2000 + + load ramdisk + => sata read 1000000 2000 8000 + + load dtb + => sata read 2000000 a000 1000 + + boot + => bootm 200000 1000000 2000000 + +1.3 How to load an image from an ext2 file system in U-Boot? + + U-Boot doesn't support writing to an ext2 file system, so the + files must be written by other means (e.g. linux). + + => ext2ls sata 0:1 / + <DIR> 4096 . + <DIR> 4096 .. + <DIR> 16384 lost+found + 1352023 uImage.837x + 3646377 ramdisk.837x + 12288 mpc837xemds.dtb + 12 hello.txt + + => ext2load sata 0:1 200000 /uImage.837x + + => ext2load sata 0:1 1000000 /ramdisk.837x + + => ext2load sata 0:1 2000000 /mpc837xemds.dtb + + => bootm 200000 1000000 2000000 diff --git a/roms/u-boot/doc/README.sched b/roms/u-boot/doc/README.sched new file mode 100644 index 000000000..3aa89e6d3 --- /dev/null +++ b/roms/u-boot/doc/README.sched @@ -0,0 +1,53 @@ +Notes on the scheduler in sched.c: +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + + 'sched.c' provides an very simplistic multi-threading scheduler. + See the example, function 'sched(...)', in the same file for its + API usage. + + Until an exhaustive testing can be done, the implementation cannot + qualify as that of production quality. It works with the example + in 'sched.c', it may or may not work in other cases. + + +Limitations: +~~~~~~~~~~~~ + + - There are NO primitives for thread synchronization (locking, + notify etc). + + - Only the GPRs and FPRs context is saved during a thread context + switch. Other registers on the PowerPC processor (60x, 7xx, 7xxx + etc) are NOT saved. + + - The scheduler is NOT transparent to the user. The user + applications must invoke thread_yield() to allow other threads to + scheduler. + + - There are NO priorities, and the scheduling policy is round-robin + based. + + - There are NO capabilities to collect thread CPU usage, scheduler + stats, thread status etc. + + - The semantics are somewhat based on those of pthreads, but NOT + the same. + + - Only seven threads are allowed. These can be easily increased by + changing "#define MAX_THREADS" depending on the available memory. + + - The stack size of each thread is 8KBytes. This can be easily + increased depending on the requirement and the available memory, + by increasing "#define STK_SIZE". + + - Only one master/parent thread is allowed, and it cannot be + stopped or deleted. Any given thread is NOT allowed to stop or + delete itself. + + - There NOT enough safety checks as are probably in the other + threads implementations. + + - There is no parent-child relationship between threads. Only one + thread may thread_join, preferably the master/parent thread. + +(C) 2003 Arun Dharankar <ADharankar@ATTBI.Com> diff --git a/roms/u-boot/doc/README.scrapyard b/roms/u-boot/doc/README.scrapyard new file mode 100644 index 000000000..24a6c1be1 --- /dev/null +++ b/roms/u-boot/doc/README.scrapyard @@ -0,0 +1,11 @@ +Over time, support for more and more boards gets added to U-Boot - +while other board support code dies a silent death caused by +negligence in combination with ordinary bitrot. Sometimes this goes +by unnoticed, but often build errors will result. If nobody cares any +more to resolve such problems, then the code is really dead and will +be removed from the U-Boot source tree. The remainders rest in peace +in the imperishable depths of the git history. Please use the tools +git provides to read through this history. A common example would be: +$ git log -p --follow -- board/technexion/twister +to see the history and changes made to the Technexion "twister" board +from introduction to removal. diff --git a/roms/u-boot/doc/README.semihosting b/roms/u-boot/doc/README.semihosting new file mode 100644 index 000000000..c019999be --- /dev/null +++ b/roms/u-boot/doc/README.semihosting @@ -0,0 +1,38 @@ +SPDX-License-Identifier: GPL-2.0+ +/* + * Copyright 2014 Broadcom Corporation. + */ + +Semihosting is ARM's way of having a real or virtual target communicate +with a host or host debugger for basic operations such as file I/O, +console I/O, etc. Please see +http://infocenter.arm.com/help/index.jsp?topic=/com.arm.doc.dui0471c/Bgbjjgij.html for more information. + +For developing on armv8 virtual fastmodel platforms, semihosting is a +valuable tool since it allows access to image/configuration files before +eMMC or other NV media are available. + +There are two main ARM virtual Fixed Virtual Platform (FVP) models, +Versatile Express (VE) FVP and BASE FVP (See +http://www.arm.com/products/tools/models/fast-models/foundation-model.php) +The initial vexpress64 u-boot board created here runs on the VE virtual +platform using the license-free Foundation_v8 simulator. Fortunately, +the Foundation_v8 simulator also supports the BASE_FVP model which +companies can purchase licenses for and contain much more functionality. +So we can, in u-boot, run either model by either using the VE FVP (default), +or turning on CONFIG_BASE_FVP for the more full featured model. + +Rather than create a new armv8 board similar to armltd/vexpress64, add +semihosting calls to the existing one, enabled with CONFIG_SEMIHOSTING +and CONFIG_BASE_FVP both set. Also reuse the existing board config file +vexpress_aemv8a.h but differentiate the two models by the presence or +absence of CONFIG_BASE_FVP. This change is tested and works on both the +Foundation and Base fastmodel simulators. + +The semihosting code adds a command: + + smhload <image> <address> [env var] + +That will load an image from the host filesystem into RAM at the specified +address and optionally store the load end address in the specified +environment variable. diff --git a/roms/u-boot/doc/README.serial_multi b/roms/u-boot/doc/README.serial_multi new file mode 100644 index 000000000..c9049fd01 --- /dev/null +++ b/roms/u-boot/doc/README.serial_multi @@ -0,0 +1,54 @@ +The support for multiple serial interfaces as implemented is mainly +intended to allow for modem dial-in / dial-out while still being able +to use a serial console on a (different) serial port. + +MPC8XX Specific +=============== +At the moment, the ports must be split on a SMC and a SCC port on a +8xx processor; other configurations are not (yet) supported. + +Support for hardware handshake has not been implemented yet (but is +in the works). + +*) The default console depends on the keys pressed: + - SMC if keys not pressed (modem not enabled) + - SCC if keys pressed (modem enabled) + +*) The console can be switched to SCC by any of the following commands: + + setenv stdout serial_scc + setenv stdin serial_scc + setenv stderr serial_scc + +*) The console can be switched to SMC by any of the following commands: + + setenv stdout serial_smc + setenv stdin serial_smc + setenv stderr serial_smc + +*) If a file descriptor is set to "serial" then the current serial device +will be used which, in turn, can be switched by above commands. + +*) The baudrate is the same for all serial devices. But it can be switched +just after switching the console: + + setenv sout serial_scc; setenv baudrate 38400 + +After that press 'enter' at the SCC console. Note that baudrates <38400 +are not allowed on LWMON with watchdog enabled (see CONFIG_SYS_BAUDRATE_TABLE in +include/configs/lwmon.h). + + +PPC4XX Specific +=============== +*) The default console is UART0 + +*) The console can be switched to UART1 by any of the following commands: + setenv stdout serial1 + setenv stderr serial1 + setenv stdin serial1 + +*) The console can be switched to UART0 by any of the following commands: + setenv stdout serial0 + setenv stderr serial0 + setenv stdin serial0 diff --git a/roms/u-boot/doc/README.sha1 b/roms/u-boot/doc/README.sha1 new file mode 100644 index 000000000..f178f3726 --- /dev/null +++ b/roms/u-boot/doc/README.sha1 @@ -0,0 +1,58 @@ +SHA1 usage: +----------- + +In the U-Boot Image for the pcs440ep board is a SHA1 checksum integrated. +This SHA1 sum is used, to check, if the U-Boot Image in Flash is not +corrupted. + +The following command is available: + +=> help sha1 +sha1 address len [addr] calculate the SHA1 sum [save at addr] + -p calculate the SHA1 sum from the U-Boot image in flash and print + -c check the U-Boot image in flash + +"sha1 -p" + calculates and prints the SHA1 sum, from the Image stored in Flash + +"sha1 -c" + check, if the SHA1 sum from the Image stored in Flash is correct + + +It is possible to calculate a SHA1 checksum from a memoryrange with: + +"sha1 address len" + +If you want to store a new Image in Flash for the pcs440ep board, +which has no SHA1 sum, you can do the following: + +a) cp the new Image on a position in RAM (here 0x300000) + (for this example we use the Image from Flash, stored at 0xfffa0000 and + 0x60000 Bytes long) + +"cp.b fffa0000 300000 60000" + +b) Initialize the SHA1 sum in the Image with 0x00 + The SHA1 sum is stored in Flash at: + CONFIG_SYS_MONITOR_BASE + CONFIG_SYS_MONITOR_LEN + SHA1_SUM_POS + for the pcs440ep Flash: 0xfffa0000 + 0x60000 + -0x20 + = 0xffffffe0 + for the example in RAM: 0x300000 + 0x60000 + -0x20 + = 0x35ffe0 + + note: a SHA1 checksum is 20 bytes long. + +"mw.b 35ffe0 0 14" + +c) now calculate the SHA1 sum from the memoryrange and write + the calculated checksum at the right place: + +"sha1 300000 60000 35ffe0" + +Now you have a U-Boot-Image for the pcs440ep board with the correct SHA1 sum. + +If you do a "buildman -k pcs440ep" or a "make all" to get the U-Boot image, +which will be found in ../current/ipam390/ - the correct SHA1 sum will be +automagically included in the U-Boot image. + +Heiko Schocher, 11 Jul 2007 diff --git a/roms/u-boot/doc/README.silent b/roms/u-boot/doc/README.silent new file mode 100644 index 000000000..00288e03b --- /dev/null +++ b/roms/u-boot/doc/README.silent @@ -0,0 +1,28 @@ +The config option CONFIG_SILENT_CONSOLE can be used to quiet messages +on the console. If the option has been enabled, the output can be +silenced by setting the environment variable "silent". + +- CONFIG_SILENT_CONSOLE_UPDATE_ON_SET + When the "silent" variable is changed with env set, the change + will take effect immediately. + +- CONFIG_SILENT_CONSOLE_UPDATE_ON_RELOC + Some environments are not available until relocation (e.g. NAND) + so this will make the value in the flash env take effect at + relocation. + +The following actions are taken if "silent" is set at boot time: + + - Until the console devices have been initialized, output has to be + suppressed by testing for the flag "GD_FLG_SILENT" in "gd->flags". + + - When the console devices have been initialized, "stdout" and + "stderr" are set to "nulldev", so subsequent messages are + suppressed automatically. Make sure to enable "nulldev" by + enabling CONFIG_SYS_DEVICE_NULLDEV in your board defconfig file. + + - When booting a linux kernel, the "bootargs" are fixed up so that + the argument "console=" will be in the command line, no matter how + it was set in "bootargs" before. If you don't want the linux command + line to be affected, define CONFIG_SILENT_U_BOOT_ONLY in your board + config file as well, and this part of the feature will be disabled. diff --git a/roms/u-boot/doc/README.socfpga b/roms/u-boot/doc/README.socfpga new file mode 100644 index 000000000..4d73398eb --- /dev/null +++ b/roms/u-boot/doc/README.socfpga @@ -0,0 +1,178 @@ +---------------------------------------- +SOCFPGA Documentation for U-Boot and SPL +---------------------------------------- + +This README is about U-Boot and SPL support for Altera's ARM Cortex-A9MPCore +based SOCFPGA. To know more about the hardware itself, please refer to +www.altera.com. + + +socfpga_dw_mmc +-------------- + +Here are macro and detailed configuration required to enable DesignWare SDMMC +controller support within SOCFPGA + +#define CONFIG_SYS_MMC_MAX_BLK_COUNT 256 +-> Using smaller max blk cnt to avoid flooding the limited stack in OCRAM + +--------------------------------------------------------------------- +Cyclone 5 / Arria 5 generating the handoff header files for U-Boot SPL +--------------------------------------------------------------------- + +This text is assuming quartus 16.1, but newer versions will probably work just fine too; +verified with DE1_SOC_Linux_FB demo project (https://github.com/VCTLabs/DE1_SOC_Linux_FB). +Updated/working projects should build using either process below. + +Note: it *should* work from Quartus 14.0.200 onwards, however, the current vendor demo +projects must have the IP cores updated as shown below. + +Rebuilding your Quartus project +------------------------------- + +Choose one of the follwing methods, either command line or GUI. + +Using the command line +~~~~~~~~~~~~~~~~~~~~~~ + +First run the embedded command shell, using your path to the Quartus install: + + $ /path/to/intelFPGA/16.1/embedded/embedded_command_shell.sh + +Then (if necessary) update the IP cores in the project, generate HDL code, and +build the project: + + $ cd path/to/project/dir + $ qsys-generate soc_system.qsys --upgrade-ip-cores + $ qsys-generate soc_system.qsys --synthesis=[VERILOG|VHDL] + $ quartus_sh --flow compile <project name> + +Convert the resulting .sof file (SRAM object file) to .rbf file (Raw bit file): + + $ quartus_cpf -c <project_name>.sof soc_system.rbf + + +Generate BSP handoff files +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +You can run the bsp editor GUI below, or run the following command from the +project directory: + + $ /path/to/bsb/tools/bsp-create-settings --type spl --bsp-dir build \ + --preloader-settings-dir hps_isw_handoff/soc_system_hps_0/ \ + --settings build/settings.bsp + +You should use the bsp "build" directory above (ie, where the settings.bsp file is) +in the following u-boot command to update the board headers. Once these headers +are updated for a given project build, u-boot should be configured for the +project board (eg, de0-nano-sockit) and then build the normal spl build. + +Now you can skip the GUI section. + + +Using the Qsys GUI +~~~~~~~~~~~~~~~~~~ + +1. Navigate to your project directory +2. Run Quartus II +3. Open Project (Ctrl+J), select <project_name>.qpf +4. Run QSys [Tools->QSys] + 4.1 In the Open dialog, select '<project_name>.qsys' + 4.2 In the Open System dialog, wait until completion and press 'Close' + 4.3 In the Qsys window, click on 'Generate HDL...' in bottom right corner + 4.3.1 In the 'Generation' window, click 'Generate' + 4.3.2 In the 'Generate' dialog, wait until completion and click 'Close' + 4.4 In the QSys window, click 'Finish' + 4.4.1 In the 'Quartus II' pop up window, click 'OK' +5. Back in Quartus II main window, do the following + 5.1 Use Processing -> Start -> Start Analysis & Synthesis (Ctrl+K) + 5.2 Use Processing -> Start Compilation (Ctrl+L) + + ... this may take some time, have patience ... + +6. Start the embedded command shell as shown in the previous section + 6.1 Change directory to 'software/spl_bsp' + 6.2 Prepare BSP by launching the BSP editor from ECS + => bsp-editor + 6.3 In BSP editor + 6.3.1 Use File -> Open + 6.3.2 Select 'settings.bsp' file + 6.3.3 Click Generate + 6.3.4 Click Exit + + +Post handoff generation +~~~~~~~~~~~~~~~~~~~~~~~ + +Now that the handoff files are generated, U-Boot can be used to process +the handoff files generated by the bsp-editor. For this, please use the +following script from the u-boot source tree: + + $ ./arch/arm/mach-socfpga/qts-filter.sh \ + <soc_type> \ + <input_qts_dir> \ + <input_bsp_dir> \ + <output_dir> + +Process QTS-generated files into U-Boot compatible ones. + + soc_type - Type of SoC, either 'cyclone5' or 'arria5'. + input_qts_dir - Directory with compiled Quartus project + and containing the Quartus project file (QPF). + input_bsp_dir - Directory with generated bsp containing + the settings.bsp file. + output_dir - Directory to store the U-Boot compatible + headers. + +This will generate (or update) the following 4 files: + + iocsr_config.h + pinmux_config.h + pll_config.h + sdram_config.h + +These files should be copied into "qts" directory in the board directory +(see output argument of qts-filter.sh command above). + +Here is an example for the DE-0 Nano SoC after the above rebuild process: + + $ ll board/terasic/de0-nano-soc/qts/ + total 36 + -rw-r--r-- 1 sarnold sarnold 8826 Mar 21 18:11 iocsr_config.h + -rw-r--r-- 1 sarnold sarnold 4398 Mar 21 18:11 pinmux_config.h + -rw-r--r-- 1 sarnold sarnold 3190 Mar 21 18:11 pll_config.h + -rw-r--r-- 1 sarnold sarnold 9022 Mar 21 18:11 sdram_config.h + +Note: file sizes will differ slightly depending on the selected board. + +Now your board is ready for full mainline support including U-Boot SPL. +The Preloader will not be needed any more. + +---------------------------------------------------------- +Arria 10 generating the handoff header files for U-Boot SPL +---------------------------------------------------------- + +A header file for inclusion in a devicetree for Arria10 can be generated +by the qts-filter-a10.sh script directly from the hps_isw_handoff/hps.xml +file generated during the FPGA project compilation. The header contains +all PLL, clock, pinmux, and bridge configurations required. + +Please look at the socfpga_arria10_socdk_sdmmc-u-boot.dtsi for an example +that includes use of the generated handoff header. + +Devicetree header generation +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The qts-filter-a10.sh script can process the compile time genetated hps.xml +to create the appropriate devicetree header. + + + $ ./arch/arm/mach-socfpga/qts-filter-a10.sh \ + <hps_xml> \ + <output_file> + + hps_xml - hps_isw_handoff/hps.xml from Quartus project + output_file - Output filename and location for header file + +The script generates a single header file names <output_file> that should +be placed in arch/arm/dts. diff --git a/roms/u-boot/doc/README.spear b/roms/u-boot/doc/README.spear new file mode 100644 index 000000000..0789b3fd2 --- /dev/null +++ b/roms/u-boot/doc/README.spear @@ -0,0 +1,74 @@ + +SPEAr (Structured Processor Enhanced Architecture). + +SPEAr600 is also known as SPEArPlus and SPEAr300 is also known as SPEArBasic + +The SPEAr SoC family embeds a customizable logic that can be programmed +one-time by a customer at silicon mask level (i.e. not at runtime!). + +U-Boot supports four SoCs: SPEAr600, SPEAr3xx + +All 4 SoCs (SPEAr3xx and SPEAr600) share common peripherals. SPEAr300 and +SPEAr600 do not have EMI. + +1. ARM926ejs core based (sp600 has two cores, the 2nd handled only in Linux) +2. FastEthernet (sp600 has Gbit version, but same controller - GMAC) +3. USB Host +4. USB Device +5. NAND controller (FSMC) +6. Serial NOR ctrl +7. I2C +8. SPI +9. CLCD +10. others .. + +Everything is supported in Linux. +u-boot is currently not supporting all peripeharls (just a few as listed below). +1. USB Device +2. NAND controller (FSMC) +3. Serial Memory Interface +4. EMI (Parallel NOR interface) +4. I2C +5. UART + +Build options + make spear320_config + spear320 build with environment variables placed at default + location i.e. Serial NOR device + make spear320_pnor_config + This option generates a uboot image that supports emi controller + for CFI compliant parallel NOR flash. Environment variables are + placed in Parallel NOR device + make spear320_nand_config + spear320 build with environment variables placed in NAND device + make spear320_usbtty_config + spear320 build with usbtty terminal as default and environment + placed at default location + make spear320_usbtty_pnor_config + spear320 build with usbtty terminal as default and environment + placed in pnor device + make spear320_usbtty_nand_config + Build with usbtty terminal as default and environment placed in + NAND device + make spear300_config + make spear300_nand_config + make spear300_usbtty_config + make spear300_usbtty_nand_config + make spear310_config + make spear310_pnor_config + make spear310_nand_config + make spear310_usbtty_config + make spear310_usbtty_pnor_config + make spear310_usbtty_nand_config + make spear600_config + make spear600_nand_config + make spear600_usbtty_config + make spear600_usbtty_nand_config + +Mac id storage and retrieval in spear platforms + +Please read doc/README.enetaddr for the implementation guidelines for mac id +usage. Basically, environment has precedence over board specific storage. The +ethaddr beeing used for the network interface is always taken only from +environment variables. Although, we can check the mac id programmed in i2c +memory by using chip_config command diff --git a/roms/u-boot/doc/README.splashprepare b/roms/u-boot/doc/README.splashprepare new file mode 100644 index 000000000..3cb5b5aeb --- /dev/null +++ b/roms/u-boot/doc/README.splashprepare @@ -0,0 +1,34 @@ +--------------------------------------------------------------------- +Splash Screen +--------------------------------------------------------------------- +The splash_screen_prepare() function is a weak function defined in +common/splash.c. It is called as part of the splash screen display +sequence. It gives the board an opportunity to prepare the splash +image data before it is processed and sent to the frame buffer by +U-Boot. Define your own version to use this feature. + +CONFIG_SPLASH_SOURCE + +Use the splash_source.c library. This library provides facilities to declare +board specific splash image locations, routines for loading splash image from +supported locations, and a way of controlling the selected splash location +using the "splashsource" environment variable. + +splashsource works as follows: +- If splashsource is set to a supported location name as defined by board code, + use that splash location. +- If splashsource is undefined, use the first splash location as default. +- If splashsource is set to an unsupported value, do not load a splash screen. + +A splash source location can describe either storage with raw data, a storage +formatted with a file system or a FIT image. In case of a filesystem, the splash +screen data is loaded as a file. The name of the splash screen file can be +controlled with the environment variable "splashfile". + +To enable loading the splash image from a FIT image, CONFIG_FIT must be +enabled. The FIT image has to start at the 'offset' field address in the +selected splash location. The name of splash image within the FIT shall be +specified by the environment variable "splashfile". + +In case the environment variable "splashfile" is not defined the default name +'splash.bmp' will be used. diff --git a/roms/u-boot/doc/README.srio-pcie-boot-corenet b/roms/u-boot/doc/README.srio-pcie-boot-corenet new file mode 100644 index 000000000..2b1f76b8d --- /dev/null +++ b/roms/u-boot/doc/README.srio-pcie-boot-corenet @@ -0,0 +1,118 @@ +--------------------------------------- +SRIO and PCIE Boot on Corenet Platforms +--------------------------------------- + +For some PowerPC processors with SRIO or PCIE interface, boot location can be +configured to SRIO or PCIE by RCW. The processor booting from SRIO or PCIE can +do without flash for u-boot image, ucode and ENV. All the images can be fetched +from another processor's memory space by SRIO or PCIE link connected between +them. + +This document describes the processes based on an example implemented on P4080DS +platforms and a RCW example with boot from SRIO or PCIE configuration. + +Environment of the SRIO or PCIE boot: + a) Master and slave can be SOCs in one board or SOCs in separate boards. + b) They are connected with SRIO or PCIE links, whether 1x, 2x or 4x, and + directly or through switch system. + c) Only Master has NorFlash for booting, and all the Master's and Slave's + U-Boot images, UCodes will be stored in this flash. + d) Slave has its own EEPROM for RCW and PBI. + e) Slave's RCW should configure the SerDes for SRIO or PCIE boot port, set + the boot location to SRIO or PCIE, and holdoff all the cores. + + ----------- ----------- ----------- + | | | | | | + | | | | | | + | NorFlash|<----->| Master |SRIO or PCIE | Slave |<---->[EEPROM] + | | | |<===========>| | + | | | | | | + ----------- ----------- ----------- + +The example based on P4080DS platform: + Two P4080DS platforms can be used to implement the boot from SRIO or PCIE. + Their SRIO or PCIE ports 1 will be connected directly and will be used for + the boot from SRIO or PCIE. + + 1. Slave's RCW example for boot from SRIO port 1 and all cores in holdoff. + 00000000: aa55 aa55 010e 0100 0c58 0000 0000 0000 + 00000010: 1818 1818 0000 8888 7440 4000 0000 2000 + 00000020: f440 0000 0100 0000 0000 0000 0000 0000 + 00000030: 0000 0000 0083 0000 0000 0000 0000 0000 + 00000040: 0000 0000 0000 0000 0813 8040 063c 778f + + 2. Slave's RCW example for boot from PCIE port 1 and all cores in holdoff. + 00000000: aa55 aa55 010e 0100 0c58 0000 0000 0000 + 00000010: 1818 1818 0000 8888 1440 4000 0000 2000 + 00000020: f040 0000 0100 0000 0020 0000 0000 0000 + 00000030: 0000 0000 0083 0000 0000 0000 0000 0000 + 00000040: 0000 0000 0000 0000 0813 8040 547e ffc9 + + 3. Sequence in Step by Step. + a) Update RCW for slave with boot from SRIO or PCIE port 1 configuration. + b) Program slave's U-Boot image, UCode, and ENV parameters into master's + NorFlash. + c) Set environment variable "bootmaster" to "SRIO1" or "PCIE1" and save + environment for master. + setenv bootmaster SRIO1 + or + setenv bootmaster PCIE1 + saveenv + d) Restart up master and it will boot up normally from its NorFlash. + Then, it will finish necessary configurations for slave's boot from + SRIO or PCIE port 1. + e) Master will set inbound SRIO or PCIE windows covered slave's U-Boot + image stored in master's NorFlash. + f) Master will set an inbound SRIO or PCIE window covered slave's UCode + and ENV stored in master's NorFlash. + g) Master will set outbound SRIO or PCIE windows in order to configure + slave's registers for the core's releasing. + h) Since all cores of slave in holdoff, slave should be powered on before + all the above master's steps, and wait to be released by master. In the + startup phase of the slave from SRIO or PCIE, it will finish some + necessary configurations. + i) Slave will set a specific TLB entry for the boot process. + j) Slave will set a LAW entry with the TargetID SRIO or PCIE port 1 for + the boot. + k) Slave will set a specific TLB entry in order to fetch UCode and ENV + from master. + l) Slave will set a LAW entry with the TargetID SRIO or PCIE port 1 for + UCode and ENV. + +How to use this feature: + To use this feature, you need to focus those points. + + 1. Slave's RCW with SRIO or PCIE boot configurations, and all cores in holdoff + configurations. + Please refer to the examples given above. + + 2. U-Boot image's compilation. + For master, U-Boot image should be generated normally. + + For example, master U-Boot image used on P4080DS should be compiled with + + make P4080DS_config. + + For slave, U-Boot image should be generated specifically by + + make xxxx_SRIO_PCIE_BOOT_config. + + For example, slave U-Boot image used on P4080DS should be compiled with + + make P4080DS_SRIO_PCIE_BOOT_config. + + 3. Necessary modifications based on a specific environment. + For a specific environment, the addresses of the slave's U-Boot image, + UCode, ENV stored in master's NorFlash, and any other configurations + can be modified in the file: + include/configs/corenet_ds.h. + + 4. Set and save the environment variable "bootmaster" with "SRIO1", "SRIO2" + or "PCIE1", "PCIE2", "PCIE3" for master, and then restart it in order to + perform the role as a master for boot from SRIO or PCIE. + +NOTE: When the Slave's ENV parameters are stored in Master's NorFlash, + it can fetch them through PCIE or SRIO interface. But the ENV + parameters can not be modified by "saveenv" or other commands under + the Slave's u-boot environment, because the Slave can not erase, + write Master's NorFlash by PCIE or SRIO link. diff --git a/roms/u-boot/doc/README.standalone b/roms/u-boot/doc/README.standalone new file mode 100644 index 000000000..874ca2f7c --- /dev/null +++ b/roms/u-boot/doc/README.standalone @@ -0,0 +1,120 @@ +Design Notes on Exporting U-Boot Functions to Standalone Applications: +====================================================================== + +1. The functions are exported by U-Boot via a jump table. The jump + table is allocated and initialized in the jumptable_init() routine + (common/exports.c). Other routines may also modify the jump table, + however. The jump table can be accessed as the 'jt' field of the + 'global_data' structure. The struct members for the jump table are + defined in the <include/exports.h> header. E.g., to substitute the + malloc() and free() functions that will be available to standalone + applications, one should do the following: + + DECLARE_GLOBAL_DATA_PTR; + + gd->jt->malloc = my_malloc; + gd->jt->free = my_free; + + Note that the pointers to the functions are real function pointers + so the compiler can perform type checks on these assignments. + +2. The pointer to the jump table is passed to the application in a + machine-dependent way. PowerPC, ARM, MIPS, Blackfin and Nios II + architectures use a dedicated register to hold the pointer to the + 'global_data' structure: r2 on PowerPC, r9 on ARM, k0 on MIPS, + P3 on Blackfin and gp on Nios II. The x86 architecture does not + use such a register; instead, the pointer to the 'global_data' + structure is passed as 'argv[-1]' pointer. + + The application can access the 'global_data' structure in the same + way as U-Boot does: + + DECLARE_GLOBAL_DATA_PTR; + + printf("U-Boot relocation offset: %x\n", gd->reloc_off); + +3. The application should call the app_startup() function before any + call to the exported functions. Also, implementor of the + application may want to check the version of the ABI provided by + U-Boot. To facilitate this, a get_version() function is exported + that returns the ABI version of the running U-Boot. I.e., a + typical application startup may look like this: + + int my_app (int argc, char *const argv[]) + { + app_startup (argv); + if (get_version () != XF_VERSION) + return 1; + } + +4. The default load and start addresses of the applications are as + follows: + + Load address Start address + x86 0x00040000 0x00040000 + PowerPC 0x00040000 0x00040004 + ARM 0x0c100000 0x0c100000 + MIPS 0x80200000 0x80200000 + Blackfin 0x00001000 0x00001000 + NDS32 0x00300000 0x00300000 + Nios II 0x02000000 0x02000000 + RISC-V 0x00600000 0x00600000 + + For example, the "hello world" application may be loaded and + executed on a PowerPC board with the following commands: + + => tftp 0x40000 hello_world.bin + => go 0x40004 + +5. To export some additional function long foobar(int i,char c), the following steps + should be undertaken: + + - Append the following line at the end of the include/_exports.h + file: + + EXPORT_FUNC(foobar, long, foobar, int, char) + + Parameters to EXPORT_FUNC: + - the first parameter is the function that is exported (default implementation) + - the second parameter is the return value type + - the third parameter is the name of the member in struct jt_funcs + this is also the name that the standalone application will used. + the rest of the parameters are the function arguments + + - Add the prototype for this function to the include/exports.h + file: + + long foobar(int i, char c); + + Initialization with the default implementation is done in jumptable_init() + + You can override the default implementation using: + + gd->jt->foobar = another_foobar; + + The signature of another_foobar must then match the declaration of foobar. + + - Increase the XF_VERSION value by one in the include/exports.h + file + + - If you want to export a function which depends on a CONFIG_XXX + use 2 lines like this: + #ifdef CONFIG_FOOBAR + EXPORT_FUNC(foobar, long, foobar, int, char) + #else + EXPORT_FUNC(dummy, void, foobar, void) + #endif + + +6. The code for exporting the U-Boot functions to applications is + mostly machine-independent. The only places written in assembly + language are stub functions that perform the jump through the jump + table. That said, to port this code to a new architecture, the + only thing to be provided is the code in the examples/stubs.c + file. If this architecture, however, uses some uncommon method of + passing the 'global_data' pointer (like x86 does), one should add + the respective code to the app_startup() function in that file. + + Note that these functions may only use call-clobbered registers; + those registers that are used to pass the function's arguments, + the stack contents and the return address should be left intact. diff --git a/roms/u-boot/doc/README.t1040-l2switch b/roms/u-boot/doc/README.t1040-l2switch new file mode 100644 index 000000000..6f03de239 --- /dev/null +++ b/roms/u-boot/doc/README.t1040-l2switch @@ -0,0 +1,63 @@ +This file contains information for VSC9953, a Vitesse L2 Switch IP +which is integrated in the T1040/T1020 Freescale SoCs. + +About Device: +============= +VSC9953 is an 8-port Gigabit Ethernet switch supports the following features: + - 8192 MAC addresses + - Static Address provisioning + - Dynamic learning of MAC addresses and aging + - 4096 VLANs + - Independent and shared VLAN learning (IVL, SVL) + - Policing with storm control and MC/BC protection + - IPv4 and IPv6 multicast + - Jumbo frames (9.6 KB) + - Access Control List + - VLAN editing, translation and remarking + - RMON counters per port + +Switch interfaces: + - 8 Gigabit switch ports (ports 0 to 7) are external and are connected to external PHYs + - 2 switch ports (ports 8 and 9) of 2.5 G are connected (fixed links) + to FMan ports (FM1@DTSEC1 and FM1@DTSEC2) + +Commands Overview: +============= +Commands supported + - enable/disable a port or show its configuration (speed, duplexity, status, etc.) + - port statistics + - MAC learning + - add/remove FDB entries + - Port-based VLAN + - Private/Shared VLAN learning + - VLAN ingress filtering + - Port LAG + +Commands syntax +ethsw [port <port_no>] { enable | disable | show } - enable/disable a port; show a port's configuration +ethsw [port <port_no>] statistics { [help] | [clear] } - show an l2 switch port's statistics +ethsw [port <port_no>] learning { [help] | show | auto | disable } - enable/disable/show learning configuration on a port +ethsw [port <port_no>] [vlan <vid>] fdb { [help] | show | flush | { add | del } <mac> } - add/delete a mac entry in FDB; use show to see FDB entries; + if [vlan <vid>] is missing, VID 1 will be used +ethsw [port <port_no>] pvid { [help] | show | <pvid> } - set/show PVID (ingress and egress VLAN tagging) for a port +ethsw [port <port_no>] vlan { [help] | show | add <vid> | del <vid> } - add a VLAN to a port (VLAN members) +ethsw [port <port_no>] untagged { [help] | show | all | none | pvid } - set egress tagging mode for a port +ethsw [port <port_no>] egress tag { [help] | show | pvid | classified } - configure VID source for egress tag. + Tag's VID could be the frame's classified VID or the PVID of the port +ethsw vlan fdb { [help] | show | shared | private } - make VLAN learning shared or private +ethsw [port <port_no>] ingress filtering { [help] | show | enable | disable } - enable/disable VLAN ingress filtering on port +ethsw [port <port_no>] aggr { [help] | show | <lag_group_no> } - get/set LAG group for a port + +=> ethsw show + Port Status Link Speed Duplex + 0 enabled down 10 half + 1 enabled down 10 half + 2 enabled down 10 half + 3 enabled up 1000 full + 4 disabled down - half + 5 disabled down - half + 6 disabled down - half + 7 disabled down - half + 8 enabled up 2500 full + 9 enabled up 2500 full +=> diff --git a/roms/u-boot/doc/README.tee b/roms/u-boot/doc/README.tee new file mode 100644 index 000000000..79e7996a6 --- /dev/null +++ b/roms/u-boot/doc/README.tee @@ -0,0 +1,112 @@ +============= +TEE uclass +============= + +This document describes the TEE uclass in U-Boot + +A TEE (Trusted Execution Environment) is a trusted OS running in some +secure environment, for example, TrustZone on ARM CPUs, or a separate +secure co-processor etc. A TEE driver handles the details needed to +communicate with the TEE. + +This uclass deals with: + +- Registration of TEE drivers + +- Managing shared memory between U-Boot and the TEE + +- Providing a generic API to the TEE + +The TEE interface +================= + +include/tee.h defines the generic interface to a TEE. + +A client finds the TEE device via tee_find_device(). Other important functions +when interfacing with a TEE are: + +- tee_shm_alloc(), tee_shm_register() and tee_shm_free() to manage shared + memory objects often needed when communicating with the TEE. + +- tee_get_version() lets the client know which the capabilities of the TEE + device. + +- tee_open_session() opens a session to a Trusted Application + +- tee_invoke_func() invokes a function in a Trusted Application + +- tee_close_session() closes a session to a Trusted Application + +Much of the communication between clients and the TEE is opaque to the +driver. The main job for the driver is to receive requests from the +clients, forward them to the TEE and send back the results. + +OP-TEE driver +============= + +The OP-TEE driver handles OP-TEE [1] based TEEs. Currently it is only the ARM +TrustZone based OP-TEE solution that is supported. + +Lowest level of communication with OP-TEE builds on ARM SMC Calling +Convention (SMCCC) [2], which is the foundation for OP-TEE's SMC interface +[3] used internally by the driver. Stacked on top of that is OP-TEE Message +Protocol [4]. + +OP-TEE SMC interface provides the basic functions required by SMCCC and some +additional functions specific for OP-TEE. The most interesting functions are: + +- OPTEE_SMC_FUNCID_CALLS_UID (part of SMCCC) returns the version information + which is then returned by TEE_IOC_VERSION + +- OPTEE_SMC_CALL_GET_OS_UUID returns the particular OP-TEE implementation, used + to tell, for instance, a TrustZone OP-TEE apart from an OP-TEE running on a + separate secure co-processor. + +- OPTEE_SMC_CALL_WITH_ARG drives the OP-TEE message protocol + +- OPTEE_SMC_GET_SHM_CONFIG lets the driver and OP-TEE agree on which memory + range to used for shared memory between Linux and OP-TEE. + +The GlobalPlatform TEE Client API [5] is implemented on top of the generic +TEE API. + +Picture of the relationship between the different components in the +OP-TEE architecture: + + U-Boot Secure world + ~~~~~~ ~~~~~~~~~~~~ + +------------+ +-------------+ + | Client | | Trusted | + | | | Application | + +------------+ +-------------+ + /\ /\ + || || + \/ \/ + +------------+ +-------------+ + | TEE | | TEE Internal| + | uclass | | API | + +------------+ +-------------+ + | OP-TEE | | OP-TEE | + | driver | | Trusted OS | + +------------+-----------+-------------+ + | OP-TEE MSG | + | SMCCC (OPTEE_SMC_CALL_*) | + +--------------------------------------+ + +RPC (Remote Procedure Call) are requests from secure world to the driver. +An RPC is identified by a special range of SMCCC return values from +OPTEE_SMC_CALL_WITH_ARG. + +References +========== + +[1] https://github.com/OP-TEE/optee_os + +[2] http://infocenter.arm.com/help/topic/com.arm.doc.den0028a/index.html + +[3] drivers/tee/optee/optee_smc.h + +[4] drivers/tee/optee/optee_msg.h + +[5] http://www.globalplatform.org/specificationsdevice.asp look for + "TEE Client API Specification v1.0" and click download. diff --git a/roms/u-boot/doc/README.ti-secure b/roms/u-boot/doc/README.ti-secure new file mode 100644 index 000000000..27c0eaa77 --- /dev/null +++ b/roms/u-boot/doc/README.ti-secure @@ -0,0 +1,226 @@ +README on how boot images are created for secure TI devices + +CONFIG_TI_SECURE_DEVICE: +Secure TI devices require a boot image that is authenticated by ROM +code to function. Without this, even JTAG remains locked and the +device is essentially useless. In order to create a valid boot image for +a secure device from TI, the initial public software image must be signed +and combined with various headers, certificates, and other binary images. + +Information on the details on the complete boot image format can be obtained +from Texas Instruments. The tools used to generate boot images for secure +devices are part of a secure development package (SECDEV) that can be +downloaded from: + + http://www.ti.com/mysecuresoftware (login required) + +The secure development package is access controlled due to NDA and export +control restrictions. Access must be requested and granted by TI before the +package is viewable and downloadable. Contact TI, either online or by way +of a local TI representative, to request access. + +Booting of U-Boot SPL +===================== + + When CONFIG_TI_SECURE_DEVICE is set, the U-Boot SPL build process + requires the presence and use of these tools in order to create a + viable boot image. The build process will look for the environment + variable TI_SECURE_DEV_PKG, which should be the path of the installed + SECDEV package. If the TI_SECURE_DEV_PKG variable is not defined or + if it is defined but doesn't point to a valid SECDEV package, a + warning is issued during the build to indicate that a final secure + bootable image was not created. + + Within the SECDEV package exists an image creation script: + + ${TI_SECURE_DEV_PKG}/scripts/create-boot-image.sh + + This is called as part of the SPL/u-boot build process. As the secure + boot image formats and requirements differ between secure SOC from TI, + the purpose of this script is to abstract these details as much as + possible. + + The script is basically the only required interface to the TI SECDEV + package for creating a bootable SPL image for secure TI devices. + + Invoking the script for AM33xx Secure Devices + ============================================= + + create-boot-image.sh \ + <IMAGE_FLAG> <INPUT_FILE> <OUTPUT_FILE> <SPL_LOAD_ADDR> + + <IMAGE_FLAG> is a value that specifies the type of the image to + generate OR the action the image generation tool will take. Valid + values are: + SPI_X-LOADER - Generates an image for SPI flash (byte swapped) + X-LOADER - Generates an image for non-XIP flash + MLO - Generates an image for SD/MMC/eMMC media + 2ND - Generates an image for USB, UART and Ethernet + XIP_X-LOADER - Generates a single stage u-boot for NOR/QSPI XiP + + <INPUT_FILE> is the full path and filename of the public world boot + loaderbinary file (depending on the boot media, this is usually + either u-boot-spl.bin or u-boot.bin). + + <OUTPUT_FILE> is the full path and filename of the final secure + image. The output binary images should be used in place of the standard + non-secure binary images (see the platform-specific user's guides and + releases notes for how the non-secure images are typically used) + u-boot-spl_HS_SPI_X-LOADER - byte swapped boot image for SPI flash + u-boot-spl_HS_X-LOADER - boot image for NAND or SD/MMC/eMMC rawmode + u-boot-spl_HS_MLO - boot image for SD/MMC/eMMC media + u-boot-spl_HS_2ND - boot image for USB, UART and Ethernet + u-boot_HS_XIP_X-LOADER - boot image for NOR or QSPI Xip flash + + <SPL_LOAD_ADDR> is the address at which SOC ROM should load the + <INPUT_FILE> + + Invoking the script for AM43xx Secure Devices + ============================================= + + create-boot-image.sh \ + <IMAGE_FLAG> <INPUT_FILE> <OUTPUT_FILE> <SPL_LOAD_ADDR> + + <IMAGE_FLAG> is a value that specifies the type of the image to + generate OR the action the image generation tool will take. Valid + values are: + SPI_X-LOADER - Generates an image for SPI flash (byte + swapped) + XIP_X-LOADER - Generates a single stage u-boot for + NOR/QSPI XiP + ISSW - Generates an image for all other boot modes + + <INPUT_FILE> is the full path and filename of the public world boot + loaderbinary file (depending on the boot media, this is usually + either u-boot-spl.bin or u-boot.bin). + + <OUTPUT_FILE> is the full path and filename of the final secure + image. The output binary images should be used in place of the standard + non-secure binary images (see the platform-specific user's guides and + releases notes for how the non-secure images are typically used) + u-boot-spl_HS_SPI_X-LOADER - byte swapped boot image for SPI flash + u-boot_HS_XIP_X-LOADER - boot image for NOR or QSPI flash + u-boot-spl_HS_ISSW - boot image for all other boot media + + <SPL_LOAD_ADDR> is the address at which SOC ROM should load the + <INPUT_FILE> + + Invoking the script for DRA7xx/AM57xx Secure Devices + ==================================================== + + create-boot-image.sh \ + <IMAGE_TYPE> <INPUT_FILE> <OUTPUT_FILE> <SPL_LOAD_ADDR> + + <IMAGE_TYPE> is a value that specifies the type of the image to + generate OR the action the image generation tool will take. Valid + values are: + X-LOADER - Generates an image for NOR or QSPI boot modes + MLO - Generates an image for SD/MMC/eMMC boot modes + ULO - Generates an image for USB/UART peripheral boot modes + + <INPUT_FILE> is the full path and filename of the public world boot + loader binary file (for this platform, this is always u-boot-spl.bin). + + <OUTPUT_FILE> is the full path and filename of the final secure image. + The output binary images should be used in place of the standard + non-secure binary images (see the platform-specific user's guides + and releases notes for how the non-secure images are typically used) + u-boot-spl_HS_MLO - boot image for SD/MMC/eMMC. This image is + copied to a file named MLO, which is the name that + the device ROM bootloader requires for loading from + the FAT partition of an SD card (same as on + non-secure devices) + u-boot-spl_HS_ULO - boot image for USB/UART peripheral boot modes + u-boot-spl_HS_X-LOADER - boot image for all other flash memories + including QSPI and NOR flash + + <SPL_LOAD_ADDR> is the address at which SOC ROM should load the + <INPUT_FILE> + + Invoking the script for Keystone2 Secure Devices + ================================================ + + create-boot-image.sh \ + <UNUSED> <INPUT_FILE> <OUTPUT_FILE> <UNUSED> + + <UNUSED> is currently ignored and reserved for future use. + + <INPUT_FILE> is the full path and filename of the public world boot + loader binary file (only u-boot.bin is currently supported on + Keystone2 devices, u-boot-spl.bin is not currently supported). + + <OUTPUT_FILE> is the full path and filename of the final secure image. + The output binary images should be used in place of the standard + non-secure binary images (see the platform-specific user's guides + and releases notes for how the non-secure images are typically used) + u-boot_HS_MLO - signed and encrypted boot image that can be used to + boot from all media. Secure boot from SPI NOR flash is not + currently supported. + + Invoking the script for K3 Secure Devices + ========================================= + + The signing steps required to produce a bootable SPL image on secure + K3 TI devices are the same as those performed on non-secure devices. + The only difference is the key is not checked on non-secure devices so + a dummy key is used when building U-Boot for those devices. For secure + K3 TI devices simply use the real hardware key for your device. This + real key can be set with the Kconfig option "K3_KEY". The environment + variable TI_SECURE_DEV_PKG is also searched for real keys when the + build targets secure devices. + +Booting of Primary U-Boot (u-boot.img) +====================================== + + The SPL image is responsible for loading the next stage boot loader, + which is the main u-boot image. For secure TI devices, the SPL will + be authenticated, as described above, as part of the particular + device's ROM boot process. In order to continue the secure boot + process, the authenticated SPL must authenticate the main u-boot + image that it loads. + + The configurations for secure TI platforms are written to make the boot + process use the FIT image format for the u-boot.img (CONFIG_SPL_FRAMEWORK + and CONFIG_SPL_LOAD_FIT). With these configurations the binary + components that the SPL loads include a specific DTB image and u-boot + image. These DTB image may be one of many available to the boot + process. In order to secure these components so that they can be + authenticated by the SPL as they are loaded from the FIT image, the + build procedure for secure TI devices will secure these images before + they are integrated into the FIT image. When those images are extracted + from the FIT image at boot time, they are post-processed to verify that + they are still secure. The outlined security-related SPL post-processing + is enabled through the CONFIG_SPL_FIT_IMAGE_POST_PROCESS option which + must be enabled for the secure boot scheme to work. In order to allow + verifying proper operation of the secure boot chain in case of successful + authentication messages like "Authentication passed" are output by the + SPL to the console for each blob that got extracted from the FIT image. + + The exact details of the how the images are secured is handled by the + SECDEV package. Within the SECDEV package exists a script to process + an input binary image: + + ${TI_SECURE_DEV_PKG}/scripts/secure-binary-image.sh + + This is called as part of the u-boot build process. As the secure + image formats and requirements can differ between the various secure + SOCs from TI, this script in the SECDEV package abstracts these + details. This script is essentially the only required interface to the + TI SECDEV package for creating a u-boot.img image for secure TI + devices. + + The SPL/u-boot code contains calls to dedicated secure ROM functions + to perform the validation on the secured images. The details of the + interface to those functions is shown in the code. The summary + is that they are accessed by invoking an ARM secure monitor call to + the device's secure ROM (fixed read-only-memory that is secure and + only accessible when the ARM core is operating in the secure mode). + + Invoking the secure-binary-image script for Secure Devices + ========================================================== + + secure-binary-image.sh <INPUT_FILE> <OUTPUT_FILE> + + <INPUT_FILE> is the full path and filename of the input binary image + + <OUTPUT_FILE> is the full path and filename of the output secure image. diff --git a/roms/u-boot/doc/README.ubi b/roms/u-boot/doc/README.ubi new file mode 100644 index 000000000..c78a81795 --- /dev/null +++ b/roms/u-boot/doc/README.ubi @@ -0,0 +1,258 @@ +------------------- +UBI usage in U-Boot +------------------- + +UBI support in U-Boot is broken down into five separate commands. +The first is the ubi command, which has six subcommands: + +=> help ubi +ubi - ubi commands + +Usage: +ubi part [part] [offset] + - Show or set current partition (with optional VID header offset) +ubi info [l[ayout]] - Display volume and ubi layout information +ubi create[vol] volume [size] [type] - create volume name with size +ubi write[vol] address volume size - Write volume from address with size +ubi write.part address volume size [fullsize] + - Write part of a volume from address +ubi read[vol] address volume [size] - Read volume to address with size +ubi remove[vol] volume - Remove volume +[Legends] + volume: character name + size: specified in bytes + type: s[tatic] or d[ynamic] (default=dynamic) + + +The first command that is needed to be issues is "ubi part" to connect +one mtd partition to the UBI subsystem. This command will either create +a new UBI device on the requested MTD partition. Or it will attach a +previously created UBI device. The other UBI commands will only work +when such a UBI device is attached (via "ubi part"). Here an example: + +=> mtdparts + +device nor0 <1fc000000.nor_flash>, # parts = 6 + #: name size offset mask_flags + 0: kernel 0x00200000 0x00000000 0 + 1: dtb 0x00040000 0x00200000 0 + 2: root 0x00200000 0x00240000 0 + 3: user 0x01ac0000 0x00440000 0 + 4: env 0x00080000 0x01f00000 0 + 5: u-boot 0x00080000 0x01f80000 0 + +active partition: nor0,0 - (kernel) 0x00200000 @ 0x00000000 + +defaults: +mtdids : nor0=1fc000000.nor_flash +mtdparts: mtdparts=1fc000000.nor_flash:2m(kernel),256k(dtb),2m(root),27392k(user),512k(env),512k(u-boot) + +=> ubi part root +Creating 1 MTD partitions on "nor0": +0x000000240000-0x000000440000 : "mtd=2" +UBI: attaching mtd1 to ubi0 +UBI: physical eraseblock size: 262144 bytes (256 KiB) +UBI: logical eraseblock size: 262016 bytes +UBI: smallest flash I/O unit: 1 +UBI: VID header offset: 64 (aligned 64) +UBI: data offset: 128 +UBI: attached mtd1 to ubi0 +UBI: MTD device name: "mtd=2" +UBI: MTD device size: 2 MiB +UBI: number of good PEBs: 8 +UBI: number of bad PEBs: 0 +UBI: max. allowed volumes: 128 +UBI: wear-leveling threshold: 4096 +UBI: number of internal volumes: 1 +UBI: number of user volumes: 1 +UBI: available PEBs: 0 +UBI: total number of reserved PEBs: 8 +UBI: number of PEBs reserved for bad PEB handling: 0 +UBI: max/mean erase counter: 2/1 + + +Now that the UBI device is attached, this device can be modified +using the following commands: + +ubi info Display volume and ubi layout information +ubi createvol Create UBI volume on UBI device +ubi removevol Remove UBI volume from UBI device +ubi read Read data from UBI volume to memory +ubi write Write data from memory to UBI volume +ubi write.part Write data from memory to UBI volume, in parts + + +Here a few examples on the usage: + +=> ubi create testvol +Creating dynamic volume testvol of size 1048064 + +=> ubi info l +UBI: volume information dump: +UBI: vol_id 0 +UBI: reserved_pebs 4 +UBI: alignment 1 +UBI: data_pad 0 +UBI: vol_type 3 +UBI: name_len 7 +UBI: usable_leb_size 262016 +UBI: used_ebs 4 +UBI: used_bytes 1048064 +UBI: last_eb_bytes 262016 +UBI: corrupted 0 +UBI: upd_marker 0 +UBI: name testvol + +UBI: volume information dump: +UBI: vol_id 2147479551 +UBI: reserved_pebs 2 +UBI: alignment 1 +UBI: data_pad 0 +UBI: vol_type 3 +UBI: name_len 13 +UBI: usable_leb_size 262016 +UBI: used_ebs 2 +UBI: used_bytes 524032 +UBI: last_eb_bytes 2 +UBI: corrupted 0 +UBI: upd_marker 0 +UBI: name layout volume + +=> ubi info +UBI: MTD device name: "mtd=2" +UBI: MTD device size: 2 MiB +UBI: physical eraseblock size: 262144 bytes (256 KiB) +UBI: logical eraseblock size: 262016 bytes +UBI: number of good PEBs: 8 +UBI: number of bad PEBs: 0 +UBI: smallest flash I/O unit: 1 +UBI: VID header offset: 64 (aligned 64) +UBI: data offset: 128 +UBI: max. allowed volumes: 128 +UBI: wear-leveling threshold: 4096 +UBI: number of internal volumes: 1 +UBI: number of user volumes: 1 +UBI: available PEBs: 0 +UBI: total number of reserved PEBs: 8 +UBI: number of PEBs reserved for bad PEB handling: 0 +UBI: max/mean erase counter: 4/1 + +=> ubi write 800000 testvol 80000 +Volume "testvol" found at volume id 0 + +=> ubi read 900000 testvol 80000 +Volume testvol found at volume id 0 +read 524288 bytes from volume 0 to 900000(buf address) + +=> cmp.b 800000 900000 80000 +Total of 524288 bytes were the same + + +Next, the ubifsmount command allows you to access filesystems on the +UBI partition which has been attached with the ubi part command: + +=> help ubifsmount +ubifsmount - mount UBIFS volume + +Usage: +ubifsmount <volume-name> + - mount 'volume-name' volume + +For example: + +=> ubifsmount ubi0:recovery +UBIFS: mounted UBI device 0, volume 0, name "recovery" +UBIFS: mounted read-only +UBIFS: file system size: 46473216 bytes (45384 KiB, 44 MiB, 366 LEBs) +UBIFS: journal size: 6348800 bytes (6200 KiB, 6 MiB, 50 LEBs) +UBIFS: media format: w4/r0 (latest is w4/r0) +UBIFS: default compressor: LZO +UBIFS: reserved for root: 0 bytes (0 KiB) + +Note that unlike Linux, U-Boot can only have one active UBI partition +at a time, which can be referred to as ubi0, and must be supplied along +with the name of the filesystem you are mounting. + + +Once a UBI filesystem has been mounted, the ubifsls command allows you +to list the contents of a directory in the filesystem: + + +=> help ubifsls +ubifsls - list files in a directory + +Usage: +ubifsls [directory] + - list files in a 'directory' (default '/') + +For example: + +=> ubifsls + 17442 Thu Jan 01 02:57:38 1970 imx28-evk.dtb + 2998146 Thu Jan 01 02:57:43 1970 zImage + + +And the ubifsload command allows you to load a file from a UBI +filesystem: + + +=> help ubifsload +ubifsload - load file from an UBIFS filesystem + +Usage: +ubifsload <addr> <filename> [bytes] + - load file 'filename' to address 'addr' + +For example: + +=> ubifsload ${loadaddr} zImage +Loading file 'zImage' to addr 0x42000000 with size 2998146 (0x002dbf82)... +Done + + +Finally, you can unmount the UBI filesystem with the ubifsumount +command: + +=> help ubifsumount +ubifsumount - unmount UBIFS volume + +Usage: +ubifsumount - unmount current volume + +For example: + +=> ubifsumount +Unmounting UBIFS volume recovery! + + +Usage of the UBI CRC skip-check flag of static volumes: +------------------------------------------------------- +Some users of static UBI volumes implement their own integrity check, +thus making the volume CRC check done at open time useless. For +instance, this is the case when one use the ubiblock + dm-verity + +squashfs combination, where dm-verity already checks integrity of the +block device but this time at the block granularity instead of verifying +the whole volume. + +Skipping this test drastically improves the boot-time. + +U-Boot now supports the "skip_check" flag to optionally skip the CRC +check at open time. + +Usage: Case A - Upon UBI volume creation: +You can optionally add "--skipcheck" to the "ubi create" command: + +ubi create[vol] volume [size] [type] [id] [--skipcheck] + - create volume name with size ('-' for maximum available size) + +Usage: Case B - With an already existing UBI volume: +Use the "ubi skipcheck" command: + +ubi skipcheck volume on/off - Set or clear skip_check flag in volume header + +Example: +=> ubi skipcheck rootfs0 on +Setting skip_check on volume rootfs0 + +BTW: This saves approx. 10 seconds Linux bootup time on a MT7688 based +target with 128MiB of SPI NAND. diff --git a/roms/u-boot/doc/README.ubispl b/roms/u-boot/doc/README.ubispl new file mode 100644 index 000000000..ff008bc31 --- /dev/null +++ b/roms/u-boot/doc/README.ubispl @@ -0,0 +1,141 @@ +Lightweight UBI and UBI fastmap support + +# Copyright (C) Thomas Gleixner <tglx@linutronix.de> +# +# SPDX-License-Identifier: GPL 2.0+ BSD-3-Clause + +Scans the UBI information and loads the requested static volumes into +memory. + +Configuration Options: + + CONFIG_SPL_UBI + Enables the SPL UBI support + + CONFIG_SPL_UBI_MAX_VOL_LEBS + The maximum number of logical eraseblocks which a static volume + to load can contain. Used for sizing the scan data structure + + CONFIG_SPL_UBI_MAX_PEB_SIZE + The maximum physical erase block size. Either a compile time + constant or runtime detection. Used for sizing the scan data + structure + + CONFIG_SPL_UBI_MAX_PEBS + The maximum physical erase block count. Either a compile time + constant or runtime detection. Used for sizing the scan data + structure + + CONFIG_SPL_UBI_VOL_IDS + The maximum volume ids which can be loaded. Used for sizing the + scan data structure. + +Usage notes: + +In the board config file define for example: + +#define CONFIG_SPL_UBI +#define CONFIG_SPL_UBI_MAX_VOL_LEBS 256 +#define CONFIG_SPL_UBI_MAX_PEB_SIZE (256*1024) +#define CONFIG_SPL_UBI_MAX_PEBS 4096 +#define CONFIG_SPL_UBI_VOL_IDS 8 + +The size requirement is roughly as follows: + + 2k for the basic data structure + + CONFIG_SPL_UBI_VOL_IDS * CONFIG_SPL_UBI_MAX_VOL_LEBS * 8 + + CONFIG_SPL_UBI_MAX_PEBS * 64 + + CONFIG_SPL_UBI_MAX_PEB_SIZE * UBI_FM_MAX_BLOCKS + +The last one is big, but I really don't care in that stage. Real world +implementations only use the first couple of blocks, but the code +handles up to UBI_FM_MAX_BLOCKS. + +Given the above configuration example the requirement is about 5M +which is usually not a problem to reserve in the RAM along with the +other areas like the kernel/dts load address. + +So something like this will do the trick: + +#define SPL_FINFO_ADDR 0x80800000 +#define SPL_DTB_LOAD_ADDR 0x81800000 +#define SPL_KERNEL_LOAD_ADDR 0x82000000 + +In the board file, implement the following: + +static struct ubispl_load myvolumes[] = { + { + .vol_id = 0, /* kernel volume */ + .load_addr = (void *)SPL_KERNEL_LOAD_ADDR, + }, + { + .vol_id = 1, /* DT blob */ + .load_addr = (void *)SPL_DTB_LOAD_ADDR, + } +}; + +int spl_start_uboot(void) +{ + struct ubispl_info info; + + info.ubi = (struct ubi_scan_info *) SPL_FINFO_ADDR; + info.fastmap = 1; + info.read = nand_spl_read_flash; + +#if COMPILE_TIME_DEFINED + /* + * MY_NAND_NR_SPL_PEBS is the number of physical erase blocks + * in the FLASH which are reserved for the SPL. Think about + * mtd partitions: + * + * part_spl { .start = 0, .end = 4 } + * part_ubi { .start = 4, .end = NR_PEBS } + */ + info.peb_offset = MY_NAND_NR_SPL_PEBS; + info.peb_size = CONFIG_SYS_NAND_BLOCK_SIZE; + info.vid_offset = MY_NAND_UBI_VID_OFFS; + info.leb_start = MY_NAND_UBI_DATA_OFFS; + info.peb_count = MY_NAND_UBI_NUM_PEBS; +#else + get_flash_info(&flash_info); + info.peb_offset = MY_NAND_NR_SPL_PEBS; + info.peb_size = flash_info.peb_size; + + /* + * The VID and Data offset depend on the capability of the + * FLASH chip to do subpage writes. + * + * If the flash chip supports subpage writes, then the VID + * header starts at the second subpage. So for 2k pages size + * with 4 subpages the VID offset is 512. The DATA offset is 2k. + * + * If the flash chip does not support subpage writes then the + * VID offset is FLASH_PAGE_SIZE and the DATA offset + * 2 * FLASH_PAGE_SIZE + */ + info.vid_offset = flash_info.vid_offset; + info.leb_start = flash_info.data_offset; + + /* + * The flash reports the total number of erase blocks, so + * we need to subtract the number of blocks which are reserved + * for the SPL itself and not managed by UBI. + */ + info.peb_count = flash_info.peb_count - MY_NAND_NR_SPL_PEBS; +#endif + + ret = ubispl_load_volumes(&info, myvolumes, ARRAY_SIZE(myvolumes); + + .... + +} + +Note: you can load any payload that way. You can even load u-boot from +UBI, so the only non UBI managed FLASH area is the one which is +reserved for the SPL itself and read from the SoC ROM. + +And you can do fallback scenarios: + + if (ubispl_load_volumes(&info, volumes0, ARRAY_SIZE(volumes0))) + if (ubispl_load_volumes(&info, volumes1, ARRAY_SIZE(volumes1))) + ubispl_load_volumes(&info, vol_uboot, ARRAY_SIZE(vol_uboot)); diff --git a/roms/u-boot/doc/README.ublimage b/roms/u-boot/doc/README.ublimage new file mode 100644 index 000000000..ab25b2615 --- /dev/null +++ b/roms/u-boot/doc/README.ublimage @@ -0,0 +1,141 @@ +--------------------------------------------- +UBL image Boot Image generation using mkimage +--------------------------------------------- + +This document describes how to set up an U-Boot image that can be directly +booted by a DaVinci processor via NAND boot mode, using an UBL header, +but without need for UBL. + +For more details see section 11.2 "ARM ROM Boot Modes" of +http://focus.ti.com/lit/ug/sprufg5a/sprufg5a.pdf + +Command syntax: +-------------- +./tools/mkimage -l <u-boot_file> + to list the UBL image file details + +./tools/mkimage -T ublimage \ + -n <board specific configuration file> \ + -d <u-boot binary> <output image file> + +For example, for the davinci dm365evm board: +./tools/mkimage -n ./board/davinci/dm365evm/ublimage.cfg \ + -T ublimage \ + -d u-boot-nand.bin u-boot.ubl + +You can generate the image directly when you compile u-boot with: + +$ make u-boot.ubl + +The output image can be flashed into the NAND. + +Please check the DaVinci documentation for further details. + +Board specific configuration file specifications: +------------------------------------------------- +1. This file must present in the $(BOARDDIR) and the name should be + ublimage.cfg (since this is used in Makefile). +2. This file can have empty lines and lines starting with "#" as first + character to put comments. +3. This file can have configuration command lines as mentioned below, + any other information in this file is treated as invalid. + +Configuration command line syntax: +--------------------------------- +1. Each command line must have two strings, first one command or address + and second one data string +2. Following are the valid command strings and associated data strings:- + Command string data string + -------------- ----------- + MODE UBL special mode, on of: + safe + Example: + MODE safe + + ENTRY Entry point address for the user + bootloader (absolute address) = TEXT_BASE + nand_spl loader. + Example: + ENTRY 0x00000020 + + PAGES Number of pages (size of user bootloader + in number of pages) + Example: + PAGES 27 + + START_BLOCK Block number where user bootloader is present + Example: + START_BLOCK 5 + + START_PAGE Page number where user bootloader is present + (for RBL always 0) + Example: + START_PAGE 0 + +------------------------------------------------ + +Structure of the u-boot.ubl binary: + +compile steps: + +1) nand_spl code compile, with pad_to = (TEXT_BASE + + (CONFIG_SYS_NROF_PAGES_NAND_SPL * pagesize)) + Example: cam_enc_4xx pad_to = 0x20 + (6 * 0x800) = 0x3020 = 12320 + -> u-boot-spl-16k.bin + + !! TEXT_BASE = 0x20, as the RBL starts at 0x20 + +2) compile u-boot.bin ("normal" u-boot) + -> u-boot.bin + +3) create u-boot-nand.bin = u-boot-spl-16k.bin + u-boot.bin + +4) create u-boot.ubl, size = 1 page size NAND + create UBL header and paste it before u-boot.bin + +This steps are done automagically if you do a "make all" + +-> You get an u-boot.ubl binary, which you can flash + into your NAND. + +Structure of this binary (Example for the cam_enc_4xx board with a NAND +page size = 0x800): + +offset : 0x00000 | 0x800 | 0x3800 +content: UBL | nand_spl | u-boot code + Header | code | + +The NAND layout looks for example like this: + +(Example for the cam_enc_4xx board with a NAND page size = 0x800, block +size = 0x20000 and CONFIG_SYS_NROF_UBL_HEADER 5): + +offset : 0x80000 | 0xa0000 | 0xa3000 +content: UBL | nand_spl | u-boot code + Header | code | + ^ ^ + ^ 0xa0000 = CONFIG_SYS_NROF_UBL_HEADER * 0x20000 + ^ + 0x80000 = Block 4 * 0x20000 + +If the cpu starts in NAND boot mode, it checks the UBL descriptor +starting with block 1 (page 0). When a valid UBL signature is found, +the corresponding block number (from 1 to 24) is written to the last 32 +bits of ARM internal memory (0x7ffc-0x8000). This feature is provided +as a basic debug mechanism. If not found, it continues with block 2 +... last possible block is 24 + +If a valid UBL descriptor is found, the UBL descriptor is read and +processed. The descriptor gives the information required for loading +and control transfer to the nand_spl code. The nand_spl code is then +read and processed. + +Once the user-specified start-up conditions are set, the RBL copies the +nand_spl into ARM internal RAM, starting at address 0x0000: 0020. + ^^^^ + +The nand_spl code itself now does necessary intializations, and at least, +copies the u-boot code from NAND into RAM, and jumps to it ... + +------------------------------------------------ +Author: Heiko Schocher <hs@denx.de> diff --git a/roms/u-boot/doc/README.udp b/roms/u-boot/doc/README.udp new file mode 100644 index 000000000..da0725719 --- /dev/null +++ b/roms/u-boot/doc/README.udp @@ -0,0 +1,35 @@ +Udp framework + +The udp framework is build on top of network framework and is designed +to define new protocol or new command based on udp without modifying +the network framework. + +The udp framework define a function udp_loop that take as argument +a structure udp_ops (defined in include/net/udp.h) : + +struct udp_ops { + int (*prereq)(void *data); + int (*start)(void *data); + void *data; +}; + +The callback prereq define if all the requirements are +valid before running the network/udp loop. + +The callback start define the first step in the network/udp loop, +and it may also be used to configure a timemout and udp handler. + +The pointer data is used to store private data that +could be used by both callback. + +A simple example to use this framework: + +static struct udp_ops udp_ops = { + .prereq = wmp_prereq, + .start = wmp_start, + .data = NULL, +}; + +... + +err = udp_loop(&udp_ops); diff --git a/roms/u-boot/doc/README.unaligned-memory-access.txt b/roms/u-boot/doc/README.unaligned-memory-access.txt new file mode 100644 index 000000000..70a85f9cf --- /dev/null +++ b/roms/u-boot/doc/README.unaligned-memory-access.txt @@ -0,0 +1,240 @@ +Editors note: This document is _heavily_ cribbed from the Linux Kernel, with +really only the section about "Alignment vs. Networking" removed. + +UNALIGNED MEMORY ACCESSES +========================= + +Linux runs on a wide variety of architectures which have varying behaviour +when it comes to memory access. This document presents some details about +unaligned accesses, why you need to write code that doesn't cause them, +and how to write such code! + + +The definition of an unaligned access +===================================== + +Unaligned memory accesses occur when you try to read N bytes of data starting +from an address that is not evenly divisible by N (i.e. addr % N != 0). +For example, reading 4 bytes of data from address 0x10004 is fine, but +reading 4 bytes of data from address 0x10005 would be an unaligned memory +access. + +The above may seem a little vague, as memory access can happen in different +ways. The context here is at the machine code level: certain instructions read +or write a number of bytes to or from memory (e.g. movb, movw, movl in x86 +assembly). As will become clear, it is relatively easy to spot C statements +which will compile to multiple-byte memory access instructions, namely when +dealing with types such as u16, u32 and u64. + + +Natural alignment +================= + +The rule mentioned above forms what we refer to as natural alignment: +When accessing N bytes of memory, the base memory address must be evenly +divisible by N, i.e. addr % N == 0. + +When writing code, assume the target architecture has natural alignment +requirements. + +In reality, only a few architectures require natural alignment on all sizes +of memory access. However, we must consider ALL supported architectures; +writing code that satisfies natural alignment requirements is the easiest way +to achieve full portability. + + +Why unaligned access is bad +=========================== + +The effects of performing an unaligned memory access vary from architecture +to architecture. It would be easy to write a whole document on the differences +here; a summary of the common scenarios is presented below: + + - Some architectures are able to perform unaligned memory accesses + transparently, but there is usually a significant performance cost. + - Some architectures raise processor exceptions when unaligned accesses + happen. The exception handler is able to correct the unaligned access, + at significant cost to performance. + - Some architectures raise processor exceptions when unaligned accesses + happen, but the exceptions do not contain enough information for the + unaligned access to be corrected. + - Some architectures are not capable of unaligned memory access, but will + silently perform a different memory access to the one that was requested, + resulting in a subtle code bug that is hard to detect! + +It should be obvious from the above that if your code causes unaligned +memory accesses to happen, your code will not work correctly on certain +platforms and will cause performance problems on others. + + +Code that does not cause unaligned access +========================================= + +At first, the concepts above may seem a little hard to relate to actual +coding practice. After all, you don't have a great deal of control over +memory addresses of certain variables, etc. + +Fortunately things are not too complex, as in most cases, the compiler +ensures that things will work for you. For example, take the following +structure: + + struct foo { + u16 field1; + u32 field2; + u8 field3; + }; + +Let us assume that an instance of the above structure resides in memory +starting at address 0x10000. With a basic level of understanding, it would +not be unreasonable to expect that accessing field2 would cause an unaligned +access. You'd be expecting field2 to be located at offset 2 bytes into the +structure, i.e. address 0x10002, but that address is not evenly divisible +by 4 (remember, we're reading a 4 byte value here). + +Fortunately, the compiler understands the alignment constraints, so in the +above case it would insert 2 bytes of padding in between field1 and field2. +Therefore, for standard structure types you can always rely on the compiler +to pad structures so that accesses to fields are suitably aligned (assuming +you do not cast the field to a type of different length). + +Similarly, you can also rely on the compiler to align variables and function +parameters to a naturally aligned scheme, based on the size of the type of +the variable. + +At this point, it should be clear that accessing a single byte (u8 or char) +will never cause an unaligned access, because all memory addresses are evenly +divisible by one. + +On a related topic, with the above considerations in mind you may observe +that you could reorder the fields in the structure in order to place fields +where padding would otherwise be inserted, and hence reduce the overall +resident memory size of structure instances. The optimal layout of the +above example is: + + struct foo { + u32 field2; + u16 field1; + u8 field3; + }; + +For a natural alignment scheme, the compiler would only have to add a single +byte of padding at the end of the structure. This padding is added in order +to satisfy alignment constraints for arrays of these structures. + +Another point worth mentioning is the use of __attribute__((packed)) on a +structure type. This GCC-specific attribute tells the compiler never to +insert any padding within structures, useful when you want to use a C struct +to represent some data that comes in a fixed arrangement 'off the wire'. + +You might be inclined to believe that usage of this attribute can easily +lead to unaligned accesses when accessing fields that do not satisfy +architectural alignment requirements. However, again, the compiler is aware +of the alignment constraints and will generate extra instructions to perform +the memory access in a way that does not cause unaligned access. Of course, +the extra instructions obviously cause a loss in performance compared to the +non-packed case, so the packed attribute should only be used when avoiding +structure padding is of importance. + + +Code that causes unaligned access +================================= + +With the above in mind, let's move onto a real life example of a function +that can cause an unaligned memory access. The following function taken +from the Linux Kernel's include/linux/etherdevice.h is an optimized routine +to compare two ethernet MAC addresses for equality. + +bool ether_addr_equal(const u8 *addr1, const u8 *addr2) +{ +#ifdef CONFIG_HAVE_EFFICIENT_UNALIGNED_ACCESS + u32 fold = ((*(const u32 *)addr1) ^ (*(const u32 *)addr2)) | + ((*(const u16 *)(addr1 + 4)) ^ (*(const u16 *)(addr2 + 4))); + + return fold == 0; +#else + const u16 *a = (const u16 *)addr1; + const u16 *b = (const u16 *)addr2; + return ((a[0] ^ b[0]) | (a[1] ^ b[1]) | (a[2] ^ b[2])) == 0; +#endif +} + +In the above function, when the hardware has efficient unaligned access +capability, there is no issue with this code. But when the hardware isn't +able to access memory on arbitrary boundaries, the reference to a[0] causes +2 bytes (16 bits) to be read from memory starting at address addr1. + +Think about what would happen if addr1 was an odd address such as 0x10003. +(Hint: it'd be an unaligned access.) + +Despite the potential unaligned access problems with the above function, it +is included in the kernel anyway but is understood to only work normally on +16-bit-aligned addresses. It is up to the caller to ensure this alignment or +not use this function at all. This alignment-unsafe function is still useful +as it is a decent optimization for the cases when you can ensure alignment, +which is true almost all of the time in ethernet networking context. + + +Here is another example of some code that could cause unaligned accesses: + void myfunc(u8 *data, u32 value) + { + [...] + *((u32 *) data) = cpu_to_le32(value); + [...] + } + +This code will cause unaligned accesses every time the data parameter points +to an address that is not evenly divisible by 4. + +In summary, the 2 main scenarios where you may run into unaligned access +problems involve: + 1. Casting variables to types of different lengths + 2. Pointer arithmetic followed by access to at least 2 bytes of data + + +Avoiding unaligned accesses +=========================== + +The easiest way to avoid unaligned access is to use the get_unaligned() and +put_unaligned() macros provided by the <asm/unaligned.h> header file. + +Going back to an earlier example of code that potentially causes unaligned +access: + + void myfunc(u8 *data, u32 value) + { + [...] + *((u32 *) data) = cpu_to_le32(value); + [...] + } + +To avoid the unaligned memory access, you would rewrite it as follows: + + void myfunc(u8 *data, u32 value) + { + [...] + value = cpu_to_le32(value); + put_unaligned(value, (u32 *) data); + [...] + } + +The get_unaligned() macro works similarly. Assuming 'data' is a pointer to +memory and you wish to avoid unaligned access, its usage is as follows: + + u32 value = get_unaligned((u32 *) data); + +These macros work for memory accesses of any length (not just 32 bits as +in the examples above). Be aware that when compared to standard access of +aligned memory, using these macros to access unaligned memory can be costly in +terms of performance. + +If use of such macros is not convenient, another option is to use memcpy(), +where the source or destination (or both) are of type u8* or unsigned char*. +Due to the byte-wise nature of this operation, unaligned accesses are avoided. + +-- +In the Linux Kernel, +Authors: Daniel Drake <dsd@gentoo.org>, + Johannes Berg <johannes@sipsolutions.net> +With help from: Alan Cox, Avuton Olrich, Heikki Orsila, Jan Engelhardt, +Kyle McMartin, Kyle Moffett, Randy Dunlap, Robert Hancock, Uli Kunitz, +Vadim Lobanov diff --git a/roms/u-boot/doc/README.uniphier b/roms/u-boot/doc/README.uniphier new file mode 100644 index 000000000..badfacd66 --- /dev/null +++ b/roms/u-boot/doc/README.uniphier @@ -0,0 +1,462 @@ +U-Boot for UniPhier SoC family +============================== + + +Recommended toolchains +---------------------- + +The UniPhier platform is well tested with Linaro toolchains. +You can download pre-built toolchains from: + + http://www.linaro.org/downloads/ + + +Compile the source +------------------ + +The source can be configured and built with the following commands: + + $ make <defconfig> + $ make CROSS_COMPILE=<toolchain-prefix> DEVICE_TREE=<device-tree> + +The recommended <toolchain-prefix> is `arm-linux-gnueabihf-` for 32bit SoCs, +`aarch64-linux-gnu-` for 64bit SoCs, but you may wish to change it to use your +favorite compiler. + +The following tables show <defconfig> and <device-tree> for each board. + +32bit SoC boards: + + Board | <defconfig> | <device-tree> +---------------|-----------------------------|------------------------------ +LD4 reference | uniphier_ld4_sld8_defconfig | uniphier-ld4-ref (default) +sld8 reference | uniphier_ld4_sld8_defconfig | uniphier-sld8-def +Pro4 reference | uniphier_v7_defconfig | uniphier-pro4-ref +Pro4 Ace | uniphier_v7_defconfig | uniphier-pro4-ace +Pro4 Sanji | uniphier_v7_defconfig | uniphier-pro4-sanji +Pro5 4KBOX | uniphier_v7_defconfig | uniphier-pro5-4kbox +PXs2 Gentil | uniphier_v7_defconfig | uniphier-pxs2-gentil +PXs2 Vodka | uniphier_v7_defconfig | uniphier-pxs2-vodka (default) +LD6b reference | uniphier_v7_defconfig | uniphier-ld6b-ref + +64bit SoC boards: + + Board | <defconfig> | <device-tree> +---------------|-----------------------|---------------------------- +LD11 reference | uniphier_v8_defconfig | uniphier-ld11-ref +LD11 Global | uniphier_v8_defconfig | uniphier-ld11-global +LD20 reference | uniphier_v8_defconfig | uniphier-ld20-ref (default) +LD20 Global | uniphier_v8_defconfig | uniphier-ld20-global +PXs3 reference | uniphier_v8_defconfig | uniphier-pxs3-ref + +For example, to compile the source for PXs2 Vodka board, run the following: + + $ make uniphier_v7_defconfig + $ make CROSS_COMPILE=arm-linux-gnueabihf- DEVICE_TREE=uniphier-pxs2-vodka + +The device tree marked as (default) can be omitted. `uniphier-pxs2-vodka` is +the default device tree for the configuration `uniphier_v7_defconfig`, so the +following gives the same result. + + $ make uniphier_v7_defconfig + $ make CROSS_COMPILE=arm-linux-gnueabihf- + + +Booting 32bit SoC boards +------------------------ + +The build command will generate the following: +- u-boot.bin +- spl/u-boot.bin + +U-Boot can boot UniPhier 32bit SoC boards by itself. Flash the generated images +to the storage device (NAND or eMMC) on your board. + + - spl/u-boot-spl.bin at the offset address 0x00000000 + - u-boot.bin at the offset address 0x00020000 + +The `u-boot-with-spl.bin` is the concatenation of the two (with appropriate +padding), so you can also do: + + - u-boot-with-spl.bin at the offset address 0x00000000 + +If a TFTP server is available, the images can be easily updated. +Just copy the u-boot-spl.bin and u-boot.bin to the TFTP public directory, +and run the following command at the U-Boot command line: + +To update the images in NAND: + + => run nandupdate + +To update the images in eMMC: + + => run emmcupdate + + +Booting 64bit SoC boards +------------------------ + +The build command will generate the following: +- u-boot.bin + +However, U-Boot is not the first stage loader for UniPhier 64bit SoC boards. +U-Boot serves as a non-secure boot loader loaded by [ARM Trusted Firmware], +so you need to provide the `u-boot.bin` to the build command of ARM Trusted +Firmware. + +[ARM Trusted Firmware]: https://github.com/ARM-software/arm-trusted-firmware + + +Verified Boot +------------- + +U-Boot supports an image verification method called "Verified Boot". +This is a brief tutorial to utilize this feature for the UniPhier platform. +You will find details documents in the doc/uImage.FIT directory. + +Here, we take LD20 reference board for example, but it should work for any +other boards including 32 bit SoCs. + +1. Generate key to sign with + + $ mkdir keys + $ openssl genpkey -algorithm RSA -out keys/dev.key \ + -pkeyopt rsa_keygen_bits:2048 -pkeyopt rsa_keygen_pubexp:65537 + $ openssl req -batch -new -x509 -key keys/dev.key -out keys/dev.crt + +Two files "dev.key" and "dev.crt" will be created. The base name is arbitrary, +but need to match to the "key-name-hint" property described below. + +2. Describe FIT source + +You need to write an FIT (Flattened Image Tree) source file to describe the +structure of the image container. + +The following is an example for a simple usecase: + +---------------------------------------->8---------------------------------------- +/dts-v1/; + +/ { + description = "Kernel, DTB and Ramdisk for UniPhier LD20 Reference Board"; + #address-cells = <1>; + + images { + kernel { + description = "linux"; + data = /incbin/("PATH/TO/YOUR/LINUX/DIR/arch/arm64/boot/Image.gz"); + type = "kernel"; + arch = "arm64"; + os = "linux"; + compression = "gzip"; + load = <0x82080000>; + entry = <0x82080000>; + hash-1 { + algo = "sha256"; + }; + }; + + fdt-1 { + description = "fdt"; + data = /incbin/("PATH/TO/YOUR/LINUX/DIR/arch/arm64/boot/dts/socionext/uniphier-ld20-ref.dtb"); + type = "flat_dt"; + arch = "arm64"; + compression = "none"; + hash-1 { + algo = "sha256"; + }; + }; + + ramdisk { + description = "ramdisk"; + data = /incbin/("PATH/TO/YOUR/ROOTFS/DIR/rootfs.cpio"); + type = "ramdisk"; + arch = "arm64"; + os = "linux"; + compression = "none"; + hash-1 { + algo = "sha256"; + }; + }; + }; + + configurations { + default = "config-1"; + + config-1 { + description = "Configuration0"; + kernel = "kernel"; + fdt = "fdt-1"; + ramdisk = "ramdisk"; + signature-1 { + algo = "sha256,rsa2048"; + key-name-hint = "dev"; + sign-images = "kernel", "fdt", "ramdisk"; + }; + }; + }; +}; +---------------------------------------->8---------------------------------------- + +You need to change the three '/incbin/' lines, depending on the location of +your kernel image, device tree blob, and init ramdisk. The "load" and "entry" +properties also need to be adjusted if you want to change the physical placement +of the kernel. + +The "key-name-hint" must specify the key name you have created in the step 1. + +The FIT file name is arbitrary. Let's say you saved it into "fit.its". + +3. Compile U-Boot with FIT and signature enabled + +To use the Verified Boot, you need to enable the following two options: + CONFIG_FIT + CONFIG_FIT_SIGNATURE + +They are disabled by default for UniPhier defconfig files. So, you need to +tweak the configuration from "make menuconfig" or friends. + + $ make uniphier_v8_defconfig + $ make menuconfig + [ enable CONFIG_FIT and CONFIG_FIT_SIGNATURE ] + $ make CROSS_COMPILE=aarch64-linux-gnu- + +4. Build the image tree blob + +After building U-Boot, you will see tools/mkimage. With this tool, you can +create an image tree blob as follows: + + $ tools/mkimage -f fit.its -k keys -K dts/dt.dtb -r -F fitImage + +The -k option must specify the key directory you have created in step 1. + +A file "fitImage" will be created. This includes kernel, DTB, Init-ramdisk, +hash data for each of the three, and signature data. + +The public key needed for the run-time verification is stored in "dts/dt.dtb". + +5. Compile U-Boot again + +Since the "dt.dtb" has been updated in step 4, you need to re-compile the +U-Boot. + + $ make CROSS_COMPILE=aarch64-linux-gnu- + +The re-compiled "u-boot.bin" is appended with DTB that contains the public key. + +6. Flash the image + +Flash the "fitImage" to a storage device (NAND, eMMC, or whatever) on your +board. + +Please note the "u-boot.bin" must be signed, and verified by someone when it is +loaded. For ARMv8 SoCs, the "someone" is generally ARM Trusted Firmware BL2. +ARM Trusted Firmware supports an image authentication mechanism called Trusted +Board Boot (TBB). The verification process must be chained from the moment of +the system reset. If the Chain of Trust has a breakage somewhere, the verified +boot process is entirely pointless. + +7. Boot verified kernel + +Load the fitImage to memory and run the following from the U-Boot command line. + + > bootm <addr> + +Here, <addr> is the base address of the fitImage. + +If it is successful, you will see messages like follows: + +---------------------------------------->8---------------------------------------- +## Loading kernel from FIT Image at 84100000 ... + Using 'config-1' configuration + Verifying Hash Integrity ... sha256,rsa2048:dev+ OK + Trying 'kernel' kernel subimage + Description: linux + Created: 2017-10-20 14:32:29 UTC + Type: Kernel Image + Compression: gzip compressed + Data Start: 0x841000c8 + Data Size: 6957818 Bytes = 6.6 MiB + Architecture: AArch64 + OS: Linux + Load Address: 0x82080000 + Entry Point: 0x82080000 + Hash algo: sha256 + Hash value: 82a37b7f11ae55f4e07aa25bf77e4067cb9dc1014d52d6cd4d588f92eee3aaad + Verifying Hash Integrity ... sha256+ OK +## Loading ramdisk from FIT Image at 84100000 ... + Using 'config-1' configuration + Trying 'ramdisk' ramdisk subimage + Description: ramdisk + Created: 2017-10-20 14:32:29 UTC + Type: RAMDisk Image + Compression: uncompressed + Data Start: 0x847a5cc0 + Data Size: 5264365 Bytes = 5 MiB + Architecture: AArch64 + OS: Linux + Load Address: unavailable + Entry Point: unavailable + Hash algo: sha256 + Hash value: 44980a2874154a2e31ed59222c9f8ea968867637f35c81e4107a984de7014deb + Verifying Hash Integrity ... sha256+ OK +## Loading fdt from FIT Image at 84100000 ... + Using 'config-1' configuration + Trying 'fdt-1' fdt subimage + Description: fdt + Created: 2017-10-20 14:32:29 UTC + Type: Flat Device Tree + Compression: uncompressed + Data Start: 0x847a2cb0 + Data Size: 12111 Bytes = 11.8 KiB + Architecture: AArch64 + Hash algo: sha256 + Hash value: c517099db537f6d325e6be46b25c871a41331ad5af0283883fd29d40bfc14e1d + Verifying Hash Integrity ... sha256+ OK + Booting using the fdt blob at 0x847a2cb0 + Uncompressing Kernel Image ... OK + reserving fdt memory region: addr=80000000 size=2000000 + Loading Device Tree to 000000009fffa000, end 000000009fffff4e ... OK + +Starting kernel ... +---------------------------------------->8---------------------------------------- + +Please pay attention to the lines that start with "Verifying Hash Integrity". + +"Verifying Hash Integrity ... sha256,rsa2048:dev+ OK" means the signature check +passed. + +"Verifying Hash Integrity ... sha256+ OK" (3 times) means the hash check passed +for kernel, DTB, and Init ramdisk. + +If they are not displayed, the Verified Boot is not working. + + +Deployment for Distro Boot +-------------------------- + +UniPhier SoC family boot the kernel in a generic manner as described in +doc/README.distro . + +To boot the kernel, you need to deploy necesssary components to a file +system on one of your block devices (eMMC, NAND, USB drive, etc.). + +The components depend on the kernel image format. + +[1] Bare images + + - kernel + - init ramdisk + - device tree blob + - boot configuration file (extlinux.conf) + +Here is an exmple of the configuration file. + +-------------------->8-------------------- +menu title UniPhier Boot Options. + +timeout 50 +default UniPhier + +label UniPhier + kernel ../Image + initrd ../rootfs.cpio.gz + fdtdir .. +-------------------->8-------------------- + +Then, write 'Image', 'rootfs.cpio.gz', 'uniphier-ld20-ref.dtb' (DTB depends on +your board), and 'extlinux/extlinux.conf' to the file system. + +[2] FIT + + - FIT blob + - boot configuration file (extlinux.conf) + +-------------------->8-------------------- +menu title UniPhier Boot Options. + +timeout 50 +default UniPhier + +label UniPhier + kernel ../fitImage +-------------------->8-------------------- + +Since the init ramdisk and DTB are contained in the FIT blob, +you do not need to describe them in the configuration file. +Write 'fitImage' and 'extlinux/extlinux.conf' to the file system. + + +UniPhier specific commands +-------------------------- + + - pinmon (enabled by CONFIG_CMD_PINMON) + shows the boot mode pins that has been latched at the power-on reset + + - ddrphy (enabled by CONFIG_CMD_DDRPHY_DUMP) + shows the DDR PHY parameters set by the PHY training + + - ddrmphy (enabled by CONFIG_CMD_DDRMPHY_DUMP) + shows the DDR Multi PHY parameters set by the PHY training + + +Supported devices +----------------- + + - UART (on-chip) + - NAND + - SD/eMMC + - USB 2.0 (EHCI) + - USB 3.0 (xHCI) + - GPIO + - LAN (on-board SMSC9118) + - I2C + - EEPROM (connected to the on-board I2C bus) + - Support card (SRAM, NOR flash, some peripherals) + + +Micro Support Card +------------------ + +The recommended bit switch settings are as follows: + + SW2 OFF(1)/ON(0) Description + ------------------------------------------ + bit 1 <---- BKSZ[0] + bit 2 ----> BKSZ[1] + bit 3 <---- SoC Bus Width 16/32 + bit 4 <---- SERIAL_SEL[0] + bit 5 ----> SERIAL_SEL[1] + bit 6 ----> BOOTSWAP_EN + bit 7 <---- CS1/CS5 + bit 8 <---- SOC_SERIAL_DISABLE + + SW8 OFF(1)/ON(0) Description + ------------------------------------------ + bit 1 <---- CS1_SPLIT + bit 2 <---- CASE9_ON + bit 3 <---- CASE10_ON + bit 4 Don't Care Reserve + bit 5 Don't Care Reserve + bit 6 Don't Care Reserve + bit 7 ----> BURST_EN + bit 8 ----> FLASHBUS32_16 + +The BKSZ[1:0] specifies the address range of memory slot and peripherals +as follows: + + BKSZ Description RAM slot Peripherals + -------------------------------------------------------------------- + 0b00 15MB RAM / 1MB Peri 00000000-00efffff 00f00000-00ffffff + 0b01 31MB RAM / 1MB Peri 00000000-01efffff 01f00000-01ffffff + 0b10 64MB RAM / 1MB Peri 00000000-03efffff 03f00000-03ffffff + 0b11 127MB RAM / 1MB Peri 00000000-07efffff 07f00000-07ffffff + +Set BSKZ[1:0] to 0b01 for U-Boot. +This mode is the most handy because EA[24] is always supported by the save pin +mode of the system bus. On the other hand, EA[25] is not supported for some +newer SoCs. Even if it is, EA[25] is not connected on most of the boards. + +-- +Masahiro Yamada <yamada.masahiro@socionext.com> +Oct. 2017 diff --git a/roms/u-boot/doc/README.update b/roms/u-boot/doc/README.update new file mode 100644 index 000000000..bf4379279 --- /dev/null +++ b/roms/u-boot/doc/README.update @@ -0,0 +1,97 @@ +Automatic software update from a TFTP server +============================================ + +Overview +-------- + +This feature allows to automatically store software updates present on a TFTP +server in NOR Flash. In more detail: a TFTP transfer of a file given in +environment variable 'updatefile' from server 'serverip' is attempted during +boot. The update file should be a FIT file, and can contain one or more +updates. Each update in the update file has an address in NOR Flash where it +should be placed, updates are also protected with a SHA-1 checksum. If the +TFTP transfer is successful, the hash of each update is verified, and if the +verification is positive, the update is stored in Flash. + +The auto-update feature is enabled by the CONFIG_UPDATE_TFTP macro: + +#define CONFIG_UPDATE_TFTP 1 + + +Note that when enabling auto-update, Flash support must be turned on. Also, +one must enable FIT and LIBFDT support: + +#define CONFIG_FIT 1 +#define CONFIG_OF_LIBFDT 1 + +The auto-update feature uses the following configuration knobs: + +- CONFIG_UPDATE_LOAD_ADDR + + Normally, TFTP transfer of the update file is done to the address specified + in environment variable 'loadaddr'. If this variable is not present, the + transfer is made to the address given in CONFIG_UPDATE_LOAD_ADDR (0x100000 + by default). + +- CONFIG_UPDATE_TFTP_CNT_MAX + CONFIG_UPDATE_TFTP_MSEC_MAX + + These knobs control the timeouts during initial connection to the TFTP + server. Since a transfer is attempted during each boot, it is undesirable to + have a long delay when a TFTP server is not present. + CONFIG_UPDATE_TFTP_MSEC_MAX specifies the number of milliseconds to wait for + the server to respond to initial connection, and CONFIG_UPDATE_TFTP_CNT_MAX + gives the number of such connection retries. CONFIG_UPDATE_TFTP_CNT_MAX must + be non-negative and is 0 by default, CONFIG_UPDATE_TFTP_MSEC_MAX must be + positive and is 100 by default. + +Since the update file is in FIT format, it is created from an *.its file using +the mkimage tool. dtc tool with support for binary includes, e.g. in version +1.2.0 or later, must also be available on the system where the update file is +to be prepared. Refer to the doc/uImage.FIT/ directory for more details on FIT +images. + + +Example .its files +------------------ + +- doc/uImage.FIT/update_uboot.its + + A simple example that can be used to create an update file for automatically + replacing U-Boot image on a system. + + Assuming that an U-Boot image u-boot.bin is present in the current working + directory, and that the address given in the 'load' property in the + 'update_uboot.its' file is where the U-Boot is stored in Flash, the + following command will create the actual update file 'update_uboot.itb': + + mkimage -f update_uboot.its update_uboot.itb + + Place 'update_uboot.itb' on a TFTP server, for example as + '/tftpboot/update_uboot.itb', and set the 'updatefile' variable + appropriately, for example in the U-Boot prompt: + + setenv updatefile /tftpboot/update_uboot.itb + saveenv + + Now, when the system boots up and the update TFTP server specified in the + 'serverip' environment variable is accessible, the new U-Boot image will be + automatically stored in Flash. + + NOTE: do make sure that the 'u-boot.bin' image used to create the update + file is a good, working image. Also make sure that the address in Flash + where the update will be placed is correct. Making mistake here and + attempting the auto-update can render the system unusable. + +- doc/uImage.FIT/update3.its + + An example containing three updates. It can be used to update Linux kernel, + ramdisk and FDT blob stored in Flash. The procedure for preparing the update + file is similar to the example above. + +TFTP update via DFU +------------------- + +- It is now possible to update firmware (bootloader, kernel, rootfs, etc.) via + TFTP by using DFU (Device Firmware Upgrade). More information can be found in + ./doc/README.dfutftp documentation entry. diff --git a/roms/u-boot/doc/README.usb b/roms/u-boot/doc/README.usb new file mode 100644 index 000000000..05c62c341 --- /dev/null +++ b/roms/u-boot/doc/README.usb @@ -0,0 +1,231 @@ +SPDX-License-Identifier: GPL-2.0+ +/* + * (C) Copyright 2001 + * Denis Peter, MPL AG Switzerland + */ + +USB Support +=========== + +The USB support is implemented on the base of the UHCI Host +controller. + +Currently supported are USB Hubs, USB Keyboards, USB Floppys, USB +flash sticks and USB network adaptors. +Tested with a TEAC Floppy TEAC FD-05PUB and Chicony KU-8933 Keyboard. + +How it works: +------------- + +The USB (at least the USB UHCI) needs a frame list (4k), transfer +descripor and queue headers which are all located in the main memory. +The UHCI allocates every milisecond the PCI bus and reads the current +frame pointer. This may cause to crash the OS during boot. So the USB +_MUST_ be stopped during OS boot. This is the reason, why the USB is +NOT automatically started during start-up. If someone needs the USB +he has to start it and should therefore be aware that he had to stop +it before booting the OS. + +For USB keyboards this can be done by a script which is automatically +started after the U-Boot is up and running. To boot an OS with a an +USB keyboard another script is necessary, which first disables the +USB and then executes the boot command. If the boot command fails, +the script can reenable the USB kbd. + +Common USB Commands: +- usb start: +- usb reset: (re)starts the USB. All USB devices will be + initialized and a device tree is build for them. +- usb tree: shows all USB devices in a tree like display +- usb info [dev]: shows all USB infos of the device dev, or of all + the devices +- usb stop [f]: stops the USB. If f==1 the USB will also stop if + an USB keyboard is assigned as stdin. The stdin + is then switched to serial input. +Storage USB Commands: +- usb scan: scans the USB for storage devices.The USB must be + running for this command (usb start) +- usb device [dev]: show or set current USB storage device +- usb part [dev]: print partition table of one or all USB storage + devices +- usb read addr blk# cnt: + read `cnt' blocks starting at block `blk#'to + memory address `addr' +- usbboot addr dev:part: + boot from USB device + +Config Switches: +---------------- +CONFIG_CMD_USB enables basic USB support and the usb command +CONFIG_USB_UHCI defines the lowlevel part.A lowlevel part must be defined + if using CONFIG_CMD_USB +CONFIG_USB_KEYBOARD enables the USB Keyboard +CONFIG_USB_STORAGE enables the USB storage devices +CONFIG_USB_HOST_ETHER enables USB ethernet adapter support + + +USB Host Networking +=================== + +If you have a supported USB Ethernet adapter you can use it in U-Boot +to obtain an IP address and load a kernel from a network server. + +Note: USB Host Networking is not the same as making your board act as a USB +client. In that case your board is pretending to be an Ethernet adapter +and will appear as a network interface to an attached computer. In that +case the connection is via a USB cable with the computer acting as the host. + +With USB Host Networking, your board is the USB host. It controls the +Ethernet adapter to which it is directly connected and the connection to +the outside world is your adapter's Ethernet cable. Your board becomes an +independent network device, able to connect and perform network operations +independently of your computer. + + +Device support +-------------- + +Currently supported devices are listed in the drivers according to +their vendor and product IDs. You can check your device by connecting it +to a Linux machine and typing 'lsusb'. The drivers are in +drivers/usb/eth. + +For example this lsusb output line shows a device with Vendor ID 0x0x95 +and product ID 0x7720: + +Bus 002 Device 010: ID 0b95:7720 ASIX Electronics Corp. AX88772 + +If you look at drivers/usb/eth/asix.c you will see this line within the +supported device list, so we know this adapter is supported. + + { 0x0b95, 0x7720 }, /* Trendnet TU2-ET100 V3.0R */ + +If your adapter is not listed there is a still a chance that it will +work. Try looking up the manufacturer of the chip inside your adapter. +or take the adapter apart and look for chip markings. Then add a line +for your vendor/product ID into the table of the appropriate driver, +build U-Boot and see if it works. If not then there might be differences +between the chip in your adapter and the driver. You could try to get a +datasheet for your device and add support for it to U-Boot. This is not +particularly difficult - you only need to provide support for four basic +functions: init, halt, send and recv. + + +Enabling USB Host Networking +---------------------------- + +The normal U-Boot commands are used with USB networking, but you must +start USB first. For example: + +usb start +setenv bootfile /tftpboot/uImage +bootp + + +To enable USB Host Ethernet in U-Boot, your platform must of course +support USB with CONFIG_CMD_USB enabled and working. You will need to +add some config settings to your board config: + +CONFIG_CMD_USB=y /* the 'usb' interactive command */ +CONFIG_USB_HOST_ETHER=y /* Enable USB Ethernet adapters */ + +and one or more of the following for individual adapter hardware: + +CONFIG_USB_ETHER_ASIX=y +CONFIG_USB_ETHER_ASIX88179=y +CONFIG_USB_ETHER_LAN75XX=y +CONFIG_USB_ETHER_LAN78XX=y +CONFIG_USB_ETHER_MCS7830=y +CONFIG_USB_ETHER_RTL8152=y +CONFIG_USB_ETHER_SMSC95XX=y + +As with built-in networking, you will also want to enable some network +commands, for example: + +CONFIG_CMD_NET=y +CONFIG_CMD_PING=y +CONFIG_CMD_DHCP=y + +and some bootp options, which tell your board to obtain its subnet, +gateway IP, host name and boot path from the bootp/dhcp server. These +settings should start you off: + +#define CONFIG_BOOTP_SUBNETMASK +#define CONFIG_BOOTP_GATEWAY +#define CONFIG_BOOTP_HOSTNAME +#define CONFIG_BOOTP_BOOTPATH + +You can also set the default IP address of your board and the server +as well as the default file to load when a 'bootp' command is issued. +However note that encoding these individual network settings into a +common exectuable is discouraged, as it leads to potential conflicts, +and all the parameters can either get stored in the board's external +environment, or get obtained from the bootp server if not set. + +#define CONFIG_IPADDR 10.0.0.2 (replace with your value) +#define CONFIG_SERVERIP 10.0.0.1 (replace with your value) +#define CONFIG_BOOTFILE "uImage" + + +The 'usb start' command should identify the adapter something like this: + +CrOS> usb start +(Re)start USB... +USB EHCI 1.00 +scanning bus for devices... 3 USB Device(s) found + scanning bus for storage devices... 0 Storage Device(s) found + scanning bus for ethernet devices... 1 Ethernet Device(s) found +CrOS> print ethact +ethact=asx0 + +You can see that it found an ethernet device and we can print out the +device name (asx0 in this case). + +Then 'bootp' or 'dhcp' should use it to obtain an IP address from DHCP, +perhaps something like this: + +CrOS> bootp +Waiting for Ethernet connection... done. +BOOTP broadcast 1 +BOOTP broadcast 2 +DHCP client bound to address 172.22.73.81 +Using asx0 device +TFTP from server 172.22.72.144; our IP address is 172.22.73.81 +Filename '/tftpboot/uImage-sjg-seaboard-261347'. +Load address: 0x40c000 +Loading: ################################################################# + ################################################################# + ################################################################# + ################################################ +done +Bytes transferred = 3557464 (364858 hex) +CrOS> + + +Another way of doing this is to issue a tftp command, which will cause the +bootp to happen automatically. + + +MAC Addresses +------------- + +Most Ethernet dongles have a built-in MAC address which is unique in the +world. This is important so that devices on the network can be +distinguised from each other. MAC address conflicts are evil and +generally result in strange and eratic behaviour. + +Some boards have USB Ethernet chips on-board, and these sometimes do not +have an assigned MAC address. In this case it is up to you to assign +one which is unique. You should obtain a valid MAC address from a range +assigned to you before you ship the product. + +Built-in Ethernet adapters support setting the MAC address by means of +an ethaddr environment variable for each interface (ethaddr, eth1addr, +eth2addr). There is similar support on the USB network side, using the +names usbethaddr, usbeth1addr, etc. They are kept separate since we +don't want a USB device taking the MAC address of a built-in device or +vice versa. + +So if your USB Ethernet chip doesn't have a MAC address available then +you must set usbethaddr to a suitable MAC address. At the time of +writing this functionality is only supported by the SMSC driver. diff --git a/roms/u-boot/doc/README.vf610 b/roms/u-boot/doc/README.vf610 new file mode 100644 index 000000000..38cf5cfd2 --- /dev/null +++ b/roms/u-boot/doc/README.vf610 @@ -0,0 +1,10 @@ +U-Boot for Freescale Vybrid VF610 + +This file contains information for the port of U-Boot to the Freescale Vybrid +VF610 SoC. + +1. CONVENTIONS FOR FUSE ASSIGNMENTS +----------------------------------- + +1.1 MAC Address: It is stored in fuse bank 4, with the 16 msbs in word 2 and the + 32 lsbs in word 3. diff --git a/roms/u-boot/doc/README.video b/roms/u-boot/doc/README.video new file mode 100644 index 000000000..ced35bd2d --- /dev/null +++ b/roms/u-boot/doc/README.video @@ -0,0 +1,97 @@ +SPDX-License-Identifier: GPL-2.0+ +/* + * (C) Copyright 2000 + * Paolo Scaffardi, AIRVENT SAM s.p.a - RIMINI(ITALY), arsenio@tin.it + */ + +"video-mode" environment variable +================================= + +The 'video-mode' environment variable can be used to enable and configure +some video drivers. The format matches the video= command-line option used +for Linux: + + video-mode=<driver>:<xres>x<yres>-<depth>@<freq><,option=string> + + <driver> The video driver name, ignored by U-Boot + <xres> The X resolution (in pixels) to use. + <yres> The Y resolution (in pixels) to use. + <depth> The color depth (in bits) to use. + <freq> The frequency (in Hz) to use. + <options> A comma-separated list of device-specific options + + +U-Boot MPC8xx video controller driver +===================================== + +The driver has been tested with the following configurations: + +- MPC823FADS with AD7176 on a PAL TV (YCbYCr) - arsenio@tin.it + +Example: video-mode=fslfb:1280x1024-32@60,monitor=dvi + + +U-Boot sunxi video controller driver +==================================== + +U-Boot supports hdmi and lcd output on Allwinner sunxi SoCs, lcd output +requires the CONFIG_VIDEO_LCD_MODE Kconfig value to be set. + +The sunxi U-Boot driver supports the following video-mode options: + +- monitor=[none|dvi|hdmi|lcd|vga|composite-*] - Select the video output to use + none: Disable video output. + dvi/hdmi: Selects output over the hdmi connector with dvi resp. hdmi output + format, if edid is used the format is automatically selected. + lcd: Selects video output to a LCD screen. + vga: Selects video output over the VGA connector. + composite-pal/composite-ntsc/composite-pal-m/composite-pal-nc: + Selects composite video output, note the specified resolution is + ignored with composite video output. + Defaults to monitor=dvi. + +- hpd=[0|1] - Enable use of the hdmi HotPlug Detect feature + 0: Disabled. Configure dvi/hdmi output even if no cable is detected + 1: Enabled. Fallback to the lcd / vga / none in that order (if available) + Defaults to hpd=1. + +- hpd_delay=<int> - How long to wait for the hdmi HPD signal in milliseconds + When the monitor and the board power up at the same time, it may take some + time for the monitor to assert the HPD signal. This configures how long to + wait for the HPD signal before assuming no cable is connected. + Defaults to hpd_delay=500. + +- edid=[0|1] - Enable use of DDC + EDID to get monitor info + 0: Disabled. + 1: Enabled. If valid EDID info was read from the monitor the EDID info will + overrides the xres, yres and refresh from the video-mode env. variable. + Defaults to edid=1. + +- overscan_x/overscan_y=<int> - Set x/y overscan value + This configures a black border on the left and right resp. top and bottom + to deal with overscanning displays. Defaults to overscan_x=32 and + overscan_y=20 for composite monitors, 0 for other monitors. + +For example to always use the hdmi connector, even if no cable is inserted, +using edid info when available and otherwise initalizing it at 1024x768@60Hz, +use: "setenv video-mode sunxi:1024x768-24@60,monitor=dvi,hpd=0,edid=1". + + +TrueType fonts +-------------- + +U-Boot supports the use of antialiased TrueType fonts on some platforms. This +has been tested in x86, ARMv7 and sandbox. + +To enable this, select CONFIG_CONSOLE_TRUETYPE. You can choose between several +fonts, with CONSOLE_TRUETYPE_NIMBUS being the default. + +TrueType support requires floating point at present. On ARMv7 platforms you +need to disable use of the private libgcc. You can do this by disabling +CONFIG_USE_PRIVATE_LIBGCC. See chromebook_jerry for an example. Note that this +increases U-Boot's size by about 70KB at present. + +On ARM you should also make sure your toolchain supports hardfp. This is +normally given in the name of your toolchain, e.g. arm-linux-gnueabihf (hf +means hardware floating point). You can also run gcc with -v to see if it has +this option. diff --git a/roms/u-boot/doc/README.vxworks b/roms/u-boot/doc/README.vxworks new file mode 100644 index 000000000..12a0d744d --- /dev/null +++ b/roms/u-boot/doc/README.vxworks @@ -0,0 +1,115 @@ +# SPDX-License-Identifier: GPL-2.0+ +# +# Copyright (C) 2013, Miao Yan <miao.yan@windriver.com> +# Copyright (C) 2015-2018, Bin Meng <bmeng.cn@gmail.com> +# Copyright (C) 2019, Lihua Zhao <lihua.zhao@windriver.com> + +VxWorks Support +=============== + +This document describes the information about U-Boot loading VxWorks kernel. + +Status +------ +U-Boot supports loading VxWorks kernels via 'bootvx' and 'bootm' commands. +For booting old kernels (6.9.x) on PowerPC and ARM, and all kernel versions +on other architectures, 'bootvx' shall be used. For booting VxWorks 7 kernels +on PowerPC and ARM, 'bootm' shall be used. + +With CONFIG_EFI_LOADER option, it's possible to chain load a VxWorks x86 kernel +via the UEFI boot loader application for VxWorks loaded by 'bootefi' command. + +VxWorks 7 on PowerPC and ARM +--------------------------- +From VxWorks 7, VxWorks starts adopting device tree as its hardware description +mechanism (for PowerPC and ARM), thus requiring boot interface changes. +This section will describe the new interface. + +Since VxWorks 7 SR0640 release, VxWorks starts using Linux compatible standard +DTB for some boards. With that, the exact same bootm flow as used by Linux is +used, which includes board-specific DTB fix up. To keep backward compatibility, +only when the least significant bit of flags in bootargs is set, the standard +DTB will be used. Otherwise it falls back to the legacy bootm flow. + +For legacy bootm flow, make sure the least significant bit of flags in bootargs +is cleared. The calling convention is described below: + +For PowerPC, the calling convention of the new VxWorks entry point conforms to +the ePAPR standard, which is shown below (see ePAPR for more details): + + void (*kernel_entry)(fdt_addr, 0, 0, EPAPR_MAGIC, boot_IMA, 0, 0) + +For ARM, the calling convention is shown below: + + void (*kernel_entry)(void *fdt_addr) + +When using the Linux compatible standard DTB, the calling convention of VxWorks +entry point is exactly the same as the Linux kernel. + +When booting a VxWorks 7 kernel (uImage format), the parameters passed to bootm +is like below: + + bootm <kernel image address> - <device tree address> + +VxWorks bootline +---------------- +When using 'bootvx', the kernel bootline must be prepared by U-Boot at a +board-specific address before loading VxWorks. U-Boot supplies its address +via "bootaddr" environment variable. To check where the bootline should be +for a specific board, go to the VxWorks BSP for that board, and look for a +parameter called BOOT_LINE_ADRS. Assign its value to "bootaddr". A typical +value for "bootaddr" on an x86 board is 0x101200. + +If a "bootargs" variable is defined, its content will be copied to the memory +location pointed by "bootaddr" as the kernel bootline. If "bootargs" is not +there, command 'bootvx' can construct a valid bootline using the following +environments variables: bootdev, bootfile, ipaddr, netmask, serverip, +gatewayip, hostname, othbootargs. + +When using 'bootm', just define "bootargs" in the environment and U-Boot will +handle bootline fix up for the kernel dtb automatically. + +When using 'bootefi' to chain load an x86 kernel, the UEFI boot loader +application for VxWorks takes care of the kernel bootline preparation. + +Serial console +-------------- +It's very common that VxWorks BSPs configure a different baud rate for the +serial console from what is being used by U-Boot. For example, VxWorks tends +to use 9600 as the default baud rate on all x86 BSPs while U-Boot uses 115200. +Please configure both U-Boot and VxWorks to use the same baud rate, or it may +look like VxWorks hangs somewhere as nothing outputs on the serial console. + +x86-specific information +------------------------ +Before direct loading an x86 kernel via 'bootvx', one additional environment +variable need to be provided. This is "vx_phys_mem_base", which represent the +physical memory base address of VxWorks. + +Check VxWorks kernel configuration to look for LOCAL_MEM_LOCAL_ADRS. For +VxWorks 7, this is normally a virtual address and you need find out its +corresponding physical address and assign its value to "vx_phys_mem_base". + +For boards on which ACPI is not supported by U-Boot yet, VxWorks kernel must +be configured to use MP table and virtual wire interrupt mode. This requires +INCLUDE_MPTABLE_BOOT_OP and INCLUDE_VIRTUAL_WIRE_MODE to be included in a +VxWorks kernel configuration. + +Both 32-bit x86 and 64-bit x64 kernels can be loaded. + +There are two types of graphics console drivers in VxWorks. One is the 80x25 +VGA text mode driver. The other one is the EFI console bitmapped graphics mode +driver. To make these drivers function, U-Boot needs to load and run the VGA +BIOS of the graphics card first. + + - If the kernel is configured with 80x25 VGA text mode driver, + CONFIG_FRAMEBUFFER_SET_VESA_MODE must be unset in U-Boot. + - If the kernel is configured with bitmapped graphics mode driver, + CONFIG_FRAMEBUFFER_SET_VESA_MODE need remain set but care must be taken + at which VESA mode is to be set. The supported pixel format is 32-bit + RGBA, hence the available VESA mode can only be one of the following: + * FRAMEBUFFER_VESA_MODE_10F + * FRAMEBUFFER_VESA_MODE_112 + * FRAMEBUFFER_VESA_MODE_115 + * FRAMEBUFFER_VESA_MODE_118 + * FRAMEBUFFER_VESA_MODE_11B diff --git a/roms/u-boot/doc/README.watchdog b/roms/u-boot/doc/README.watchdog new file mode 100644 index 000000000..f23c92391 --- /dev/null +++ b/roms/u-boot/doc/README.watchdog @@ -0,0 +1,33 @@ +Watchdog driver general info + +CONFIG_HW_WATCHDOG + This enables hw_watchdog_reset to be called during various loops, + including waiting for a character on a serial port. But it + does not also call hw_watchdog_init. Boards which want this + enabled must call this function in their board file. This split + is useful because some rom's enable the watchdog when downloading + new code, so it must be serviced, but the board would rather it + was off. And, it cannot always be turned off once on. + +CONFIG_WATCHDOG_TIMEOUT_MSECS + Can be used to change the timeout for i.mx31/35/5x/6x. + If not given, will default to maximum timeout. This would + be 128000 msec for i.mx31/35/5x/6x. + +CONFIG_WDT_AT91 + Available for AT91SAM9 to service the watchdog. + +CONFIG_FTWDT010_WATCHDOG + Available for FTWDT010 to service the watchdog. + +CONFIG_FTWDT010_HW_TIMEOUT + Can be used to change the timeout for FTWDT010. + +CONFIG_IMX_WATCHDOG + Available for i.mx31/35/5x/6x to service the watchdog. This is not + automatically set because some boards (vision2) still need to define + their own hw_watchdog_reset routine. + TODO: vision2 is removed now, so perhaps this can be changed. + +CONFIG_XILINX_TB_WATCHDOG + Available for Xilinx Axi platforms to service timebase watchdog timer. diff --git a/roms/u-boot/doc/README.zfs b/roms/u-boot/doc/README.zfs new file mode 100644 index 000000000..7f237c407 --- /dev/null +++ b/roms/u-boot/doc/README.zfs @@ -0,0 +1,29 @@ +This patch series adds support for ZFS listing and load to u-boot. + +To Enable zfs ls and load commands, modify the board specific config file with +#define CONFIG_CMD_ZFS + +Steps to test: + +1. After applying the patch, zfs specific commands can be seen + in the boot loader prompt using + UBOOT #help + + zfsload- load binary file from a ZFS file system + zfsls - list files in a directory (default /) + +2. To list the files in zfs pool, device or partition, execute + zfsls <interface> <dev[:part]> [POOL/@/dir/file] + For example: + UBOOT #zfsls mmc 0:5 /rpool/@/usr/bin/ + +3. To read and load a file from an ZFS formatted partition to RAM, execute + zfsload <interface> <dev[:part]> [addr] [filename] [bytes] + For example: + UBOOT #zfsload mmc 2:2 0x30007fc0 /rpool/@/boot/uImage + +References : + -- ZFS GRUB sources from Solaris GRUB-0.97 + -- GRUB Bazaar repository + +Jorgen Lundman <lundman at lundman.net> 2012. diff --git a/roms/u-boot/doc/SPI/README.altera_spi b/roms/u-boot/doc/SPI/README.altera_spi new file mode 100644 index 000000000..b07449f80 --- /dev/null +++ b/roms/u-boot/doc/SPI/README.altera_spi @@ -0,0 +1,6 @@ +SoCFPGA EPCS/EPCQx1 mini howto: +- Instantiate EPCS/EPCQx1 Serial flash controller in QSys and rebuild +- The controller base address is the "Base" in QSys + 0x400 +- Set MSEL[4:0]=10010 (AS Standard) +- Load the bitstream into FPGA, enable bridges +- Only then will the driver work diff --git a/roms/u-boot/doc/SPI/README.ftssp010_spi_test b/roms/u-boot/doc/SPI/README.ftssp010_spi_test new file mode 100644 index 000000000..1d86f3623 --- /dev/null +++ b/roms/u-boot/doc/SPI/README.ftssp010_spi_test @@ -0,0 +1,41 @@ +SPI Flash test on Faraday A369 EVB: +================================== + +U-Boot 2014.01-rc2-g3444b6f (Dec 20 2013 - 10:58:40) + +CPU: FA626TE 528 MHz +AHB: 132 MHz +APB: 66 MHz +I2C: ready +DRAM: 256 MiB +MMU: on +NAND: 512 MiB +MMC: ftsdc010: 0 +*** Warning - bad CRC, using default environment + +In: serial +Out: serial +Err: serial +Net: FTGMAC100#0 +Hit any key to stop autoboot: 0 +=> sf probe 0:0 +SF: Detected MX25L1605D with page size 256 Bytes, erase size 64 KiB, total 2 MiB +=> sf read 0x10800000 0 0x400 +SF: 1024 bytes @ 0x0 Read: OK +=> md 0x10800000 +10800000: ea000013 e59ff014 e59ff014 e59ff014 ................ +10800010: e59ff014 e59ff014 e59ff014 e59ff014 ................ +10800020: 1ff7b0c0 1ff7b120 1ff7b180 1ff7b1e0 .... ........... +10800030: 1ff7b240 1ff7b2a0 1ff7b300 deadbeef @............... +10800040: 10800000 0002c1f0 0007409c 00032048 .........@..H .. +10800050: 1fd6af40 e10f0000 e3c0001f e38000d3 @............... +10800060: e129f000 eb000001 eb000223 e12fff1e ..).....#...../. +10800070: e3a00000 ee070f1e ee080f17 ee070f15 ................ +10800080: ee070f9a ee110f10 e3c00c03 e3c00087 ................ +10800090: e3c00a02 e3800002 e3800a01 ee010f10 ................ +108000a0: e1a0c00e eb007a68 e1a0e00c e1a0f00e ....hz.......... +108000b0: e1a00000 e1a00000 e1a00000 e1a00000 ................ +108000c0: e51fd078 e58de000 e14fe000 e58de004 x.........O..... +108000d0: e3a0d013 e169f00d e1a0e00f e1b0f00e ......i......... +108000e0: e24dd048 e88d1fff e51f20a0 e892000c H.M...... ...... +108000f0: e28d0048 e28d5034 e1a0100e e885000f H...4P.......... diff --git a/roms/u-boot/doc/SPI/README.sandbox-spi b/roms/u-boot/doc/SPI/README.sandbox-spi new file mode 100644 index 000000000..f6a55fe78 --- /dev/null +++ b/roms/u-boot/doc/SPI/README.sandbox-spi @@ -0,0 +1,42 @@ +Sandbox SPI/SPI Flash Implementation +==================================== + +U-Boot supports SPI and SPI flash emulation in sandbox. This must be enabled +via a device tree. + +For example: + + spi@0 { + #address-cells = <1>; + #size-cells = <0>; + reg = <0 1>; + compatible = "sandbox,spi"; + cs-gpios = <0>, <&gpio_a 0>; + spi.bin@0 { + reg = <0>; + compatible = "spansion,m25p16", "jedec,spi-nor"; + spi-max-frequency = <40000000>; + sandbox,filename = "spi.bin"; + }; + }; + +Supported chips are W25Q16 (2MB), W25Q32 (4MB) and W25Q128 (16MB). Once +U-Boot it started you can use 'sf' commands as normal. For example: + +$ dd if=/dev/zero of=spi.bin bs=1M count=2 +$ u-boot -T + +Since the SPI bus is fully implemented as well as the SPI flash connected to +it, you can also use low-level SPI commands to access the flash. For example +this reads the device ID from the emulated chip: + +=> sspi 0 32 9f +SF: Detected m25p16 with page size 256 Bytes, erase size 64 KiB, total 2 MiB +FF202015 + + +Simon Glass +sjg@chromium.org +7/11/2013 +Note that the sandbox SPI implementation was written by Mike Frysinger +<vapier@gentoo.org>. diff --git a/roms/u-boot/doc/SPI/README.sh_qspi_test b/roms/u-boot/doc/SPI/README.sh_qspi_test new file mode 100644 index 000000000..8a33fec32 --- /dev/null +++ b/roms/u-boot/doc/SPI/README.sh_qspi_test @@ -0,0 +1,38 @@ +------------------------------------------------- + Simple steps used to test the SH-QSPI at U-Boot +------------------------------------------------- + +#0, Currently, SH-QSPI is used by lager board (Renesas ARM SoC R8A7790) + and koelsch board (Renesas ARM SoC R8A7791). These boot from SPI ROM + basically. Thus, U-Boot start, SH-QSPI will is operating normally. + +#1, build U-Boot and load u-boot.bin + + => tftpboot 40000000 u-boot.bin + sh_eth Waiting for PHY auto negotiation to complete.. done + sh_eth: 100Base/Half + Using sh_eth device + TFTP from server 192.168.169.1; our IP address is 192.168.169.79 + Filename 'u-boot.bin'. + Load address: 0x40000000 + Loading: ############ + 2.5 MiB/s + done + Bytes transferred = 175364 (2ad04 hex) + +#2, Commands to erase/write u-boot to flash device + + Note: This method is description of the lager board. If you want to use the + other boards, please change the value according to each environment. + + => sf probe 0 + SF: Detected S25FL512S_256K with page size 512 Bytes, erase size 64 KiB, total 64 MiB + => sf erase 80000 40000 + SF: 262144 bytes @ 0x80000 Erased: OK + => sf write 40000000 80000 175364 + SF: 1528676 bytes @ 0x80000 Written: OK + => + +#3, Push reset button. + + If you're written correctly and driver works properly, U-Boot starts. diff --git a/roms/u-boot/doc/SPI/README.ti_qspi_am43x_test b/roms/u-boot/doc/SPI/README.ti_qspi_am43x_test new file mode 100644 index 000000000..8fbf10b57 --- /dev/null +++ b/roms/u-boot/doc/SPI/README.ti_qspi_am43x_test @@ -0,0 +1,76 @@ +Testing details- +---------------- + +This doc simply illustrated the testing details of qspi flash +driver with Macronix M25L51235 flash device. + +The test includes +- probing the flash device +- erasing the flash device +- Writing to flash +- Reading the contents of the flash. + +Test Log +-------- + +Hit any key to stop autoboot: 0 +U-Boot# sf probe 0 +SF: Detected MX25L51235F with page size 256 Bytes, erase size 64 KiB, total 64 MiB, mapped at 30000000 +U-Boot# sf erase 0 0x80000 +SF: 524288 bytes @ 0x0 Erased: OK +U-Boot# mw 81000000 0xdededede 0x40000 +U-Boot# sf write 81000000 0 0x40000 +SF: 262144 bytes @ 0x0 Written: OK +U-Boot# sf read 82000000 0 0x40000 +SF: 262144 bytes @ 0x0 Read: OK +U-Boot# md 0x82000000 +82000000: dededede dededede dededede dededede ................ +82000010: dededede dededede dededede dededede ................ +82000020: dededede dededede dededede dededede ................ +82000030: dededede dededede dededede dededede ................ +82000040: dededede dededede dededede dededede ................ +82000050: dededede dededede dededede dededede ................ +82000060: dededede dededede dededede dededede ................ +82000070: dededede dededede dededede dededede ................ +82000080: dededede dededede dededede dededede ................ +82000090: dededede dededede dededede dededede ................ +820000a0: dededede dededede dededede dededede ................ +820000b0: dededede dededede dededede dededede ................ +820000c0: dededede dededede dededede dededede ................ +820000d0: dededede dededede dededede dededede ................ +820000e0: dededede dededede dededede dededede ................ +820000f0: dededede dededede dededede dededede ................ +U-Boot# md 0x82010000 +82010000: dededede dededede dededede dededede ................ +82010010: dededede dededede dededede dededede ................ +82010020: dededede dededede dededede dededede ................ +82010030: dededede dededede dededede dededede ................ +82010040: dededede dededede dededede dededede ................ +82010050: dededede dededede dededede dededede ................ +82010060: dededede dededede dededede dededede ................ +82010070: dededede dededede dededede dededede ................ +82010080: dededede dededede dededede dededede ................ +82010090: dededede dededede dededede dededede ................ +820100a0: dededede dededede dededede dededede ................ +820100b0: dededede dededede dededede dededede ................ +820100c0: dededede dededede dededede dededede ................ +820100d0: dededede dededede dededede dededede ................ +820100e0: dededede dededede dededede dededede ................ +820100f0: dededede dededede dededede dededede ................ +U-Boot# md 0x82030000 +82030000: dededede dededede dededede dededede ................ +82030010: dededede dededede dededede dededede ................ +82030020: dededede dededede dededede dededede ................ +82030030: dededede dededede dededede dededede ................ +82030040: dededede dededede dededede dededede ................ +82030050: dededede dededede dededede dededede ................ +82030060: dededede dededede dededede dededede ................ +82030070: dededede dededede dededede dededede ................ +82030080: dededede dededede dededede dededede ................ +82030090: dededede dededede dededede dededede ................ +820300a0: dededede dededede dededede dededede ................ +820300b0: dededede dededede dededede dededede ................ +820300c0: dededede dededede dededede dededede ................ +820300d0: dededede dededede dededede dededede ................ +820300e0: dededede dededede dededede dededede ................ +820300f0: dededede dededede dededede dededede ................ diff --git a/roms/u-boot/doc/SPI/README.ti_qspi_dra_test b/roms/u-boot/doc/SPI/README.ti_qspi_dra_test new file mode 100644 index 000000000..e89f53587 --- /dev/null +++ b/roms/u-boot/doc/SPI/README.ti_qspi_dra_test @@ -0,0 +1,47 @@ +------------------------------------------------- + Simple steps used to test the QSPI at U-Boot +------------------------------------------------- + +For #1, build the patched U-Boot and load MLO/u-boot.img + +---------------------------------- +Boot from another medium like MMC +---------------------------------- + +U-Boot# mmc dev 0 +mmc0 is current device +U-Boot# fatload mmc 0 0x82000000 MLO +reading MLO +55872 bytes read in 8 ms (6.7 MiB/s) +U-Boot# fatload mmc 0 0x83000000 u-boot.img +reading u-boot.img +248600 bytes read in 19 ms (12.5 MiB/s) + +-------------------------------------------------- +Commands to erase/write u-boot/mlo to flash device +-------------------------------------------------- +U-Boot# sf probe 0 +SF: Detected S25FL256S_64K with page size 256 Bytes, erase size 64 KiB, total 32 MiB, mapped at 5c000000 +U-Boot# sf erase 0 0x10000 +SF: 65536 bytes @ 0x0 Erased: OK +U-Boot# sf erase 0x20000 0x10000 +SF: 65536 bytes @ 0x20000 Erased: OK +U-Boot# sf erase 0x30000 0x10000 +SF: 65536 bytes @ 0x30000 Erased: OK +U-Boot# sf erase 0x40000 0x10000 +SF: 65536 bytes @ 0x40000 Erased: OK +U-Boot# sf erase 0x50000 0x10000 +SF: 65536 bytes @ 0x50000 Erased: OK +U-Boot# sf erase 0x60000 0x10000 +SF: 65536 bytes @ 0x60000 Erased: OK +U-Boot# sf write 82000000 0 0x10000 +SF: 65536 bytes @ 0x0 Written: OK +U-Boot# sf write 83000000 0x20000 0x60000 +SF: 393216 bytes @ 0x20000 Written: OK + +For #2, set sysboot to QSPI-1 boot mode(SYSBOOT[5:0] = 100110) and power +on. ROM should find the GP header at offset 0 and load/execute SPL. SPL +then detects that ROM was in QSPI-1 mode (boot code 10) and attempts to +find a U-Boot image header at offset 0x20000 (set in the config file) +and proceeds to load that image using the U-Boot image payload offset/size +from the header. It will then start U-Boot. diff --git a/roms/u-boot/doc/SPI/README.ti_qspi_flash b/roms/u-boot/doc/SPI/README.ti_qspi_flash new file mode 100644 index 000000000..5cc1fd03b --- /dev/null +++ b/roms/u-boot/doc/SPI/README.ti_qspi_flash @@ -0,0 +1,47 @@ +QSPI U-Boot support +------------------ + +Host processor is connected to serial flash device via qpsi +interface. QSPI is a kind of spi module that allows single, +dual and quad read access to external spi devices. The module +has a memory mapped interface which provide direct interface +for accessing data form external spi devices. + +The one QSPI in the device is primarily intended for fast booting +from Quad SPI flash devices. + +Usecase +------- + +MLO/u-boot.img will be flashed from SD/MMC to the flash device +using serial flash erase and write commands. Then, switch settings +will be changed to qspi boot. Then, the ROM code will read MLO +from the predefined location in the flash, where it was flashed and +execute it after storing it in SDRAM. Then, the MLO will read +u-boot.img from flash and execute it from SDRAM. + +SPI mode +------- +SPI mode uses mtd spi framework for transfer and reception of data. +Can be used in: +1. Normal mode: use single pin for transfers +2. Dual Mode: use two pins for transfers. +3. Quad mode: use four pin for transfer + +Memory mapped read mode +----------------------- +In this, SPI controller is configured using configuration port and then +controller is switched to memory mapped port for data read. + +Driver +------ +drivers/qspi/ti_qspi.c + - Newly created file which is responsible for configuring the + qspi controller and also for providing the low level api which + is responsible for transferring the datas from host controller + to flash device and vice versa. + +Testing +------- +A seperated file named README.dra_qspi_test has been created which gives all the +details about the commands required to test qspi at U-Boot level. diff --git a/roms/u-boot/doc/SPI/status.txt b/roms/u-boot/doc/SPI/status.txt new file mode 100644 index 000000000..13889f545 --- /dev/null +++ b/roms/u-boot/doc/SPI/status.txt @@ -0,0 +1,32 @@ +Status on SPI subsystem: +======================= + +SPI COMMAND (common/cmd_sf, cmd_spi): +- + +SPI FLASH (drivers/mtd/spi): +- sf_probe.c: SPI flash probing code. +- sf_ops.c: SPI flash operations code. +- sf.c: SPI flash interface, which interacts controller driver. +- Bank Address Register (Accessing flashes > 16Mbytes in 3-byte addressing) +- Added memory_mapped support for read operations. +- Common probe support for all supported flash vendors except, ramtron. +- Extended read commands support(dual read, dual IO read) +- Quad Page Program support. +- Quad Read support(quad fast read, quad IO read) +- Dual flash connection topology support(accessing two spi flash memories with single cs) +- Banking support on dual flash connection topology. + +SPI DRIVERS (drivers/spi): +- + +TODO: +- Runtime detection of spi_flash params, SFDP(if possible) +- Add support for multibus build/accessing. +- Need proper cleanups on spi_flash and drivers. + +-- +Jagannadha Sutradharudu Teki <jagannadh.teki@gmail.com> +18-09-2013. +07-10-2013. +08-01-2014. diff --git a/roms/u-boot/doc/SPL/README.am335x-network b/roms/u-boot/doc/SPL/README.am335x-network new file mode 100644 index 000000000..e3cf93f8d --- /dev/null +++ b/roms/u-boot/doc/SPL/README.am335x-network @@ -0,0 +1,96 @@ +USING AM335x NETBOOT FEATURE + + Some boards (like TI AM335x based ones) have quite big on-chip RAM and +have support for booting via network in ROM. The following describes +how to setup network booting and then optionally use this support to flash +NAND and bricked (empty) board with only a network cable. + + I. Building the required images + 1. You have to enable generic SPL configuration options (see +doc/README.SPL) as well as CONFIG_SPL_NET_SUPPORT, +CONFIG_ETH_SUPPORT, CONFIG_SPL_LIBGENERIC_SUPPORT and +CONFIG_SPL_LIBCOMMON_SUPPORT in your board configuration file to build +SPL with support for booting over the network. Also you have to enable +the driver for the NIC used and CONFIG_SPL_BOARD_INIT option if your +board needs some board-specific initialization (TI AM335x EVM does). +If you want SPL to use some Vendor Class Identifier (VCI) you can set +one with CONFIG_SPL_NET_VCI_STRING option. am335x_evm configuration +comes with support for network booting preconfigured. + 2. Define CONFIG_BOOTCOMMAND for your board to load and run debrick +script after boot: +#define CONFIG_BOOTCOMMAND \ + "setenv autoload no; " \ + "bootp; " \ + "if tftp 80000000 debrick.scr; then " \ + "source 80000000; " \ + "fi" +(Or create additional board configuration with such option). + 3. Build U-Boot as usual + $ make <your_board_name> + You will need u-boot.img and spl/u-boot.bin images to perform +network boot. Copy them to u-boot-restore.img and +u-boot-spl-restore.bin respectively to distinguish this version +(with automatic restore running) from the main one. + + II. Host configuration. + 1. Setup DHCP server (recommended server is ISC DHCPd). + - Install DHCP server and setup it to listen on the interface you +chose to connect to the board (usually configured in +/etc/default/dhcpd or /etc/default/isc-dhcp-server). Make sure there +are no other active DHCP servers in the same network segment. + - Edit your dhcpd.conf and subnet declaration matching the address +on the interface. Specify the range of assigned addresses and bootfile +to use. IMPORTANT! Both RBL and SPL use the image filename provided +in the BOOTP reply but obviously they need different images (RBL needs +raw SPL image -- u-boot-spl-restore.bin while SPL needs main U-Boot +image -- u-boot-restore.img). So you have to configure DHCP server to +provide different image filenames to RBL and SPL (and possibly another +one to main U-Boot). This can be done by checking Vendor Class +Identifier (VCI) set by BOOTP client (RBL sets VCI to "DM814x ROM v1.0" +and you can set VCI used by SPL with CONFIG_SPL_NET_VCI_STRING option, +see above). + - If you plan to use TFTP server on another machine you have to set +server-name option to point to it. + - Here is sample configuration for ISC DHCPd, assuming the interface +used to connect to the board is eth0, and it has address 192.168.8.1: + +subnet 192.168.8.0 netmask 255.255.255.0 { + range dynamic-bootp 192.168.8.100 192.168.8.199; + + if substring (option vendor-class-identifier, 0, 10) = "DM814x ROM" { + filename "u-boot-spl-restore.bin"; + } elsif substring (option vendor-class-identifier, 0, 17) = "AM335x U-Boot SPL" { + filename "u-boot-restore.img"; + } else { + filename "uImage"; + } +} + + May the ROM bootloader sends another "vendor-class-identifier" + on the shc board with an AM335X it is: + "AM335x ROM" + + 2. Setup TFTP server. + Install TFTP server and put image files to it's root directory +(likely /tftpboot or /var/lib/tftpboot or /srv/tftp). You will need +u-boot.img and spl/u-boot-spl-bin files from U-Boot build directory. + + III. Reflashing (debricking) the board. + 1. Write debrick script. You will need to write a script that will +be executed after network boot to perform actual rescue actions. You +can use usual U-Boot commands from this script: tftp to load additional +files, nand erase/nand write to erase/write the NAND flash. + + 2. Create script image from your script. From U-Boot build directory: + +$ ./tools/mkimage -A arm -O U-Boot -C none -T script -d <your script> debrick.scr + +This will create debrick.scr file with your script inside. + + 3. Copy debrick.scr to TFTP root directory. You also need to copy +there all the files your script tries to load via TFTP. Example script +loads u-boot.img and MLO. You have to create these files doing regular +(not restore_flash) build and copy them to tftpboot directory. + + 4. Boot the board from the network, U-Boot will load debrick script +and run it after boot. diff --git a/roms/u-boot/doc/SPL/README.omap3 b/roms/u-boot/doc/SPL/README.omap3 new file mode 100644 index 000000000..c77ca4300 --- /dev/null +++ b/roms/u-boot/doc/SPL/README.omap3 @@ -0,0 +1,52 @@ +Overview of SPL on OMAP3 devices +================================ + +Introduction +------------ + +This document provides an overview of how SPL functions on OMAP3 (and related +such as am35x and am37x) processors. + +Methodology +----------- + +On these platforms the ROM supports trying a sequence of boot devices. Once +one has been used successfully to load SPL this information is stored in memory +and the location stored in a register. We will read this to determine where to +read U-Boot from in turn. + +Memory Map +---------- + +This is an example of a typical setup. See top-level README for documentation +of which CONFIG variables control these values. For a given board and the +amount of DRAM available to it different values may need to be used. +Note that the size of the SPL text rodata and data is enforced with a CONFIG +option and growing over that size results in a link error. The SPL stack +starts at the top of SRAM (which is configurable) and grows downward. The +space between the top of SRAM and the enforced upper bound on the size of the +SPL text, data and rodata is considered the safe stack area. Details on +confirming this behavior are shown below. + +A portion of the system memory map looks as follows: +SRAM: 0x40200000 - 0x4020FFFF +DDR1: 0x80000000 - 0xBFFFFFFF + +Option 1 (SPL only): +0x40200800 - 0x4020BBFF: Area for SPL text, data and rodata +0x4020E000 - 0x4020FFFC: Area for the SPL stack. +0x80000000 - 0x8007FFFF: Area for the SPL BSS. +0x80100000: CONFIG_SYS_TEXT_BASE of U-Boot +0x80208000 - 0x80307FFF: malloc() pool available to SPL. + +Option 2 (SPL or X-Loader): +0x40200800 - 0x4020BBFF: Area for SPL text, data and rodata +0x4020E000 - 0x4020FFFC: Area for the SPL stack. +0x80008000: CONFIG_SYS_TEXT_BASE of U-Boot +0x87000000 - 0x8707FFFF: Area for the SPL BSS. +0x87080000 - 0x870FFFFF: malloc() pool available to SPL. + +For the areas that reside within DDR1 they must not be used prior to s_init() +completing. Note that CONFIG_SYS_TEXT_BASE must be clear of the areas that SPL +uses while running. This is why we have two versions of the memory map that +only vary in where the BSS and malloc pool reside. diff --git a/roms/u-boot/doc/SPL/README.spl-secure-boot b/roms/u-boot/doc/SPL/README.spl-secure-boot new file mode 100644 index 000000000..f2f8d7888 --- /dev/null +++ b/roms/u-boot/doc/SPL/README.spl-secure-boot @@ -0,0 +1,18 @@ +Overview of SPL verified boot on powerpc/mpc85xx & arm/layerscape platforms +=========================================================================== + +Introduction +------------ + +This document provides an overview of how SPL verified boot works on powerpc/ +mpc85xx & arm/layerscape platforms. + +Methodology +----------- + +The SPL image is responsible for loading the next stage boot loader, which is +the main u-boot image. For secure boot process on these platforms ROM verifies +SPL image, so to continue chain of trust SPL image verifies U-boot image using +spl_validate_uboot(). This function uses QorIQ Trust Architecture header +(appended to U-boot image) to validate the U-boot binary just before passing +control to it. diff --git a/roms/u-boot/doc/android/ab.rst b/roms/u-boot/doc/android/ab.rst new file mode 100644 index 000000000..961895c32 --- /dev/null +++ b/roms/u-boot/doc/android/ab.rst @@ -0,0 +1,72 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +Android A/B updates +=================== + +Overview +-------- + +A/B system updates ensures modern approach for system update. This feature +allows one to use two sets (or more) of partitions referred to as slots +(normally slot A and slot B). The system runs from the current slot while the +partitions in the unused slot can be updated [1]_. + +A/B enablement +-------------- + +The A/B updates support can be activated by specifying next options in +your board configuration file:: + + CONFIG_ANDROID_AB=y + CONFIG_CMD_AB_SELECT=y + +The disk space on target device must be partitioned in a way so that each +partition which needs to be updated has two or more instances. The name of +each instance must be formed by adding suffixes: ``_a``, ``_b``, ``_c``, etc. +For example: ``boot_a``, ``boot_b``, ``system_a``, ``system_b``, ``vendor_a``, +``vendor_b``. + +As a result you can use ``ab_select`` command to ensure A/B boot process in your +boot script. This command analyzes and processes A/B metadata stored on a +special partition (e.g. ``misc``) and determines which slot should be used for +booting up. + +Command usage +------------- + +.. code-block:: none + + ab_select <slot_var_name> <interface> <dev[:part_number|#part_name]> + +for example:: + + => ab_select slot_name mmc 1:4 + +or:: + + => ab_select slot_name mmc 1#misc + +Result:: + + => printenv slot_name + slot_name=a + +Based on this slot information, the current boot partition should be defined, +and next kernel command line parameters should be generated: + +* ``androidboot.slot_suffix=`` +* ``root=`` + +For example:: + + androidboot.slot_suffix=_a root=/dev/mmcblk1p12 + +A/B metadata is organized according to AOSP reference [2]_. On the first system +start with A/B enabled, when ``misc`` partition doesn't contain required data, +the default A/B metadata will be created and written to ``misc`` partition. + +References +---------- + +.. [1] https://source.android.com/devices/tech/ota/ab +.. [2] https://android.googlesource.com/platform/bootable/recovery/+/refs/tags/android-10.0.0_r25/bootloader_message/include/bootloader_message/bootloader_message.h diff --git a/roms/u-boot/doc/android/avb2.rst b/roms/u-boot/doc/android/avb2.rst new file mode 100644 index 000000000..a07211957 --- /dev/null +++ b/roms/u-boot/doc/android/avb2.rst @@ -0,0 +1,133 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +Android Verified Boot 2.0 +========================= + +This file contains information about the current support of Android Verified +Boot 2.0 in U-Boot. + +Overview +-------- + +Verified Boot establishes a chain of trust from the bootloader to system images: + +* Provides integrity checking for: + + * Android Boot image: Linux kernel + ramdisk. RAW hashing of the whole + partition is done and the hash is compared with the one stored in + the VBMeta image + * ``system``/``vendor`` partitions: verifying root hash of dm-verity hashtrees + +* Provides capabilities for rollback protection + +Integrity of the bootloader (U-Boot BLOB and environment) is out of scope. + +For additional details check [1]_. + +AVB using OP-TEE (optional) +^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +If AVB is configured to use OP-TEE (see `Enable on your board`_) rollback +indexes and device lock state are stored in RPMB. The RPMB partition is managed +by OP-TEE (see [2]_ for details) which is a secure OS leveraging ARM +TrustZone. + +AVB 2.0 U-Boot shell commands +----------------------------- + +Provides CLI interface to invoke AVB 2.0 verification + misc. commands for +different testing purposes:: + + avb init <dev> - initialize avb 2.0 for <dev> + avb verify - run verification process using hash data from vbmeta structure + avb read_rb <num> - read rollback index at location <num> + avb write_rb <num> <rb> - write rollback index <rb> to <num> + avb is_unlocked - returns unlock status of the device + avb get_uuid <partname> - read and print uuid of partition <partname> + avb read_part <partname> <offset> <num> <addr> - read <num> bytes from + partition <partname> to buffer <addr> + avb write_part <partname> <offset> <num> <addr> - write <num> bytes to + <partname> by <offset> using data from <addr> + +Partitions tampering (example) +------------------------------ + +Boot or system/vendor (dm-verity metadata section) is tampered:: + + => avb init 1 + => avb verify + avb_slot_verify.c:175: ERROR: boot: Hash of data does not match digest in + descriptor. + Slot verification result: ERROR_IO + +Vbmeta partition is tampered:: + + => avb init 1 + => avb verify + avb_vbmeta_image.c:206: ERROR: Hash does not match! + avb_slot_verify.c:388: ERROR: vbmeta: Error verifying vbmeta image: + HASH_MISMATCH + Slot verification result: ERROR_IO + +Enable on your board +-------------------- + +The following options must be enabled:: + + CONFIG_LIBAVB=y + CONFIG_AVB_VERIFY=y + CONFIG_CMD_AVB=y + +In addtion optionally if storing rollback indexes in RPMB with help of +OP-TEE:: + + CONFIG_TEE=y + CONFIG_OPTEE=y + CONFIG_OPTEE_TA_AVB=y + CONFIG_SUPPORT_EMMC_RPMB=y + +Then add ``avb verify`` invocation to your android boot sequence of commands, +e.g.:: + + => avb_verify=avb init $mmcdev; avb verify; + => if run avb_verify; then \ + echo AVB verification OK. Continue boot; \ + set bootargs $bootargs $avb_bootargs; \ + else \ + echo AVB verification failed; \ + exit; \ + fi; \ + + => emmc_android_boot= \ + echo Trying to boot Android from eMMC ...; \ + ... \ + run avb_verify; \ + mmc read ${fdtaddr} ${fdt_start} ${fdt_size}; \ + mmc read ${loadaddr} ${boot_start} ${boot_size}; \ + bootm $loadaddr $loadaddr $fdtaddr; \ + +If partitions you want to verify are slotted (have A/B suffixes), then current +slot suffix should be passed to ``avb verify`` sub-command, e.g.:: + + => avb verify _a + +To switch on automatic generation of vbmeta partition in AOSP build, add these +lines to device configuration mk file:: + + BOARD_AVB_ENABLE := true + BOARD_AVB_ALGORITHM := SHA512_RSA4096 + BOARD_BOOTIMAGE_PARTITION_SIZE := <boot partition size> + +After flashing U-Boot don't forget to update environment and write new +partition table:: + + => env default -f -a + => setenv partitions $partitions_android + => env save + => gpt write mmc 1 $partitions_android + +References +---------- + +.. [1] https://android.googlesource.com/platform/external/avb/+/master/README.md +.. [2] https://www.op-tee.org/ diff --git a/roms/u-boot/doc/android/bcb.rst b/roms/u-boot/doc/android/bcb.rst new file mode 100644 index 000000000..886160830 --- /dev/null +++ b/roms/u-boot/doc/android/bcb.rst @@ -0,0 +1,100 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +Android Bootloader Control Block (BCB) +====================================== + +The purpose behind this file is to: + +* give an overview of BCB w/o duplicating public documentation +* describe the main BCB use-cases which concern U-Boot +* reflect current support status in U-Boot +* mention any relevant U-Boot build-time tunables +* precisely exemplify one or more use-cases + +Additions and fixes are welcome! + +Overview +-------- + +Bootloader Control Block (BCB) is a well established term/acronym in +the Android namespace which refers to a location in a dedicated raw +(i.e. FS-unaware) flash (e.g. eMMC) partition, usually called ``misc``, +which is used as media for exchanging messages between Android userspace +(particularly recovery [1]_) and an Android-capable bootloader. + +On higher level, BCB provides a way to implement a subset of Android +Bootloader Requirements [2]_, amongst which are: + +* Android-specific bootloader flow [3]_ +* Get the "reboot reason" (and act accordingly) [4]_ +* Get/pass a list of commands from/to recovery [1]_ +* TODO + + +'bcb'. Shell command overview +----------------------------- + +The ``bcb`` command provides a CLI to facilitate the development of the +requirements enumerated above. Below is the command's help message:: + + => bcb + bcb - Load/set/clear/test/dump/store Android BCB fields + + Usage: + bcb load <dev> <part> - load BCB from mmc <dev>:<part> + bcb set <field> <val> - set BCB <field> to <val> + bcb clear [<field>] - clear BCB <field> or all fields + bcb test <field> <op> <val> - test BCB <field> against <val> + bcb dump <field> - dump BCB <field> + bcb store - store BCB back to mmc + + Legend: + <dev> - MMC device index containing the BCB partition + <part> - MMC partition index or name containing the BCB + <field> - one of {command,status,recovery,stage,reserved} + <op> - the binary operator used in 'bcb test': + '=' returns true if <val> matches the string stored in <field> + '~' returns true if <val> matches a subset of <field>'s string + <val> - string/text provided as input to bcb {set,test} + NOTE: any ':' character in <val> will be replaced by line feed + during 'bcb set' and used as separator by upper layers + + +'bcb'. Example of getting reboot reason +--------------------------------------- + +.. code-block:: bash + + if bcb load 1 misc; then + # valid BCB found + if bcb test command = bootonce-bootloader; then + bcb clear command; bcb store; + # do the equivalent of AOSP ${fastbootcmd} + # i.e. call fastboot + else if bcb test command = boot-recovery; then + bcb clear command; bcb store; + # do the equivalent of AOSP ${recoverycmd} + # i.e. do anything required for booting into recovery + else + # boot Android OS normally + fi + else + # corrupted/non-existent BCB + # report error or boot non-Android OS (platform-specific) + fi + + +Enable on your board +-------------------- + +The following Kconfig options must be enabled:: + + CONFIG_PARTITIONS=y + CONFIG_MMC=y + CONFIG_BCB=y + +.. [1] https://android.googlesource.com/platform/bootable/recovery +.. [2] https://source.android.com/devices/bootloader +.. [3] https://patchwork.ozlabs.org/patch/746835/ + ("[U-Boot,5/6] Initial support for the Android Bootloader flow") +.. [4] https://source.android.com/devices/bootloader/boot-reason diff --git a/roms/u-boot/doc/android/boot-image.rst b/roms/u-boot/doc/android/boot-image.rst new file mode 100644 index 000000000..fa8f2a47e --- /dev/null +++ b/roms/u-boot/doc/android/boot-image.rst @@ -0,0 +1,155 @@ +.. SPDX-License-Identifier: GPL-2.0+ +.. sectionauthor:: Sam Protsenko <joe.skb7@gmail.com> + +Android Boot Image +================== + +Overview +-------- + +Android Boot Image is used to boot Android OS. It usually contains kernel image +(like ``zImage`` file) and ramdisk. Sometimes it can contain additional +binaries. This image is built as a part of AOSP (called ``boot.img``), and being +flashed into ``boot`` partition on eMMC. Bootloader then reads that image from +``boot`` partition to RAM and boots the kernel from it. Kernel than starts +``init`` process from the ramdisk. It should be mentioned that recovery image +(``recovery.img``) also has Android Boot Image format. + +Android Boot Image format is described at [1]_. At the moment it can have one of +next image headers: + +* v0: it's called *legacy* boot image header; used in devices launched before + Android 9; contains kernel image, ramdisk and second stage bootloader + (usually unused) +* v1: used in devices launched with Android 9; adds ``recovery_dtbo`` field, + which should be used for non-A/B devices in ``recovery.img`` (see [2]_ for + details) +* v2: used in devices launched with Android 10; adds ``dtb`` field, which + references payload containing DTB blobs (either concatenated one after the + other, or in Android DTBO image format) + +v2, v1 and v0 formats are backward compatible. + +The Android Boot Image format is represented by +:c:type:`struct andr_img_hdr <andr_img_hdr>` in U-Boot, and can be seen in +``include/android_image.h``. U-Boot supports booting Android Boot Image and also +has associated command + +Booting +------- + +U-Boot is able to boot the Android OS from Android Boot Image using ``bootm`` +command. In order to use Android Boot Image format support, next option should +be enabled:: + + CONFIG_ANDROID_BOOT_IMAGE=y + +Then one can use next ``bootm`` command call to run Android: + +.. code-block:: bash + + => bootm $loadaddr $loadaddr $fdtaddr + +where ``$loadaddr`` - address in RAM where boot image was loaded; ``$fdtaddr`` - +address in RAM where DTB blob was loaded. + +And parameters are, correspondingly: + + 1. Where kernel image is located in RAM + 2. Where ramdisk is located in RAM (can be ``"-"`` if not applicable) + 3. Where DTB blob is located in RAM + +``bootm`` command will figure out that image located in ``$loadaddr`` has +Android Boot Image format, will parse that and boot the kernel from it, +providing DTB blob to kernel (from 3rd parameter), passing info about ramdisk to +kernel via DTB. + +DTB and DTBO blobs +------------------ + +``bootm`` command can't just use DTB blob from Android Boot Image (``dtb`` +field), because: + +* there is no DTB area in Android Boot Image before v2 +* there may be several DTB blobs in DTB area (e.g. for different SoCs) +* some DTBO blobs may have to be merged in DTB blobs before booting + (e.g. for different boards) + +So user has to prepare DTB blob manually and provide it in a 3rd parameter +of ``bootm`` command. Next commands can be used to do so: + +1. ``abootimg``: manipulates Anroid Boot Image, allows one to extract + meta-information and payloads from it +2. ``adtimg``: manipulates Android DTB/DTBO image [3]_, allows one to extract + DTB/DTBO blobs from it + +In order to use those, please enable next config options:: + + CONFIG_CMD_ABOOTIMG=y + CONFIG_CMD_ADTIMG=y + +For example, let's assume we have next Android partitions on eMMC: + +* ``boot``: contains Android Boot Image v2 (including DTB blobs) +* ``dtbo``: contains DTBO blobs + +Then next command sequence can be used to boot Android: + +.. code-block:: bash + + => mmc dev 1 + + # Read boot image to RAM (into $loadaddr) + => part start mmc 1 boot boot_start + => part size mmc 1 boot boot_size + => mmc read $loadaddr $boot_start $boot_size + + # Read DTBO image to RAM (into $dtboaddr) + => part start mmc 1 dtbo dtbo_start + => part size mmc 1 dtbo dtbo_size + => mmc read $dtboaddr $dtbo_start $dtbo_size + + # Copy required DTB blob (into $fdtaddr) + => abootimg get dtb --index=0 dtb0_start dtb0_size + => cp.b $dtb0_start $fdtaddr $dtb0_size + + # Merge required DTBO blobs into DTB blob + => fdt addr $fdtaddr 0x100000 + => adtimg addr $dtboaddr + => adtimg get dt --index=0 $dtbo0_addr + => fdt apply $dtbo0_addr + + # Boot Android + => bootm $loadaddr $loadaddr $fdtaddr + +This sequence should be used for Android 10 boot. Of course, the whole Android +boot procedure includes much more actions, like: + +* obtaining reboot reason from BCB (see [4]_) +* implementing recovery boot +* implementing fastboot boot +* implementing A/B slotting (see [5]_) +* implementing AVB2.0 (see [6]_) + +But Android Boot Image booting is the most crucial part in Android boot scheme. + +All Android bootloader requirements documentation is available at [7]_. Some +overview on the whole Android 10 boot process can be found at [8]_. + +C API for working with Android Boot Image format +------------------------------------------------ + +.. kernel-doc:: common/image-android.c + :internal: + +References +---------- + +.. [1] https://source.android.com/devices/bootloader/boot-image-header +.. [2] https://source.android.com/devices/bootloader/recovery-image +.. [3] https://source.android.com/devices/architecture/dto/partitions +.. [4] :doc:`bcb` +.. [5] :doc:`ab` +.. [6] :doc:`avb2` +.. [7] https://source.android.com/devices/bootloader +.. [8] https://connect.linaro.org/resources/san19/san19-217/ diff --git a/roms/u-boot/doc/android/fastboot-protocol.rst b/roms/u-boot/doc/android/fastboot-protocol.rst new file mode 100644 index 000000000..e8cbd7f24 --- /dev/null +++ b/roms/u-boot/doc/android/fastboot-protocol.rst @@ -0,0 +1,178 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +FastBoot Version 0.4 +==================== + +The fastboot protocol is a mechanism for communicating with bootloaders +over USB. It is designed to be very straightforward to implement, to +allow it to be used across a wide range of devices and from hosts running +Linux, Windows, or OSX. + +Basic Requirements +------------------ + +* Two bulk endpoints (in, out) are required +* Max packet size must be 64 bytes for full-speed and 512 bytes for + high-speed USB +* The protocol is entirely host-driven and synchronous (unlike the + multi-channel, bi-directional, asynchronous ADB protocol) + + +Transport and Framing +--------------------- + +1. Host sends a command, which is an ascii string in a single + packet no greater than 64 bytes. + +2. Client response with a single packet no greater than 64 bytes. + The first four bytes of the response are "OKAY", "FAIL", "DATA", + or "INFO". Additional bytes may contain an (ascii) informative + message. + + a. INFO -> the remaining 60 bytes are an informative message + (providing progress or diagnostic messages). They should + be displayed and then step #2 repeats + + b. FAIL -> the requested command failed. The remaining 60 bytes + of the response (if present) provide a textual failure message + to present to the user. Stop. + + c. OKAY -> the requested command completed successfully. Go to #5 + + d. DATA -> the requested command is ready for the data phase. + A DATA response packet will be 12 bytes long, in the form of + DATA00000000 where the 8 digit hexidecimal number represents + the total data size to transfer. + +3. Data phase. Depending on the command, the host or client will + send the indicated amount of data. Short packets are always + acceptable and zero-length packets are ignored. This phase continues + until the client has sent or received the number of bytes indicated + in the "DATA" response above. + +4. Client responds with a single packet no greater than 64 bytes. + The first four bytes of the response are "OKAY", "FAIL", or "INFO". + Similar to #2: + + a. INFO -> display the remaining 60 bytes and return to #4 + + b. FAIL -> display the remaining 60 bytes (if present) as a failure + reason and consider the command failed. Stop. + + c. OKAY -> success. Go to #5 + +5. Success. Stop. + + +Example Session +--------------- + +.. code-block:: none + + Host: "getvar:version" request version variable + + Client: "OKAY0.4" return version "0.4" + + Host: "getvar:nonexistant" request some undefined variable + + Client: "OKAY" return value "" + + Host: "download:00001234" request to send 0x1234 bytes of data + + Client: "DATA00001234" ready to accept data + + Host: < 0x1234 bytes > send data + + Client: "OKAY" success + + Host: "flash:bootloader" request to flash the data to the bootloader + + Client: "INFOerasing flash" indicate status / progress + "INFOwriting flash" + "OKAY" indicate success + + Host: "powerdown" send a command + + Client: "FAILunknown command" indicate failure + + +Command Reference +----------------- + +* Command parameters are indicated by printf-style escape sequences. + +* Commands are ascii strings and sent without the quotes (which are + for illustration only here) and without a trailing 0 byte. + +* Commands that begin with a lowercase letter are reserved for this + specification. OEM-specific commands should not begin with a + lowercase letter, to prevent incompatibilities with future specs. + +.. code-block:: none + + "getvar:%s" Read a config/version variable from the bootloader. + The variable contents will be returned after the + OKAY response. + + "download:%08x" Write data to memory which will be later used + by "boot", "ramdisk", "flash", etc. The client + will reply with "DATA%08x" if it has enough + space in RAM or "FAIL" if not. The size of + the download is remembered. + + "verify:%08x" Send a digital signature to verify the downloaded + data. Required if the bootloader is "secure" + otherwise "flash" and "boot" will be ignored. + + "flash:%s" Write the previously downloaded image to the + named partition (if possible). + + "erase:%s" Erase the indicated partition (clear to 0xFFs) + + "boot" The previously downloaded data is a boot.img + and should be booted according to the normal + procedure for a boot.img + + "continue" Continue booting as normal (if possible) + + "reboot" Reboot the device. + + "reboot-bootloader" Reboot back into the bootloader. + Useful for upgrade processes that require upgrading + the bootloader and then upgrading other partitions + using the new bootloader. + + "powerdown" Power off the device. + + "ucmd" execute any bootloader command and wait until it + finishs. + + "acmd" execute any bootloader command, do not wait. + +Client Variables +---------------- + +The ``getvar:%s`` command is used to read client variables which +represent various information about the device and the software +on it. + +The various currently defined names are:: + + version Version of FastBoot protocol supported. + It should be "0.3" for this document. + + version-bootloader Version string for the Bootloader. + + version-baseband Version string of the Baseband Software + + product Name of the product + + serialno Product serial number + + secure If the value is "yes", this is a secure + bootloader requiring a signature before + it will install or boot images. + +Names starting with a lowercase character are reserved by this +specification. OEM-specific names should not start with lowercase +characters. diff --git a/roms/u-boot/doc/android/fastboot.rst b/roms/u-boot/doc/android/fastboot.rst new file mode 100644 index 000000000..7611f0703 --- /dev/null +++ b/roms/u-boot/doc/android/fastboot.rst @@ -0,0 +1,234 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +Android Fastboot +================ + +Overview +-------- + +The protocol that is used over USB and UDP is described in [1]_. + +The current implementation supports the following standard commands: + +- ``boot`` +- ``continue`` +- ``download`` +- ``erase`` (if enabled) +- ``flash`` (if enabled) +- ``getvar`` +- ``reboot`` +- ``reboot-bootloader`` +- ``set_active`` (only a stub implementation which always succeeds) +- ``ucmd`` (if enabled) +- ``acmd`` (if enabled) + +The following OEM commands are supported (if enabled): + +- ``oem format`` - this executes ``gpt write mmc %x $partitions`` +- ``oem partconf`` - this executes ``mmc partconf %x <arg> 0`` to configure eMMC + with <arg> = boot_ack boot_partition +- ``oem bootbus`` - this executes ``mmc bootbus %x %s`` to configure eMMC + +Support for both eMMC and NAND devices is included. + +Client installation +------------------- + +The counterpart to this is the fastboot client which can be found in +Android's ``platform/system/core`` repository in the fastboot +folder. It runs on Windows, Linux and OSX. The fastboot client is +part of the Android SDK Platform-Tools and can be downloaded from [2]_. + +Board specific +-------------- + +USB configuration +^^^^^^^^^^^^^^^^^ + +The fastboot gadget relies on the USB download gadget, so the following +options must be configured: + +:: + + CONFIG_USB_GADGET_DOWNLOAD + CONFIG_USB_GADGET_VENDOR_NUM + CONFIG_USB_GADGET_PRODUCT_NUM + CONFIG_USB_GADGET_MANUFACTURER + +NOTE: The ``CONFIG_USB_GADGET_VENDOR_NUM`` must be one of the numbers +supported by the fastboot client. The list of vendor IDs supported can +be found in the fastboot client source code. + +General configuration +^^^^^^^^^^^^^^^^^^^^^ + +The fastboot protocol requires a large memory buffer for +downloads. This buffer should be as large as possible for a +platform. The location of the buffer and size are set with +``CONFIG_FASTBOOT_BUF_ADDR`` and ``CONFIG_FASTBOOT_BUF_SIZE``. These +may be overridden on the fastboot command line using ``-l`` and +``-s``. + +Fastboot environment variables +------------------------------ + +Partition aliases +^^^^^^^^^^^^^^^^^ + +Fastboot partition aliases can also be defined for devices where GPT +limitations prevent user-friendly partition names such as ``boot``, ``system`` +and ``cache``. Or, where the actual partition name doesn't match a standard +partition name used commonly with fastboot. + +The current implementation checks aliases when accessing partitions by +name (flash_write and erase functions). To define a partition alias +add an environment variable similar to:: + + fastboot_partition_alias_<alias partition name>=<actual partition name> + +for example:: + + fastboot_partition_alias_boot=LNX + +Raw partition descriptors +^^^^^^^^^^^^^^^^^^^^^^^^^ + +In cases where no partition table is present, a raw partition descriptor can be +defined, specifying the offset, size, and optionally the MMC hardware partition +number for a given partition name. + +This is useful when using fastboot to flash files (e.g. SPL or U-Boot) to a +specific offset in the eMMC boot partition, without having to update the entire +boot partition. + +To define a raw partition descriptor, add an environment variable similar to:: + + fastboot_raw_partition_<raw partition name>=<offset> <size> [mmcpart <num>] + +for example:: + + fastboot_raw_partition_boot=0x100 0x1f00 mmcpart 1 + +Variable overrides +^^^^^^^^^^^^^^^^^^ + +Variables retrived through ``getvar`` can be overridden by defining +environment variables of the form ``fastboot.<variable>``. These are +looked up first so can be used to override values which would +otherwise be returned. Using this mechanism you can also return types +for NAND filesystems, as the fully parameterised variable is looked +up, e.g.:: + + fastboot.partition-type:boot=jffs2 + +Boot command +^^^^^^^^^^^^ + +When executing the fastboot ``boot`` command, if ``fastboot_bootcmd`` is set +then that will be executed in place of ``bootm <CONFIG_FASTBOOT_BUF_ADDR>``. + +Partition Names +--------------- + +The Fastboot implementation in U-Boot allows to write images into disk +partitions. Target partitions are referred on the host computer by +their names. + +For GPT/EFI the respective partition name is used. + +For MBR the partitions are referred by generic names according to the +following schema:: + + <device type><device index letter><partition index> + +Example: ``hda3``, ``sdb1``, ``usbda1``. + +The device type is as follows: + + * IDE, ATAPI and SATA disks: ``hd`` + * SCSI disks: ``sd`` + * USB media: ``usbd`` + * MMC and SD cards: ``mmcsd`` + * Disk on chip: ``docd`` + * other: ``xx`` + +The device index starts from ``a`` and refers to the interface (e.g. USB +controller, SD/MMC controller) or disk index. The partition index starts +from ``1`` and describes the partition number on the particular device. + +Alternatively, partition types may be specified using :ref:`U-Boot's partition +syntax <partitions>`. This allows specifying partitions like ``0.1``, +``0#boot``, or ``:3``. The interface is always ``mmc``. + +Writing Partition Table +----------------------- + +Fastboot also allows to write the partition table to the media. This can be +done by writing the respective partition table image to a special target +"gpt" or "mbr". These names can be customized by defining the following +configuration options: + +:: + + CONFIG_FASTBOOT_GPT_NAME + CONFIG_FASTBOOT_MBR_NAME + +In Action +--------- + +Enter into fastboot by executing the fastboot command in U-Boot for either USB:: + + => fastboot usb 0 + +or UDP:: + + => fastboot udp + link up on port 0, speed 100, full duplex + Using ethernet@4a100000 device + Listening for fastboot command on 192.168.0.102 + +On the client side you can fetch the bootloader version for instance:: + + $ fastboot getvar version-bootloader + version-bootloader: U-Boot 2019.07-rc4-00240-g00c9f2a2ec + Finished. Total time: 0.005s + +or initiate a reboot:: + + $ fastboot reboot + +and once the client comes back, the board should reset. + +You can also specify a kernel image to boot. You have to either specify +the an image in Android format *or* pass a binary kernel and let the +fastboot client wrap the Android suite around it. On OMAP for instance you +take zImage kernel and pass it to the fastboot client:: + + $ fastboot -b 0x80000000 -c "console=ttyO2 earlyprintk root=/dev/ram0 mem=128M" boot zImage + creating boot image... + creating boot image - 1847296 bytes + downloading 'boot.img'... + OKAY [ 2.766s] + booting... + OKAY [ -0.000s] + finished. total time: 2.766s + +and on the U-Boot side you should see:: + + Starting download of 1847296 bytes + ........................................................ + downloading of 1847296 bytes finished + Booting kernel.. + ## Booting Android Image at 0x81000000 ... + Kernel load addr 0x80008000 size 1801 KiB + Kernel command line: console=ttyO2 earlyprintk root=/dev/ram0 mem=128M + Loading Kernel Image ... OK + OK + + Starting kernel ... + +References +---------- + +.. [1] :doc:`fastboot-protocol` +.. [2] https://developer.android.com/studio/releases/platform-tools diff --git a/roms/u-boot/doc/android/index.rst b/roms/u-boot/doc/android/index.rst new file mode 100644 index 000000000..225d6f125 --- /dev/null +++ b/roms/u-boot/doc/android/index.rst @@ -0,0 +1,14 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +Android-specific doc +==================== + +.. toctree:: + :maxdepth: 2 + + ab + avb2 + bcb + boot-image + fastboot-protocol + fastboot diff --git a/roms/u-boot/doc/api/dfu.rst b/roms/u-boot/doc/api/dfu.rst new file mode 100644 index 000000000..5bd9e292a --- /dev/null +++ b/roms/u-boot/doc/api/dfu.rst @@ -0,0 +1,7 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +Device firmware update +====================== + +.. kernel-doc:: include/dfu.h + :internal: diff --git a/roms/u-boot/doc/api/efi.rst b/roms/u-boot/doc/api/efi.rst new file mode 100644 index 000000000..cb2a1c897 --- /dev/null +++ b/roms/u-boot/doc/api/efi.rst @@ -0,0 +1,176 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +UEFI subsystem +============== + +Lauching UEFI images +-------------------- + +Bootefi command +~~~~~~~~~~~~~~~ + +The bootefi command is used to start UEFI applications or to install UEFI +drivers. It takes two parameters + + bootefi <image address> [fdt address] + +* image address - the memory address of the UEFI binary +* fdt address - the memory address of the flattened device tree + +The environment variable 'bootargs' is passed as load options in the UEFI system +table. The Linux kernel EFI stub uses the load options as command line +arguments. + +.. kernel-doc:: cmd/bootefi.c + :internal: + +Boot manager +~~~~~~~~~~~~ + +The UEFI specification foresees to define boot entries and boot sequence via UEFI +variables. Booting according to these variables is possible via + + bootefi bootmgr [fdt address] + +* fdt address - the memory address of the flattened device tree + +The relevant variables are: + +* Boot0000-BootFFFF define boot entries +* BootNext specifies next boot option to be booted +* BootOrder specifies in which sequence the boot options shall be tried if + BootNext is not defined or booting via BootNext fails + +.. kernel-doc:: lib/efi_loader/efi_bootmgr.c + :internal: + +Efidebug command +~~~~~~~~~~~~~~~~ + +The efidebug command is used to set and display boot options as well as to +display information about internal data of the UEFI subsystem (devices, +drivers, handles, loaded images, and the memory map). + +.. kernel-doc:: cmd/efidebug.c + :internal: + +Initialization of the UEFI sub-system +------------------------------------- + +.. kernel-doc:: lib/efi_loader/efi_setup.c + :internal: + +Boot services +------------- + +.. kernel-doc:: lib/efi_loader/efi_boottime.c + :internal: + +Image relocation +~~~~~~~~~~~~~~~~ + +.. kernel-doc:: lib/efi_loader/efi_image_loader.c + :internal: + +Memory services +~~~~~~~~~~~~~~~ + +.. kernel-doc:: lib/efi_loader/efi_memory.c + :internal: + +SetWatchdogTimer service +~~~~~~~~~~~~~~~~~~~~~~~~ + +.. kernel-doc:: lib/efi_loader/efi_watchdog.c + :internal: + +Runtime services +---------------- + +.. kernel-doc:: lib/efi_loader/efi_runtime.c + :internal: + +Variable services +~~~~~~~~~~~~~~~~~ + +.. kernel-doc:: include/efi_variable.h + :internal: +.. kernel-doc:: lib/efi_loader/efi_variable.c + :internal: + +UEFI drivers +------------ + +UEFI driver uclass +~~~~~~~~~~~~~~~~~~ +.. kernel-doc:: lib/efi_driver/efi_uclass.c + :internal: + +Block device driver +~~~~~~~~~~~~~~~~~~~ + +.. kernel-doc:: lib/efi_driver/efi_block_device.c + :internal: + +Protocols +--------- + +Block IO protocol +~~~~~~~~~~~~~~~~~ + +.. kernel-doc:: lib/efi_loader/efi_disk.c + :internal: + +File protocol +~~~~~~~~~~~~~ + +.. kernel-doc:: lib/efi_loader/efi_file.c + :internal: + +Graphical output protocol +~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. kernel-doc:: lib/efi_loader/efi_gop.c + :internal: + +Load file 2 protocol +~~~~~~~~~~~~~~~~~~~~ + +The load file 2 protocol can be used by the Linux kernel to load the initial +RAM disk. U-Boot can be configured to provide an implementation. + +.. kernel-doc:: lib/efi_loader/efi_load_initrd.c + :internal: + +Network protocols +~~~~~~~~~~~~~~~~~ + +.. kernel-doc:: lib/efi_loader/efi_net.c + :internal: + +Random number generator protocol +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. kernel-doc:: lib/efi_loader/efi_rng.c + :internal: + +Text IO protocols +~~~~~~~~~~~~~~~~~ + +.. kernel-doc:: lib/efi_loader/efi_console.c + :internal: + +Unicode Collation protocol +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. kernel-doc:: lib/efi_loader/efi_unicode_collation.c + :internal: + +Unit testing +------------ + +The following library functions are provided to support writing UEFI unit tests. +The should not be used elsewhere. + +.. kernel-doc:: include/efi_selftest.h + :internal: diff --git a/roms/u-boot/doc/api/getopt.rst b/roms/u-boot/doc/api/getopt.rst new file mode 100644 index 000000000..773f79aeb --- /dev/null +++ b/roms/u-boot/doc/api/getopt.rst @@ -0,0 +1,8 @@ +.. SPDX-License-Identifier: GPL-2.0+ +.. Copyright (C) 2020 Sean Anderson <seanga2@gmail.com> + +Option Parsing +============== + +.. kernel-doc:: include/getopt.h + :internal: diff --git a/roms/u-boot/doc/api/index.rst b/roms/u-boot/doc/api/index.rst new file mode 100644 index 000000000..ea02aa571 --- /dev/null +++ b/roms/u-boot/doc/api/index.rst @@ -0,0 +1,19 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +U-Boot API documentation +======================== + +.. toctree:: + :maxdepth: 2 + + dfu + efi + getopt + linker_lists + logging + pinctrl + rng + sandbox + serial + timer + unicode diff --git a/roms/u-boot/doc/api/linker_lists.rst b/roms/u-boot/doc/api/linker_lists.rst new file mode 100644 index 000000000..7063fdc83 --- /dev/null +++ b/roms/u-boot/doc/api/linker_lists.rst @@ -0,0 +1,159 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +Linker-Generated Arrays +======================= + +A linker list is constructed by grouping together linker input +sections, each containing one entry of the list. Each input section +contains a constant initialized variable which holds the entry's +content. Linker list input sections are constructed from the list +and entry names, plus a prefix which allows grouping all lists +together. Assuming _list and _entry are the list and entry names, +then the corresponding input section name is + +:: + + .u_boot_list_ + 2_ + @_list + _2_ + @_entry + +and the C variable name is + +:: + + _u_boot_list + _2_ + @_list + _2_ + @_entry + +This ensures uniqueness for both input section and C variable name. + +Note that the names differ only in the first character, "." for the +section and "_" for the variable, so that the linker cannot confuse +section and symbol names. From now on, both names will be referred +to as + +:: + + %u_boot_list_ + 2_ + @_list + _2_ + @_entry + +Entry variables need never be referred to directly. + +The naming scheme for input sections allows grouping all linker lists +into a single linker output section and grouping all entries for a +single list. + +Note the two '_2_' constant components in the names: their presence +allows putting a start and end symbols around a list, by mapping +these symbols to sections names with components "1" (before) and +"3" (after) instead of "2" (within). +Start and end symbols for a list can generally be defined as + +:: + + %u_boot_list_2_ + @_list + _1_... + %u_boot_list_2_ + @_list + _3_... + +Start and end symbols for the whole of the linker lists area can be +defined as + +:: + + %u_boot_list_1_... + %u_boot_list_3_... + +Here is an example of the sorted sections which result from a list +"array" made up of three entries : "first", "second" and "third", +iterated at least once. + +:: + + .u_boot_list_2_array_1 + .u_boot_list_2_array_2_first + .u_boot_list_2_array_2_second + .u_boot_list_2_array_2_third + .u_boot_list_2_array_3 + +If lists must be divided into sublists (e.g. for iterating only on +part of a list), one can simply give the list a name of the form +'outer_2_inner', where 'outer' is the global list name and 'inner' +is the sub-list name. Iterators for the whole list should use the +global list name ("outer"); iterators for only a sub-list should use +the full sub-list name ("outer_2_inner"). + +Here is an example of the sections generated from a global list +named "drivers", two sub-lists named "i2c" and "pci", and iterators +defined for the whole list and each sub-list: + +:: + + %u_boot_list_2_drivers_1 + %u_boot_list_2_drivers_2_i2c_1 + %u_boot_list_2_drivers_2_i2c_2_first + %u_boot_list_2_drivers_2_i2c_2_first + %u_boot_list_2_drivers_2_i2c_2_second + %u_boot_list_2_drivers_2_i2c_2_third + %u_boot_list_2_drivers_2_i2c_3 + %u_boot_list_2_drivers_2_pci_1 + %u_boot_list_2_drivers_2_pci_2_first + %u_boot_list_2_drivers_2_pci_2_second + %u_boot_list_2_drivers_2_pci_2_third + %u_boot_list_2_drivers_2_pci_3 + %u_boot_list_2_drivers_3 + +Alignment issues +---------------- + +The linker script uses alphabetic sorting to group the different linker +lists together. Each group has its own struct and potentially its own +alignment. But when the linker packs the structs together it cannot ensure +that a linker list starts on the expected alignment boundary. + +For example, if the first list has a struct size of 8 and we place 3 of +them in the image, that means that the next struct will start at offset +0x18 from the start of the linker_list section. If the next struct has +a size of 16 then it will start at an 8-byte aligned offset, but not a +16-byte aligned offset. + +With sandbox on x86_64, a reference to a linker list item using +ll_entry_get() can force alignment of that particular linker_list item, +if it is in the same file as the linker_list item is declared. + +Consider this example, where struct driver is 0x80 bytes:: + + ll_entry_declare(struct driver, fred, driver) + + ... + + void *p = ll_entry_get(struct driver, fred, driver) + +If these two lines of code are in the same file, then the entry is forced +to be aligned at the 'struct driver' alignment, which is 16 bytes. If the +second line of code is in a different file, then no action is taken, since +the compiler cannot update the alignment of the linker_list item. + +In the first case, an 8-byte 'fill' region is added:: + + .u_boot_list_2_driver_2_testbus_drv + 0x0000000000270018 0x80 test/built-in.o + 0x0000000000270018 _u_boot_list_2_driver_2_testbus_drv + .u_boot_list_2_driver_2_testfdt1_drv + 0x0000000000270098 0x80 test/built-in.o + 0x0000000000270098 _u_boot_list_2_driver_2_testfdt1_drv + *fill* 0x0000000000270118 0x8 + .u_boot_list_2_driver_2_testfdt_drv + 0x0000000000270120 0x80 test/built-in.o + 0x0000000000270120 _u_boot_list_2_driver_2_testfdt_drv + .u_boot_list_2_driver_2_testprobe_drv + 0x00000000002701a0 0x80 test/built-in.o + 0x00000000002701a0 _u_boot_list_2_driver_2_testprobe_drv + +With this, the linker_list no-longer works since items after testfdt1_drv +are not at the expected address. + +Ideally we would have a way to tell gcc not to align structs in this way. +It is not clear how we could do this, and in any case it would require us +to adjust every struct used by the linker_list feature. + +The simplest fix seems to be to force each separate linker_list to start +on the largest possible boundary that can be required by the compiler. This +is the purpose of CONFIG_LINKER_LIST_ALIGN + + +.. kernel-doc:: include/linker_lists.h + :internal: diff --git a/roms/u-boot/doc/api/logging.rst b/roms/u-boot/doc/api/logging.rst new file mode 100644 index 000000000..1e6cbc493 --- /dev/null +++ b/roms/u-boot/doc/api/logging.rst @@ -0,0 +1,6 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +Logging API +=========== + +.. kernel-doc:: include/log.h diff --git a/roms/u-boot/doc/api/pinctrl.rst b/roms/u-boot/doc/api/pinctrl.rst new file mode 100644 index 000000000..043bd57ef --- /dev/null +++ b/roms/u-boot/doc/api/pinctrl.rst @@ -0,0 +1,7 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +Pinctrl and Pinmux +================== + +.. kernel-doc:: include/dm/pinctrl.h + :internal: diff --git a/roms/u-boot/doc/api/rng.rst b/roms/u-boot/doc/api/rng.rst new file mode 100644 index 000000000..b826d4fd4 --- /dev/null +++ b/roms/u-boot/doc/api/rng.rst @@ -0,0 +1,17 @@ +.. SPDX-License-Identifier: GPL-2.0+ +.. Copyright (c) 2018 Heinrich Schuchardt + +Random number generation +======================== + +Hardware random number generation +--------------------------------- + +.. kernel-doc:: include/rng.h + :internal: + +Pseudo random number generation +------------------------------- + +.. kernel-doc:: include/rand.h + :internal: diff --git a/roms/u-boot/doc/api/sandbox.rst b/roms/u-boot/doc/api/sandbox.rst new file mode 100644 index 000000000..724776399 --- /dev/null +++ b/roms/u-boot/doc/api/sandbox.rst @@ -0,0 +1,9 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +Sandbox +======= + +The following API routines are used to implement the U-Boot sandbox. + +.. kernel-doc:: include/os.h + :internal: diff --git a/roms/u-boot/doc/api/serial.rst b/roms/u-boot/doc/api/serial.rst new file mode 100644 index 000000000..ed34e592a --- /dev/null +++ b/roms/u-boot/doc/api/serial.rst @@ -0,0 +1,7 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +Serial system +============= + +.. kernel-doc:: drivers/serial/serial.c + :internal: diff --git a/roms/u-boot/doc/api/timer.rst b/roms/u-boot/doc/api/timer.rst new file mode 100644 index 000000000..b0695174d --- /dev/null +++ b/roms/u-boot/doc/api/timer.rst @@ -0,0 +1,8 @@ +.. SPDX-License-Identifier: GPL-2.0+ +.. Copyright (C) 2020 Sean Anderson <seanga2@gmail.com> + +Timer Subsystem +=============== + +.. kernel-doc:: include/timer.h + :internal: diff --git a/roms/u-boot/doc/api/unicode.rst b/roms/u-boot/doc/api/unicode.rst new file mode 100644 index 000000000..3fb6745f8 --- /dev/null +++ b/roms/u-boot/doc/api/unicode.rst @@ -0,0 +1,7 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +Unicode support +=============== + +.. kernel-doc:: include/charset.h + :internal: diff --git a/roms/u-boot/doc/arch/arc.rst b/roms/u-boot/doc/arch/arc.rst new file mode 100644 index 000000000..f8e04a34f --- /dev/null +++ b/roms/u-boot/doc/arch/arc.rst @@ -0,0 +1,32 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +ARC +=== + +Synopsys' DesignWare(r) ARC(r) Processors are a family of 32-bit CPUs +that SoC designers can optimize for a wide range of uses, from deeply embedded +to high-performance host applications. + +More information on ARC cores avaialble here: +http://www.synopsys.com/IP/ProcessorIP/ARCProcessors/Pages/default.aspx + +Designers can differentiate their products by using patented configuration +technology to tailor each ARC processor instance to meet specific performance, +power and area requirements. + +The DesignWare ARC processors are also extendable, allowing designers to add +their own custom instructions that dramatically increase performance. + +Synopsys' ARC processors have been used by over 170 customers worldwide who +collectively ship more than 1 billion ARC-based chips annually. + +All DesignWare ARC processors utilize a 16-/32-bit ISA that provides excellent +performance and code density for embedded and host SoC applications. + +The RISC microprocessors are synthesizable and can be implemented in any foundry +or process, and are supported by a complete suite of development tools. + +The ARC GNU toolchain with support for all ARC Processors can be downloaded +from here (available pre-built toolchains as well): + +https://github.com/foss-for-synopsys-dwc-arc-processors/toolchain/releases diff --git a/roms/u-boot/doc/arch/arm64.rst b/roms/u-boot/doc/arch/arm64.rst new file mode 100644 index 000000000..80498f6f6 --- /dev/null +++ b/roms/u-boot/doc/arch/arm64.rst @@ -0,0 +1,59 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +ARM64 +===== + +Summary +------- +The initial arm64 U-Boot port was developed before hardware was available, +so the first supported platforms were the Foundation and Fast Model for ARMv8. +These days U-Boot runs on a variety of 64-bit capable ARM hardware, from +embedded development boards to servers. + +Notes +----- + +1. U-Boot can run at any exception level it is entered in, it is + recommened to enter it in EL3 if U-Boot takes some responsibilities of a + classical firmware (like initial hardware setup, CPU errata workarounds + or SMP bringup). U-Boot can be entered in EL2 when its main purpose is + that of a boot loader. It can drop to lower exception levels before + entering the OS. + +2. U-Boot for arm64 is compiled with AArch64-gcc. AArch64-gcc + use rela relocation format, a tool(tools/relocate-rela) by Scott Wood + is used to encode the initial addend of rela to u-boot.bin. After running, + the U-Boot will be relocated to destination again. + +3. Earlier Linux kernel versions required the FDT to be placed at a + 2 MB boundary and within the same 512 MB section as the kernel image, + resulting in fdt_high to be defined specially. + Since kernel version 4.2 Linux is more relaxed about the DT location, so it + can be placed anywhere in memory. + Please reference linux/Documentation/arm64/booting.txt for detail. + +4. Spin-table is used to wake up secondary processors. One location + (or per processor location) is defined to hold the kernel entry point + for secondary processors. It must be ensured that the location is + accessible and zero immediately after secondary processor + enter slave_cpu branch execution in start.S. The location address + is encoded in cpu node of DTS. Linux kernel store the entry point + of secondary processors to it and send event to wakeup secondary + processors. + Please reference linux/Documentation/arm64/booting.txt for detail. + +5. Generic board is supported. + +6. CONFIG_ARM64 instead of CONFIG_ARMV8 is used to distinguish aarch64 and + aarch32 specific codes. + + +Contributors +------------ + * Tom Rini <trini@ti.com> + * Scott Wood <scottwood@freescale.com> + * York Sun <yorksun@freescale.com> + * Simon Glass <sjg@chromium.org> + * Sharma Bhupesh <bhupesh.sharma@freescale.com> + * Rob Herring <robherring2@gmail.com> + * Sergey Temerkhanov <s.temerkhanov@gmail.com> diff --git a/roms/u-boot/doc/arch/index.rst b/roms/u-boot/doc/arch/index.rst new file mode 100644 index 000000000..369d8eeb6 --- /dev/null +++ b/roms/u-boot/doc/arch/index.rst @@ -0,0 +1,18 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +Architecture-specific doc +========================= + +.. toctree:: + :maxdepth: 2 + + arc + arm64 + m68k + mips + nds32 + nios2 + sandbox + sh + x86 + xtensa diff --git a/roms/u-boot/doc/arch/m68k.rst b/roms/u-boot/doc/arch/m68k.rst new file mode 100644 index 000000000..44e1a5dfa --- /dev/null +++ b/roms/u-boot/doc/arch/m68k.rst @@ -0,0 +1,170 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +M68K / ColdFire +=============== + +History +------- +* November 02, 2017 Angelo Dureghello <angelo@sysam.it> +* August 08, 2005 Jens Scharsig <esw@bus-elektronik.de> + MCF5282 implementation without preloader +* January 12, 2004 <josef.baumgartner@telex.de> + +This file contains status information for the port of U-Boot to the +Motorola ColdFire series of CPUs. + +Overview +-------- + +The ColdFire instruction set is "assembly source" compatible but an evolution +of the original 68000 instruction set. Some not much used instructions has +been removed. The instructions are only 16, 32, or 48 bits long, a +simplification compared to the 68000 series. + +Bernhard Kuhn ported U-Boot 0.4.0 to the Motorola ColdFire architecture. +The patches of Bernhard support the MCF5272 and MCF5282. A great disadvantage +of these patches was that they needed a pre-bootloader to start U-Boot. +Because of this, a new port was created which no longer needs a first stage +booter. + +Thanks mainly to Freescale but also to several other contributors, U-Boot now +supports nearly the entire range of ColdFire processors and their related +development boards. + + +Supported CPU families +---------------------- + +Please "make menuconfig" and select "m68k" or check arch/m68k/cpu to see the +currently supported processor and families. + + +Supported boards +---------------- + +U-Boot supports actually more than 40 ColdFire based boards. +Board configuration can be done trough include/configs/<boardname>.h but the +current recommended method is to use the new and more friendly approach as +the "make menuconfig" way, very similar to the Linux way. + +To know details as memory map, build targets, default setup, etc, of a +specific board please check: + +* include/configs/<boardname>.h + +and/or + +* configs/<boardname>_defconfig + +It is possible to build all ColdFire boards in a single command-line command, +from u-boot root directory, as:: + + ./tools/buildman/buildman m68k + +Build U-Boot for a specific board +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +A bash script similar to the one below may be used: + +.. code-block:: shell + + #!/bin/bash + + export CROSS_COMPILE=/opt/toolchains/m68k/gcc-4.9.0-nolibc/bin/m68k-linux- + + board=M5475DFE + + make distclean + make ${board}_defconfig + make KBUILD_VERBOSE=1 + + +Adopted toolchains +------------------ + +Please check: +https://www.denx.de/wiki/U-Boot/ColdFireNotes + + +ColdFire specific configuration options/settings +------------------------------------------------ + +Configuration to use a pre-loader +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +If U-Boot should be loaded to RAM and started by a pre-loader +CONFIG_MONITOR_IS_IN_RAM must be defined. If it is defined the +initial vector table and basic processor initialization will not +be compiled in. The start address of U-Boot must be adjusted in +the boards config header file (CONFIG_SYS_MONITOR_BASE) and Makefile +(CONFIG_SYS_TEXT_BASE) to the load address. + +ColdFire CPU specific options/settings +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +To specify a CPU model, some defines shoudl be used, i.e.: + +CONFIG_MCF52x2: + defined for all MCF52x2 CPUs +CONFIG_M5272: + defined for all Motorola MCF5272 CPUs + +Other options, generally set inside include/configs/<boardname>.h, they may +apply to one or more cpu for the ColdFire family: + +CONFIG_SYS_MBAR: + defines the base address of the MCF5272 configuration registers +CONFIG_SYS_ENET_BD_BASE: + defines the base address of the FEC buffer descriptors +CONFIG_SYS_SCR: + defines the contents of the System Configuration Register +CONFIG_SYS_SPR: + defines the contents of the System Protection Register +CONFIG_SYS_MFD: + defines the PLL Multiplication Factor Divider + (see table 9-4 of MCF user manual) +CONFIG_SYS_RFD: + defines the PLL Reduce Frequency Devider + (see table 9-4 of MCF user manual) +CONFIG_SYS_CSx_BASE: + defines the base address of chip select x +CONFIG_SYS_CSx_SIZE: + defines the memory size (address range) of chip select x +CONFIG_SYS_CSx_WIDTH: + defines the bus with of chip select x +CONFIG_SYS_CSx_MASK: + defines the mask for the related chip select x +CONFIG_SYS_CSx_RO: + if set to 0 chip select x is read/write else chip select is read only +CONFIG_SYS_CSx_WS: + defines the number of wait states of chip select x +CONFIG_SYS_CACHE_ICACR: + cache-related registers config +CONFIG_SYS_CACHE_DCACR: + cache-related registers config +CONFIG_SYS_CACHE_ACRX: + cache-related registers config +CONFIG_SYS_SDRAM_BASE: + SDRAM config for SDRAM controller-specific registers +CONFIG_SYS_SDRAM_SIZE: + SDRAM config for SDRAM controller-specific registers +CONFIG_SYS_SDRAM_BASEX: + SDRAM config for SDRAM controller-specific registers +CONFIG_SYS_SDRAM_CFG1: + SDRAM config for SDRAM controller-specific registers +CONFIG_SYS_SDRAM_CFG2: + SDRAM config for SDRAM controller-specific registers +CONFIG_SYS_SDRAM_CTRL: + SDRAM config for SDRAM controller-specific registers +CONFIG_SYS_SDRAM_MODE: + SDRAM config for SDRAM controller-specific registers +CONFIG_SYS_SDRAM_EMOD: + SDRAM config for SDRAM controller-specific registers, please + see arch/m68k/cpu/<specific_cpu>/start.S files to see how + these options are used. +CONFIG_MCFUART: + defines enabling of ColdFire UART driver +CONFIG_SYS_UART_PORT: + defines the UART port to be used (only a single UART can be actually enabled) +CONFIG_SYS_SBFHDR_SIZE: + size of the prepended SBF header, if any diff --git a/roms/u-boot/doc/arch/mips.rst b/roms/u-boot/doc/arch/mips.rst new file mode 100644 index 000000000..b8166087d --- /dev/null +++ b/roms/u-boot/doc/arch/mips.rst @@ -0,0 +1,46 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +MIPS +==== + +Notes for the MIPS architecture port of U-Boot + +Toolchains +---------- + + * `ELDK < DULG < DENX <http://www.denx.de/wiki/DULG/ELDK>`_ + * `Embedded Debian -- Cross-development toolchains <http://www.emdebian.org/crosstools.html>`_ + * `Buildroot <http://buildroot.uclibc.org/>`_ + +Known Issues +------------ + + * Cache incoherency issue caused by do_bootelf_exec() at cmd_elf.c + + Cache will be disabled before entering the loaded ELF image without + writing back and invalidating cache lines. This leads to cache + incoherency in most cases, unless the code gets loaded after U-Boot + re-initializes the cache. The more common uImage 'bootm' command does + not suffer this problem. + + [workaround] To avoid this cache incoherency: + - insert flush_cache(all) before calling dcache_disable(), or + - fix dcache_disable() to do both flushing and disabling cache. + + * Note that Linux users need to kill dcache_disable() in do_bootelf_exec() + or override do_bootelf_exec() not to disable I-/D-caches, because most + Linux/MIPS ports don't re-enable caches after entering kernel_entry. + +TODOs +----- + + * Probe CPU types, I-/D-cache and TLB size etc. automatically + * Secondary cache support missing + * Initialize TLB entries redardless of their use + * R2000/R3000 class parts are not supported + * Limited testing across different MIPS variants + * Due to cache initialization issues, the DRAM on board must be + initialized in board specific assembler language before the cache init + code is run -- that is, initialize the DRAM in lowlevel_init(). + * centralize/share more CPU code of MIPS32, MIPS64 and XBurst + * support Qemu Malta diff --git a/roms/u-boot/doc/arch/nds32.rst b/roms/u-boot/doc/arch/nds32.rst new file mode 100644 index 000000000..502397cf7 --- /dev/null +++ b/roms/u-boot/doc/arch/nds32.rst @@ -0,0 +1,101 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +NDS32 +===== + +NDS32 is a new high-performance 32-bit RISC microprocessor core. + +http://www.andestech.com/ + +AndeStar ISA +------------ +AndeStar is a patent-pending 16-bit/32-bit mixed-length instruction set to +achieve optimal system performance, code density, and power efficiency. + +It contains the following features: + - Intermixable 32-bit and 16-bit instruction sets without the need for + mode switch. + - 16-bit instructions as a frequently used subset of 32-bit instructions. + - RISC-style register-based instruction set. + - 32 32-bit General Purpose Registers (GPR). + - Upto 1024 User Special Registers (USR) for existing and extension + instructions. + - Rich load/store instructions for... + - Single memory access with base address update. + - Multiple aligned and unaligned memory accesses for memory copy and stack + operations. + - Data prefetch to improve data cache performance. + - Non-bus locking synchronization instructions. + - PC relative jump and PC read instructions for efficient position independent + code. + - Multiply-add and multiple-sub with 64-bit accumulator. + - Instruction for efficient power management. + - Bi-endian support. + - Three instruction extension space for application acceleration: + - Performance extension. + - Andes future extensions (for floating-point, multimedia, etc.) + - Customer extensions. + +AndesCore CPU +------------- +Andes Technology has 4 families of CPU cores: N12, N10, N9, N8. + +For details about N12 CPU family, please check below N1213 features. +N1213 is a configurable hard/soft core of NDS32's N12 CPU family. + +N1213 Features +^^^^^^^^^^^^^^ + +CPU Core + - 16-/32-bit mixable instruction format. + - 32 general-purpose 32-bit registers. + - 8-stage pipeline. + - Dynamic branch prediction. + - 32/64/128/256 BTB. + - Return address stack (RAS). + - Vector interrupts for internal/external. + interrupt controller with 6 hardware interrupt signals. + - 3 HW-level nested interruptions. + - User and super-user mode support. + - Memory-mapped I/O. + - Address space up to 4GB. + +Memory Management Unit + - TLB + - 4/8-entry fully associative iTLB/dTLB. + - 32/64/128-entry 4-way set-associati.ve main TLB. + - TLB locking support + - Optional hardware page table walker. + - Two groups of page size support. + - 4KB & 1MB. + - 8KB & 1MB. + +Memory Subsystem + - I & D cache. + - Virtually indexed and physically tagged. + - Cache size: 8KB/16KB/32KB/64KB. + - Cache line size: 16B/32B. + - Set associativity: 2-way, 4-way or direct-mapped. + - Cache locking support. + - I & D local memory (LM). + - Size: 4KB to 1MB. + - Bank numbers: 1 or 2. + - Optional 1D/2D DMA engine. + - Internal or external to CPU core. + +Bus Interface + - Synchronous/Asynchronous AHB bus: 0, 1 or 2 ports. + - Synchronous High speed memory port. + (HSMP): 0, 1 or 2 ports. + +Debug + - JTAG debug interface. + - Embedded debug module (EDM). + - Optional embedded program tracer interface. + +Miscellaneous + - Programmable data endian control. + - Performance monitoring mechanism. + +The NDS32 ports of u-boot, the Linux kernel, the GNU toolchain and other +associated software are actively supported by Andes Technology Corporation. diff --git a/roms/u-boot/doc/arch/nios2.rst b/roms/u-boot/doc/arch/nios2.rst new file mode 100644 index 000000000..35defb0af --- /dev/null +++ b/roms/u-boot/doc/arch/nios2.rst @@ -0,0 +1,111 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +Nios II +======= + +Nios II is a 32-bit embedded-processor architecture designed +specifically for the Altera family of FPGAs. + +Please refer to the link for more information on Nios II: +https://www.altera.com/products/processors/overview.html + +Please refer to the link for Linux port and toolchains: +http://rocketboards.org/foswiki/view/Documentation/NiosIILinuxUserManual + +The Nios II port of u-boot is controlled by device tree. Please check +out doc/README.fdt-control. + +To add a new board/configuration (eg, mysystem) to u-boot, you will need +three files. + +1. The device tree source which describes the hardware, dts file: + arch/nios2/dts/mysystem.dts + +2. Default configuration of Kconfig, defconfig file: + configs/mysystem_defconfig + +3. The legacy board header file: + include/configs/mysystem.h + +The device tree source must be generated from your qsys/sopc design +using the sopc2dts tool. Then modified to fit your configuration. + +Please find the sopc2dts download and usage at the wiki: +http://www.alterawiki.com/wiki/Sopc2dts + +.. code-block:: none + + $ java -jar sopc2dts.jar --force-altr -i mysystem.sopcinfo -o mysystem.dts + +You will need to add additional properties to the dts. Please find an +example at, arch/nios2/dts/10m50_devboard.dts. + +1. Add "stdout-path=..." property with your serial path to the chosen + node, like this:: + + chosen { + stdout-path = &uart_0; + }; + +2. If you use SPI/EPCS or I2C, you will need to add aliases to number + the sequence of these devices, like this:: + + aliases { + spi0 = &epcs_controller; + }; + +Next, you will need a default config file. You may start with +10m50_defconfig, modify the options and save it. + +.. code-block:: none + + $ make 10m50_defconfig + $ make menuconfig + $ make savedefconfig + $ cp defconfig configs/mysystem_defconfig + +You will need to change the names of board header file and device tree, +and select the drivers with menuconfig. + +.. code-block:: none + + Nios II architecture ---> + (mysystem) Board header file + Device Tree Control ---> + (mysystem) Default Device Tree for DT control + +There is a selection of "Provider of DTB for DT control" in the Device +Tree Control menu. + + * Separate DTB for DT control, will cat the dtb to end of u-boot + binary, output u-boot-dtb.bin. This should be used for production. + If you use boot copier, like EPCS boot copier, make sure the copier + copies all the u-boot-dtb.bin, not just u-boot.bin. + + * Embedded DTB for DT control, will include the dtb inside the u-boot + binary. This is handy for development, eg, using gdb or nios2-download. + +The last thing, legacy board header file describes those config options +not covered in Kconfig yet. You may copy it from 10m50_devboard.h:: + + $ cp include/configs/10m50_devboard.h include/configs/mysystem.h + +Please change the SDRAM base and size to match your board. The base +should be cached virtual address, for Nios II with MMU it is 0xCxxx_xxxx +to 0xDxxx_xxxx. + +.. code-block:: c + + #define CONFIG_SYS_SDRAM_BASE 0xc8000000 + #define CONFIG_SYS_SDRAM_SIZE 0x08000000 + +You will need to change the environment variables location and setting, +too. You may change other configs to fit your board. + +After all these changes, you may build and test:: + + $ export CROSS_COMPILE=nios2-elf- (or nios2-linux-gnu-) + $ make mysystem_defconfig + $ make + +Enjoy! diff --git a/roms/u-boot/doc/arch/sandbox.rst b/roms/u-boot/doc/arch/sandbox.rst new file mode 100644 index 000000000..e052b6bdb --- /dev/null +++ b/roms/u-boot/doc/arch/sandbox.rst @@ -0,0 +1,519 @@ +.. SPDX-License-Identifier: GPL-2.0+ */ +.. Copyright (c) 2014 The Chromium OS Authors. +.. sectionauthor:: Simon Glass <sjg@chromium.org> + +Sandbox +======= + +Native Execution of U-Boot +-------------------------- + +The 'sandbox' architecture is designed to allow U-Boot to run under Linux on +almost any hardware. To achieve this it builds U-Boot (so far as possible) +as a normal C application with a main() and normal C libraries. + +All of U-Boot's architecture-specific code therefore cannot be built as part +of the sandbox U-Boot. The purpose of running U-Boot under Linux is to test +all the generic code, not specific to any one architecture. The idea is to +create unit tests which we can run to test this upper level code. + +Sandbox allows development of many types of new features in a traditional way, +rather than needing to test each iteration on real hardware. Many U-Boot +features were developed on sandbox, including the core driver model, most +uclasses, verified boot, bloblist, logging and dozens of others. Sandbox has +enabled many large-scale code refactors as well. + +CONFIG_SANDBOX is defined when building a native board. + +The board name is 'sandbox' but the vendor name is unset, so there is a +single board in board/sandbox. + +CONFIG_SANDBOX_BIG_ENDIAN should be defined when running on big-endian +machines. + +There are two versions of the sandbox: One using 32-bit-wide integers, and one +using 64-bit-wide integers. The 32-bit version can be build and run on either +32 or 64-bit hosts by either selecting or deselecting CONFIG_SANDBOX_32BIT; by +default, the sandbox it built for a 32-bit host. The sandbox using 64-bit-wide +integers can only be built on 64-bit hosts. + +Note that standalone/API support is not available at present. + + +Prerequisites +------------- + +Here are some packages that are worth installing if you are doing sandbox or +tools development in U-Boot: + + python3-pytest lzma lzma-alone lz4 python3 python3-virtualenv + libssl1.0-dev + + +Basic Operation +--------------- + +To run sandbox U-Boot use something like:: + + make sandbox_defconfig all + ./u-boot + +Note: If you get errors about 'sdl-config: Command not found' you may need to +install libsdl2.0-dev or similar to get SDL support. Alternatively you can +build sandbox without SDL (i.e. no display/keyboard support) by removing +the CONFIG_SANDBOX_SDL line in include/configs/sandbox.h or using:: + + make sandbox_defconfig all NO_SDL=1 + ./u-boot + +U-Boot will start on your computer, showing a sandbox emulation of the serial +console:: + + U-Boot 2014.04 (Mar 20 2014 - 19:06:00) + + DRAM: 128 MiB + Using default environment + + In: serial + Out: lcd + Err: lcd + => + +You can issue commands as your would normally. If the command you want is +not supported you can add it to include/configs/sandbox.h. + +To exit, type 'poweroff' or press Ctrl-C. + + +Console / LCD support +--------------------- + +Assuming that CONFIG_SANDBOX_SDL is defined when building, you can run the +sandbox with LCD and keyboard emulation, using something like:: + + ./u-boot -d u-boot.dtb -l + +This will start U-Boot with a window showing the contents of the LCD. If +that window has the focus then you will be able to type commands as you +would on the console. You can adjust the display settings in the device +tree file - see arch/sandbox/dts/sandbox.dts. + + +Command-line Options +-------------------- + +Various options are available, mostly for test purposes. Use -h to see +available options. Some of these are described below: + +-t, --terminal <arg> + The terminal is normally in what is called 'raw-with-sigs' mode. This means + that you can use arrow keys for command editing and history, but if you + press Ctrl-C, U-Boot will exit instead of handling this as a keypress. + Other options are 'raw' (so Ctrl-C is handled within U-Boot) and 'cooked' + (where the terminal is in cooked mode and cursor keys will not work, Ctrl-C + will exit). + +-l + Show the LCD emulation window. + +-d <device_tree> + A device tree binary file can be provided with -d. If you edit the source + (it is stored at arch/sandbox/dts/sandbox.dts) you must rebuild U-Boot to + recreate the binary file. + +-D + To use the default device tree, use -D. + +-T + To use the test device tree, use -T. + +-c [<cmd>;]<cmd> + To execute commands directly, use the -c option. You can specify a single + command, or multiple commands separated by a semicolon, as is normal in + U-Boot. Be careful with quoting as the shell will normally process and + swallow quotes. When -c is used, U-Boot exits after the command is complete, + but you can force it to go to interactive mode instead with -i. + +-i + Go to interactive mode after executing the commands specified by -c. + +Environment Variables +--------------------- + +UBOOT_SB_TIME_OFFSET + This environment variable stores the offset of the emulated real time clock + to the host's real time clock in seconds. The offset defaults to zero. + +Memory Emulation +---------------- + +Memory emulation is supported, with the size set by CONFIG_SYS_SDRAM_SIZE. +The -m option can be used to read memory from a file on start-up and write +it when shutting down. This allows preserving of memory contents across +test runs. You can tell U-Boot to remove the memory file after it is read +(on start-up) with the --rm_memory option. + +To access U-Boot's emulated memory within the code, use map_sysmem(). This +function is used throughout U-Boot to ensure that emulated memory is used +rather than the U-Boot application memory. This provides memory starting +at 0 and extending to the size of the emulation. + + +Storing State +------------- + +With sandbox you can write drivers which emulate the operation of drivers on +real devices. Some of these drivers may want to record state which is +preserved across U-Boot runs. This is particularly useful for testing. For +example, the contents of a SPI flash chip should not disappear just because +U-Boot exits. + +State is stored in a device tree file in a simple format which is driver- +specific. You then use the -s option to specify the state file. Use -r to +make U-Boot read the state on start-up (otherwise it starts empty) and -w +to write it on exit (otherwise the stored state is left unchanged and any +changes U-Boot made will be lost). You can also use -n to tell U-Boot to +ignore any problems with missing state. This is useful when first running +since the state file will be empty. + +The device tree file has one node for each driver - the driver can store +whatever properties it likes in there. See 'Writing Sandbox Drivers' below +for more details on how to get drivers to read and write their state. + + +Running and Booting +------------------- + +Since there is no machine architecture, sandbox U-Boot cannot actually boot +a kernel, but it does support the bootm command. Filesystems, memory +commands, hashing, FIT images, verified boot and many other features are +supported. + +When 'bootm' runs a kernel, sandbox will exit, as U-Boot does on a real +machine. Of course in this case, no kernel is run. + +It is also possible to tell U-Boot that it has jumped from a temporary +previous U-Boot binary, with the -j option. That binary is automatically +removed by the U-Boot that gets the -j option. This allows you to write +tests which emulate the action of chain-loading U-Boot, typically used in +a situation where a second 'updatable' U-Boot is stored on your board. It +is very risky to overwrite or upgrade the only U-Boot on a board, since a +power or other failure will brick the board and require return to the +manufacturer in the case of a consumer device. + + +Supported Drivers +----------------- + +U-Boot sandbox supports these emulations: + +- Block devices +- Chrome OS EC +- GPIO +- Host filesystem (access files on the host from within U-Boot) +- I2C +- Keyboard (Chrome OS) +- LCD +- Network +- Serial (for console only) +- Sound (incomplete - see sandbox_sdl_sound_init() for details) +- SPI +- SPI flash +- TPM (Trusted Platform Module) + +A wide range of commands are implemented. Filesystems which use a block +device are supported. + +Also sandbox supports driver model (CONFIG_DM) and associated commands. + + +Sandbox Variants +---------------- + +There are unfortunately quite a few variants at present: + +sandbox: + should be used for most tests +sandbox64: + special build that forces a 64-bit host +sandbox_flattree: + builds with dev_read\_...() functions defined as inline. + We need this build so that we can test those inline functions, and we + cannot build with both the inline functions and the non-inline functions + since they are named the same. +sandbox_spl: + builds sandbox with SPL support, so you can run spl/u-boot-spl + and it will start up and then load ./u-boot. It is also possible to + run ./u-boot directly. + +Of these sandbox_spl can probably be removed since it is a superset of sandbox. + +Most of the config options should be identical between these variants. + + +Linux RAW Networking Bridge +--------------------------- + +The sandbox_eth_raw driver bridges traffic between the bottom of the network +stack and the RAW sockets API in Linux. This allows much of the U-Boot network +functionality to be tested in sandbox against real network traffic. + +For Ethernet network adapters, the bridge utilizes the RAW AF_PACKET API. This +is needed to get access to the lowest level of the network stack in Linux. This +means that all of the Ethernet frame is included. This allows the U-Boot network +stack to be fully used. In other words, nothing about the Linux network stack is +involved in forming the packets that end up on the wire. To receive the +responses to packets sent from U-Boot the network interface has to be set to +promiscuous mode so that the network card won't filter out packets not destined +for its configured (on Linux) MAC address. + +The RAW sockets Ethernet API requires elevated privileges in Linux. You can +either run as root, or you can add the capability needed like so:: + + sudo /sbin/setcap "CAP_NET_RAW+ep" /path/to/u-boot + +The default device tree for sandbox includes an entry for eth0 on the sandbox +host machine whose alias is "eth1". The following are a few examples of network +operations being tested on the eth0 interface. + +.. code-block:: none + + sudo /path/to/u-boot -D + + DHCP + .... + + setenv autoload no + setenv ethrotate no + setenv ethact eth1 + dhcp + + PING + .... + + setenv autoload no + setenv ethrotate no + setenv ethact eth1 + dhcp + ping $gatewayip + + TFTP + .... + + setenv autoload no + setenv ethrotate no + setenv ethact eth1 + dhcp + setenv serverip WWW.XXX.YYY.ZZZ + tftpboot u-boot.bin + +The bridge also supports (to a lesser extent) the localhost interface, 'lo'. + +The 'lo' interface cannot use the RAW AF_PACKET API because the lo interface +doesn't support Ethernet-level traffic. It is a higher-level interface that is +expected only to be used at the AF_INET level of the API. As such, the most raw +we can get on that interface is the RAW AF_INET API on UDP. This allows us to +set the IP_HDRINCL option to include everything except the Ethernet header in +the packets we send and receive. + +Because only UDP is supported, ICMP traffic will not work, so expect that ping +commands will time out. + +The default device tree for sandbox includes an entry for lo on the sandbox +host machine whose alias is "eth5". The following is an example of a network +operation being tested on the lo interface. + +.. code-block:: none + + TFTP + .... + + setenv ethrotate no + setenv ethact eth5 + tftpboot u-boot.bin + + +SPI Emulation +------------- + +Sandbox supports SPI and SPI flash emulation. + +The device can be enabled via a device tree, for example:: + + spi@0 { + #address-cells = <1>; + #size-cells = <0>; + reg = <0 1>; + compatible = "sandbox,spi"; + cs-gpios = <0>, <&gpio_a 0>; + spi.bin@0 { + reg = <0>; + compatible = "spansion,m25p16", "jedec,spi-nor"; + spi-max-frequency = <40000000>; + sandbox,filename = "spi.bin"; + }; + }; + +The file must be created in advance:: + + $ dd if=/dev/zero of=spi.bin bs=1M count=2 + $ u-boot -T + +Here, you can use "-T" or "-D" option to specify test.dtb or u-boot.dtb, +respectively, or "-d <file>" for your own dtb. + +With this setup you can issue SPI flash commands as normal:: + + =>sf probe + SF: Detected M25P16 with page size 64 KiB, total 2 MiB + =>sf read 0 0 10000 + SF: 65536 bytes @ 0x0 Read: OK + +Since this is a full SPI emulation (rather than just flash), you can +also use low-level SPI commands:: + + =>sspi 0:0 32 9f + FF202015 + +This is issuing a READ_ID command and getting back 20 (ST Micro) part +0x2015 (the M25P16). + + +Block Device Emulation +---------------------- + +U-Boot can use raw disk images for block device emulation. To e.g. list +the contents of the root directory on the second partion of the image +"disk.raw", you can use the following commands:: + + =>host bind 0 ./disk.raw + =>ls host 0:2 + +The device can be marked removeable with 'host bind -r'. + +A disk image can be created using the following commands:: + + $> truncate -s 1200M ./disk.raw + $> echo -e "label: gpt\n,64M,U\n,,L" | /usr/sbin/sgdisk ./disk.raw + $> lodev=`sudo losetup -P -f --show ./disk.raw` + $> sudo mkfs.vfat -n EFI -v ${lodev}p1 + $> sudo mkfs.ext4 -L ROOT -v ${lodev}p2 + +or utilize the device described in test/py/make_test_disk.py:: + + #!/usr/bin/python + import make_test_disk + make_test_disk.makeDisk() + +Writing Sandbox Drivers +----------------------- + +Generally you should put your driver in a file containing the word 'sandbox' +and put it in the same directory as other drivers of its type. You can then +implement the same hooks as the other drivers. + +To access U-Boot's emulated memory, use map_sysmem() as mentioned above. + +If your driver needs to store configuration or state (such as SPI flash +contents or emulated chip registers), you can use the device tree as +described above. Define handlers for this with the SANDBOX_STATE_IO macro. +See arch/sandbox/include/asm/state.h for documentation. In short you provide +a node name, compatible string and functions to read and write the state. +Since writing the state can expand the device tree, you may need to use +state_setprop() which does this automatically and avoids running out of +space. See existing code for examples. + + +Debugging the init sequence +--------------------------- + +If you get a failure in the initcall sequence, like this:: + + initcall sequence 0000560775957c80 failed at call 0000000000048134 (err=-96) + +Then you use can use grep to see which init call failed, e.g.:: + + $ grep 0000000000048134 u-boot.map + stdio_add_devices + +Of course another option is to run it with a debugger such as gdb:: + + $ gdb u-boot + ... + (gdb) br initcall.h:41 + Breakpoint 1 at 0x4db9d: initcall.h:41. (2 locations) + +Note that two locations are reported, since this function is used in both +board_init_f() and board_init_r(). + +.. code-block:: none + + (gdb) r + Starting program: /tmp/b/sandbox/u-boot + [Thread debugging using libthread_db enabled] + Using host libthread_db library "/lib/x86_64-linux-gnu/libthread_db.so.1". + + U-Boot 2018.09-00264-ge0c2ba9814-dirty (Sep 22 2018 - 12:21:46 -0600) + + DRAM: 128 MiB + MMC: + + Breakpoint 1, initcall_run_list (init_sequence=0x5555559619e0 <init_sequence_f>) + at /scratch/sglass/cosarm/src/third_party/u-boot/files/include/initcall.h:41 + 41 printf("initcall sequence %p failed at call %p (err=%d)\n", + (gdb) print *init_fnc_ptr + $1 = (const init_fnc_t) 0x55555559c114 <stdio_add_devices> + (gdb) + + +This approach can be used on normal boards as well as sandbox. + + +SDL_CONFIG +---------- + +If sdl-config is on a different path from the default, set the SDL_CONFIG +environment variable to the correct pathname before building U-Boot. + + +Using valgrind / memcheck +------------------------- + +It is possible to run U-Boot under valgrind to check memory allocations:: + + valgrind u-boot + +If you are running sandbox SPL or TPL, then valgrind will not by default +notice when U-Boot jumps from TPL to SPL, or from SPL to U-Boot proper. To +fix this, use:: + + valgrind --trace-children=yes u-boot + + +Testing +------- + +U-Boot sandbox can be used to run various tests, mostly in the test/ +directory. + +See :doc:`../develop/tests_sandbox` for more information and +:doc:`../develop/testing` for information about testing generally. + + +Memory Map +---------- + +Sandbox has its own emulated memory starting at 0. Here are some of the things +that are mapped into that memory: + +======= ======================== =============================== +Addr Config Usage +======= ======================== =============================== + 0 CONFIG_SYS_FDT_LOAD_ADDR Device tree + e000 CONFIG_BLOBLIST_ADDR Blob list + 10000 CONFIG_MALLOC_F_ADDR Early memory allocation + f0000 CONFIG_PRE_CON_BUF_ADDR Pre-console buffer + 100000 CONFIG_TRACE_EARLY_ADDR Early trace buffer (if enabled). Also used + as the SPL load buffer in spl_test_load(). + 200000 CONFIG_SYS_TEXT_BASE Load buffer for U-Boot (sandbox_spl only) +======= ======================== =============================== diff --git a/roms/u-boot/doc/arch/sh.rst b/roms/u-boot/doc/arch/sh.rst new file mode 100644 index 000000000..3e3759d68 --- /dev/null +++ b/roms/u-boot/doc/arch/sh.rst @@ -0,0 +1,88 @@ +.. SPDX-License-Identifier: GPL-2.0+ +.. Copyright (c) 2007,2008 Nobuhiro Iwamatsu <iwamatsu@nigaur.org> + +SuperH +====== + +What's this? +------------ +This file contains status information for the port of U-Boot to the +Renesas SuperH series of CPUs. + +Overview +-------- +SuperH has an original boot loader. However, source code is dirty, and +maintenance is not done. To improve sharing and the maintenance of the code, +Nobuhiro Iwamatsu started the porting to U-Boot in 2007. + +Supported CPUs +-------------- + +Renesas SH7750/SH7750R +^^^^^^^^^^^^^^^^^^^^^^ +This CPU has the SH4 core. + +Renesas SH7722 +^^^^^^^^^^^^^^ +This CPU has the SH4AL-DSP core. + +Supported Boards +---------------- + +Hitachi UL MS7750SE01/MS7750RSE01 +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Board specific code is in board/ms7750se +To use this board, type "make ms7750se_config". +Support devices are: + + - SCIF + - SDRAM + - NOR Flash + - Marubun PCMCIA + +Hitachi UL MS7722SE01 +^^^^^^^^^^^^^^^^^^^^^ +Board specific code is in board/ms7722se +To use this board, type "make ms7722se_config". +Support devices are: + + - SCIF + - SDRAM + - NOR Flash + - Marubun PCMCIA + - SMC91x ethernet + +Hitachi UL MS7720ERP01 +^^^^^^^^^^^^^^^^^^^^^^ +Board specific code is in board/ms7720se +To use this board, type "make ms7720se_config". +Support devices are: + + - SCIF + - SDRAM + - NOR Flash + - Marubun PCMCIA + +In SuperH, S-record and binary of made u-boot work on the memory. +When u-boot is written in the flash, it is necessary to change the +address by using 'objcopy':: + + ex) shX-linux-objcopy -Ibinary -Osrec u-boot.bin u-boot.flash.srec + +Compiler +-------- +You can use the following of u-boot to compile. + - `SuperH Linux Open site <http://www.superh-linux.org/>`_ + - `KPIT GNU tools <http://www.kpitgnutools.com/>`_ + +Future +------ +I plan to support the following CPUs and boards. + +CPUs +^^^^ +- SH7751R(SH4) + +Boards +^^^^^^ +Many boards ;-) diff --git a/roms/u-boot/doc/arch/x86.rst b/roms/u-boot/doc/arch/x86.rst new file mode 100644 index 000000000..2ebfed871 --- /dev/null +++ b/roms/u-boot/doc/arch/x86.rst @@ -0,0 +1,765 @@ +.. SPDX-License-Identifier: GPL-2.0+ +.. Copyright (C) 2014, Simon Glass <sjg@chromium.org> +.. Copyright (C) 2014, Bin Meng <bmeng.cn@gmail.com> + +x86 +=== + +This document describes the information about U-Boot running on x86 targets, +including supported boards, build instructions, todo list, etc. + +Status +------ +U-Boot supports running as a `coreboot`_ payload on x86. So far only Link +(Chromebook Pixel) and `QEMU`_ x86 targets have been tested, but it should +work with minimal adjustments on other x86 boards since coreboot deals with +most of the low-level details. + +U-Boot is a main bootloader on Intel Edison board. + +U-Boot also supports booting directly from x86 reset vector, without coreboot. +In this case, known as bare mode, from the fact that it runs on the +'bare metal', U-Boot acts like a BIOS replacement. The following platforms +are supported: + + - Bayley Bay CRB + - Cherry Hill CRB + - Congatec QEVAL 2.0 & conga-QA3/E3845 + - Cougar Canyon 2 CRB + - Crown Bay CRB + - Galileo + - Link (Chromebook Pixel) + - Minnowboard MAX + - Samus (Chromebook Pixel 2015) + - QEMU x86 (32-bit & 64-bit) + +As for loading an OS, U-Boot supports directly booting a 32-bit or 64-bit +Linux kernel as part of a FIT image. It also supports a compressed zImage. +U-Boot supports loading an x86 VxWorks kernel. Please check README.vxworks +for more details. + +Build Instructions for U-Boot as BIOS replacement (bare mode) +------------------------------------------------------------- +Building a ROM version of U-Boot (hereafter referred to as u-boot.rom) is a +little bit tricky, as generally it requires several binary blobs which are not +shipped in the U-Boot source tree. Due to this reason, the u-boot.rom build is +not turned on by default in the U-Boot source tree. Firstly, you need turn it +on by enabling the ROM build either via an environment variable:: + + $ export BUILD_ROM=y + +or via configuration:: + + CONFIG_BUILD_ROM=y + +Both tell the Makefile to build u-boot.rom as a target. + +CPU Microcode +------------- +Modern CPUs usually require a special bit stream called `microcode`_ to be +loaded on the processor after power up in order to function properly. U-Boot +has already integrated these as hex dumps in the source tree. + +SMP Support +----------- +On a multicore system, U-Boot is executed on the bootstrap processor (BSP). +Additional application processors (AP) can be brought up by U-Boot. In order to +have an SMP kernel to discover all of the available processors, U-Boot needs to +prepare configuration tables which contain the multi-CPUs information before +loading the OS kernel. Currently U-Boot supports generating two types of tables +for SMP, called Simple Firmware Interface (`SFI`_) and Multi-Processor (`MP`_) +tables. The writing of these two tables are controlled by two Kconfig +options GENERATE_SFI_TABLE and GENERATE_MP_TABLE. + +Driver Model +------------ +x86 has been converted to use driver model for serial, GPIO, SPI, SPI flash, +keyboard, real-time clock, USB. Video is in progress. + +Device Tree +----------- +x86 uses device tree to configure the board thus requires CONFIG_OF_CONTROL to +be turned on. Not every device on the board is configured via device tree, but +more and more devices will be added as time goes by. Check out the directory +arch/x86/dts/ for these device tree source files. + +Useful Commands +--------------- +In keeping with the U-Boot philosophy of providing functions to check and +adjust internal settings, there are several x86-specific commands that may be +useful: + +fsp + Display information about Intel Firmware Support Package (FSP). + This is only available on platforms which use FSP, mostly Atom. +iod + Display I/O memory +iow + Write I/O memory +mtrr + List and set the Memory Type Range Registers (MTRR). These are used to + tell the CPU whether memory is cacheable and if so the cache write + mode to use. U-Boot sets up some reasonable values but you can + adjust then with this command. + +Booting Ubuntu +-------------- +As an example of how to set up your boot flow with U-Boot, here are +instructions for starting Ubuntu from U-Boot. These instructions have been +tested on Minnowboard MAX with a SATA drive but are equally applicable on +other platforms and other media. There are really only four steps and it's a +very simple script, but a more detailed explanation is provided here for +completeness. + +Note: It is possible to set up U-Boot to boot automatically using syslinux. +It could also use the grub.cfg file (/efi/ubuntu/grub.cfg) to obtain the +GUID. If you figure these out, please post patches to this README. + +Firstly, you will need Ubuntu installed on an available disk. It should be +possible to make U-Boot start a USB start-up disk but for now let's assume +that you used another boot loader to install Ubuntu. + +Use the U-Boot command line to find the UUID of the partition you want to +boot. For example our disk is SCSI device 0:: + + => part list scsi 0 + + Partition Map for SCSI device 0 -- Partition Type: EFI + + Part Start LBA End LBA Name + Attributes + Type GUID + Partition GUID + 1 0x00000800 0x001007ff "" + attrs: 0x0000000000000000 + type: c12a7328-f81f-11d2-ba4b-00a0c93ec93b + guid: 9d02e8e4-4d59-408f-a9b0-fd497bc9291c + 2 0x00100800 0x037d8fff "" + attrs: 0x0000000000000000 + type: 0fc63daf-8483-4772-8e79-3d69d8477de4 + guid: 965c59ee-1822-4326-90d2-b02446050059 + 3 0x037d9000 0x03ba27ff "" + attrs: 0x0000000000000000 + type: 0657fd6d-a4ab-43c4-84e5-0933c84b4f4f + guid: 2c4282bd-1e82-4bcf-a5ff-51dedbf39f17 + => + +This shows that your SCSI disk has three partitions. The really long hex +strings are called Globally Unique Identifiers (GUIDs). You can look up the +'type' ones `here`_. On this disk the first partition is for EFI and is in +VFAT format (DOS/Windows):: + + => fatls scsi 0:1 + efi/ + + 0 file(s), 1 dir(s) + + +Partition 2 is 'Linux filesystem data' so that will be our root disk. It is +in ext2 format:: + + => ext2ls scsi 0:2 + <DIR> 4096 . + <DIR> 4096 .. + <DIR> 16384 lost+found + <DIR> 4096 boot + <DIR> 12288 etc + <DIR> 4096 media + <DIR> 4096 bin + <DIR> 4096 dev + <DIR> 4096 home + <DIR> 4096 lib + <DIR> 4096 lib64 + <DIR> 4096 mnt + <DIR> 4096 opt + <DIR> 4096 proc + <DIR> 4096 root + <DIR> 4096 run + <DIR> 12288 sbin + <DIR> 4096 srv + <DIR> 4096 sys + <DIR> 4096 tmp + <DIR> 4096 usr + <DIR> 4096 var + <SYM> 33 initrd.img + <SYM> 30 vmlinuz + <DIR> 4096 cdrom + <SYM> 33 initrd.img.old + => + +and if you look in the /boot directory you will see the kernel:: + + => ext2ls scsi 0:2 /boot + <DIR> 4096 . + <DIR> 4096 .. + <DIR> 4096 efi + <DIR> 4096 grub + 3381262 System.map-3.13.0-32-generic + 1162712 abi-3.13.0-32-generic + 165611 config-3.13.0-32-generic + 176500 memtest86+.bin + 178176 memtest86+.elf + 178680 memtest86+_multiboot.bin + 5798112 vmlinuz-3.13.0-32-generic + 165762 config-3.13.0-58-generic + 1165129 abi-3.13.0-58-generic + 5823136 vmlinuz-3.13.0-58-generic + 19215259 initrd.img-3.13.0-58-generic + 3391763 System.map-3.13.0-58-generic + 5825048 vmlinuz-3.13.0-58-generic.efi.signed + 28304443 initrd.img-3.13.0-32-generic + => + +The 'vmlinuz' files contain a packaged Linux kernel. The format is a kind of +self-extracting compressed file mixed with some 'setup' configuration data. +Despite its size (uncompressed it is >10MB) this only includes a basic set of +device drivers, enough to boot on most hardware types. + +The 'initrd' files contain a RAM disk. This is something that can be loaded +into RAM and will appear to Linux like a disk. Ubuntu uses this to hold lots +of drivers for whatever hardware you might have. It is loaded before the +real root disk is accessed. + +The numbers after the end of each file are the version. Here it is Linux +version 3.13. You can find the source code for this in the Linux tree with +the tag v3.13. The '.0' allows for additional Linux releases to fix problems, +but normally this is not needed. The '-58' is used by Ubuntu. Each time they +release a new kernel they increment this number. New Ubuntu versions might +include kernel patches to fix reported bugs. Stable kernels can exist for +some years so this number can get quite high. + +The '.efi.signed' kernel is signed for EFI's secure boot. U-Boot has its own +secure boot mechanism - see `this`_ & `that`_. It cannot read .efi files +at present. + +To boot Ubuntu from U-Boot the steps are as follows: + +1. Set up the boot arguments. Use the GUID for the partition you want to boot:: + + => setenv bootargs root=/dev/disk/by-partuuid/965c59ee-1822-4326-90d2-b02446050059 ro + +Here root= tells Linux the location of its root disk. The disk is specified +by its GUID, using '/dev/disk/by-partuuid/', a Linux path to a 'directory' +containing all the GUIDs Linux has found. When it starts up, there will be a +file in that directory with this name in it. It is also possible to use a +device name here, see later. + +2. Load the kernel. Since it is an ext2/4 filesystem we can do:: + + => ext2load scsi 0:2 03000000 /boot/vmlinuz-3.13.0-58-generic + +The address 30000000 is arbitrary, but there seem to be problems with using +small addresses (sometimes Linux cannot find the ramdisk). This is 48MB into +the start of RAM (which is at 0 on x86). + +3. Load the ramdisk (to 64MB):: + + => ext2load scsi 0:2 04000000 /boot/initrd.img-3.13.0-58-generic + +4. Start up the kernel. We need to know the size of the ramdisk, but can use + a variable for that. U-Boot sets 'filesize' to the size of the last file it + loaded:: + + => zboot 03000000 0 04000000 ${filesize} + +Type 'help zboot' if you want to see what the arguments are. U-Boot on x86 is +quite verbose when it boots a kernel. You should see these messages from +U-Boot:: + + Valid Boot Flag + Setup Size = 0x00004400 + Magic signature found + Using boot protocol version 2.0c + Linux kernel version 3.13.0-58-generic (buildd@allspice) #97-Ubuntu SMP Wed Jul 8 02:56:15 UTC 2015 + Building boot_params at 0x00090000 + Loading bzImage at address 100000 (5805728 bytes) + Magic signature found + Initial RAM disk at linear address 0x04000000, size 19215259 bytes + Kernel command line: "root=/dev/disk/by-partuuid/965c59ee-1822-4326-90d2-b02446050059 ro" + + Starting kernel ... + +U-Boot prints out some bootstage timing. This is more useful if you put the +above commands into a script since then it will be faster:: + + Timer summary in microseconds: + Mark Elapsed Stage + 0 0 reset + 241,535 241,535 board_init_r + 2,421,611 2,180,076 id=64 + 2,421,790 179 id=65 + 2,428,215 6,425 main_loop + 48,860,584 46,432,369 start_kernel + + Accumulated time: + 240,329 ahci + 1,422,704 vesa display + +Now the kernel actually starts (if you want to examine kernel boot up message on +the serial console, append "console=ttyS0,115200" to the kernel command line):: + + [ 0.000000] Initializing cgroup subsys cpuset + [ 0.000000] Initializing cgroup subsys cpu + [ 0.000000] Initializing cgroup subsys cpuacct + [ 0.000000] Linux version 3.13.0-58-generic (buildd@allspice) (gcc version 4.8.2 (Ubuntu 4.8.2-19ubuntu1) ) #97-Ubuntu SMP Wed Jul 8 02:56:15 UTC 2015 (Ubuntu 3.13.0-58.97-generic 3.13.11-ckt22) + [ 0.000000] Command line: root=/dev/disk/by-partuuid/965c59ee-1822-4326-90d2-b02446050059 ro console=ttyS0,115200 + +It continues for a long time. Along the way you will see it pick up your +ramdisk:: + + [ 0.000000] RAMDISK: [mem 0x04000000-0x05253fff] + ... + [ 0.788540] Trying to unpack rootfs image as initramfs... + [ 1.540111] Freeing initrd memory: 18768K (ffff880004000000 - ffff880005254000) + ... + +Later it actually starts using it:: + + Begin: Running /scripts/local-premount ... done. + +You should also see your boot disk turn up:: + + [ 4.357243] scsi 1:0:0:0: Direct-Access ATA ADATA SP310 5.2 PQ: 0 ANSI: 5 + [ 4.366860] sd 1:0:0:0: [sda] 62533296 512-byte logical blocks: (32.0 GB/29.8 GiB) + [ 4.375677] sd 1:0:0:0: Attached scsi generic sg0 type 0 + [ 4.381859] sd 1:0:0:0: [sda] Write Protect is off + [ 4.387452] sd 1:0:0:0: [sda] Write cache: enabled, read cache: enabled, doesn't support DPO or FUA + [ 4.399535] sda: sda1 sda2 sda3 + +Linux has found the three partitions (sda1-3). Mercifully it doesn't print out +the GUIDs. In step 1 above we could have used:: + + setenv bootargs root=/dev/sda2 ro + +instead of the GUID. However if you add another drive to your board the +numbering may change whereas the GUIDs will not. So if your boot partition +becomes sdb2, it will still boot. For embedded systems where you just want to +boot the first disk, you have that option. + +The last thing you will see on the console is mention of plymouth (which +displays the Ubuntu start-up screen) and a lot of 'Starting' messages:: + + * Starting Mount filesystems on boot [ OK ] + +After a pause you should see a login screen on your display and you are done. + +If you want to put this in a script you can use something like this:: + + setenv bootargs root=UUID=b2aaf743-0418-4d90-94cc-3e6108d7d968 ro + setenv boot zboot 03000000 0 04000000 \${filesize} + setenv bootcmd "ext2load scsi 0:2 03000000 /boot/vmlinuz-3.13.0-58-generic; ext2load scsi 0:2 04000000 /boot/initrd.img-3.13.0-58-generic; run boot" + saveenv + +The \ is to tell the shell not to evaluate ${filesize} as part of the setenv +command. + +You can also bake this behaviour into your build by hard-coding the +environment variables if you add this to minnowmax.h: + +.. code-block:: c + + #undef CONFIG_BOOTCOMMAND + #define CONFIG_BOOTCOMMAND \ + "ext2load scsi 0:2 03000000 /boot/vmlinuz-3.13.0-58-generic; " \ + "ext2load scsi 0:2 04000000 /boot/initrd.img-3.13.0-58-generic; " \ + "run boot" + + #undef CONFIG_EXTRA_ENV_SETTINGS + #define CONFIG_EXTRA_ENV_SETTINGS "boot=zboot 03000000 0 04000000 ${filesize}" + +and change CONFIG_BOOTARGS value in configs/minnowmax_defconfig to:: + + CONFIG_BOOTARGS="root=/dev/sda2 ro" + +Test with SeaBIOS +----------------- +`SeaBIOS`_ is an open source implementation of a 16-bit x86 BIOS. It can run +in an emulator or natively on x86 hardware with the use of U-Boot. With its +help, we can boot some OSes that require 16-bit BIOS services like Windows/DOS. + +As U-Boot, we have to manually create a table where SeaBIOS gets various system +information (eg: E820) from. The table unfortunately has to follow the coreboot +table format as SeaBIOS currently supports booting as a coreboot payload. + +To support loading SeaBIOS, U-Boot should be built with CONFIG_SEABIOS on. +Booting SeaBIOS is done via U-Boot's bootelf command, like below:: + + => tftp bios.bin.elf;bootelf + Using e1000#0 device + TFTP from server 10.10.0.100; our IP address is 10.10.0.108 + ... + Bytes transferred = 122124 (1dd0c hex) + ## Starting application at 0x000ff06e ... + SeaBIOS (version rel-1.9.0) + ... + +bios.bin.elf is the SeaBIOS image built from SeaBIOS source tree. +Make sure it is built as follows:: + + $ make menuconfig + +Inside the "General Features" menu, select "Build for coreboot" as the +"Build Target". Inside the "Debugging" menu, turn on "Serial port debugging" +so that we can see something as soon as SeaBIOS boots. Leave other options +as in their default state. Then:: + + $ make + ... + Total size: 121888 Fixed: 66496 Free: 9184 (used 93.0% of 128KiB rom) + Creating out/bios.bin.elf + +Currently this is tested on QEMU x86 target with U-Boot chain-loading SeaBIOS +to install/boot a Windows XP OS (below for example command to install Windows). + +.. code-block:: none + + # Create a 10G disk.img as the virtual hard disk + $ qemu-img create -f qcow2 disk.img 10G + + # Install a Windows XP OS from an ISO image 'winxp.iso' + $ qemu-system-i386 -serial stdio -bios u-boot.rom -hda disk.img -cdrom winxp.iso -smp 2 -m 512 + + # Boot a Windows XP OS installed on the virutal hard disk + $ qemu-system-i386 -serial stdio -bios u-boot.rom -hda disk.img -smp 2 -m 512 + +This is also tested on Intel Crown Bay board with a PCIe graphics card, booting +SeaBIOS then chain-loading a GRUB on a USB drive, then Linux kernel finally. + +If you are using Intel Integrated Graphics Device (IGD) as the primary display +device on your board, SeaBIOS needs to be patched manually to get its VGA ROM +loaded and run by SeaBIOS. SeaBIOS locates VGA ROM via the PCI expansion ROM +register, but IGD device does not have its VGA ROM mapped by this register. +Its VGA ROM is packaged as part of u-boot.rom at a configurable flash address +which is unknown to SeaBIOS. An example patch is needed for SeaBIOS below: + +.. code-block:: none + + diff --git a/src/optionroms.c b/src/optionroms.c + index 65f7fe0..c7b6f5e 100644 + --- a/src/optionroms.c + +++ b/src/optionroms.c + @@ -324,6 +324,8 @@ init_pcirom(struct pci_device *pci, int isvga, u64 *sources) + rom = deploy_romfile(file); + else if (RunPCIroms > 1 || (RunPCIroms == 1 && isvga)) + rom = map_pcirom(pci); + + if (pci->bdf == pci_to_bdf(0, 2, 0)) + + rom = (struct rom_header *)0xfff90000; + if (! rom) + // No ROM present. + return; + +Note: the patch above expects IGD device is at PCI b.d.f 0.2.0 and its VGA ROM +is at 0xfff90000 which corresponds to CONFIG_VGA_BIOS_ADDR on Minnowboard MAX. +Change these two accordingly if this is not the case on your board. + +Development Flow +---------------- +These notes are for those who want to port U-Boot to a new x86 platform. + +Since x86 CPUs boot from SPI flash, a SPI flash emulator is a good investment. +The Dediprog em100 can be used on Linux. + +The em100 tool is available here: http://review.coreboot.org/p/em100.git + +On Minnowboard Max the following command line can be used:: + + sudo em100 -s -p LOW -d u-boot.rom -c W25Q64DW -r + +A suitable clip for connecting over the SPI flash chip is here: +http://www.dediprog.com/pd/programmer-accessories/EM-TC-8. + +This allows you to override the SPI flash contents for development purposes. +Typically you can write to the em100 in around 1200ms, considerably faster +than programming the real flash device each time. The only important +limitation of the em100 is that it only supports SPI bus speeds up to 20MHz. +This means that images must be set to boot with that speed. This is an +Intel-specific feature - e.g. tools/ifttool has an option to set the SPI +speed in the SPI descriptor region. + +If your chip/board uses an Intel Firmware Support Package (FSP) it is fairly +easy to fit it in. You can follow the Minnowboard Max implementation, for +example. Hopefully you will just need to create new files similar to those +in arch/x86/cpu/baytrail which provide Bay Trail support. + +If you are not using an FSP you have more freedom and more responsibility. +The ivybridge support works this way, although it still uses a ROM for +graphics and still has binary blobs containing Intel code. You should aim to +support all important peripherals on your platform including video and storage. +Use the device tree for configuration where possible. + +For the microcode you can create a suitable device tree file using the +microcode tool:: + + ./tools/microcode-tool -d microcode.dat -m <model> create + +or if you only have header files and not the full Intel microcode.dat database:: + + ./tools/microcode-tool -H BAY_TRAIL_FSP_KIT/Microcode/M0130673322.h \ + -H BAY_TRAIL_FSP_KIT/Microcode/M0130679901.h -m all create + +These are written to arch/x86/dts/microcode/ by default. + +Note that it is possible to just add the micrcode for your CPU if you know its +model. U-Boot prints this information when it starts:: + + CPU: x86_64, vendor Intel, device 30673h + +so here we can use the M0130673322 file. + +If you platform can display POST codes on two little 7-segment displays on +the board, then you can use post_code() calls from C or assembler to monitor +boot progress. This can be good for debugging. + +If not, you can try to get serial working as early as possible. The early +debug serial port may be useful here. See setup_internal_uart() for an example. + +During the U-Boot porting, one of the important steps is to write correct PIRQ +routing information in the board device tree. Without it, device drivers in the +Linux kernel won't function correctly due to interrupt is not working. Please +refer to U-Boot `doc <doc/device-tree-bindings/misc/intel,irq-router.txt>`_ for +the device tree bindings of Intel interrupt router. Here we have more details +on the intel,pirq-routing property below. + +.. code-block:: none + + intel,pirq-routing = < + PCI_BDF(0, 2, 0) INTA PIRQA + ... + >; + +As you see each entry has 3 cells. For the first one, we need describe all pci +devices mounted on the board. For SoC devices, normally there is a chapter on +the chipset datasheet which lists all the available PCI devices. For example on +Bay Trail, this is chapter 4.3 (PCI configuration space). For the second one, we +can get the interrupt pin either from datasheet or hardware via U-Boot shell. +The reliable source is the hardware as sometimes chipset datasheet is not 100% +up-to-date. Type 'pci header' plus the device's pci bus/device/function number +from U-Boot shell below:: + + => pci header 0.1e.1 + vendor ID = 0x8086 + device ID = 0x0f08 + ... + interrupt line = 0x09 + interrupt pin = 0x04 + ... + +It shows this PCI device is using INTD pin as it reports 4 in the interrupt pin +register. Repeat this until you get interrupt pins for all the devices. The last +cell is the PIRQ line which a particular interrupt pin is mapped to. On Intel +chipset, the power-up default mapping is INTA/B/C/D maps to PIRQA/B/C/D. This +can be changed by registers in LPC bridge. So far Intel FSP does not touch those +registers so we can write down the PIRQ according to the default mapping rule. + +Once we get the PIRQ routing information in the device tree, the interrupt +allocation and assignment will be done by U-Boot automatically. Now you can +enable CONFIG_GENERATE_PIRQ_TABLE for testing Linux kernel using i8259 PIC and +CONFIG_GENERATE_MP_TABLE for testing Linux kernel using local APIC and I/O APIC. + +This script might be useful. If you feed it the output of 'pci long' from +U-Boot then it will generate a device tree fragment with the interrupt +configuration for each device (note it needs gawk 4.0.0):: + + $ cat console_output |awk '/PCI/ {device=$4} /interrupt line/ {line=$4} \ + /interrupt pin/ {pin = $4; if (pin != "0x00" && pin != "0xff") \ + {patsplit(device, bdf, "[0-9a-f]+"); \ + printf "PCI_BDF(%d, %d, %d) INT%c PIRQ%c\n", strtonum("0x" bdf[1]), \ + strtonum("0x" bdf[2]), bdf[3], strtonum(pin) + 64, 64 + strtonum(pin)}}' + +Example output:: + + PCI_BDF(0, 2, 0) INTA PIRQA + PCI_BDF(0, 3, 0) INTA PIRQA + ... + +Porting Hints +------------- + +Quark-specific considerations +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +To port U-Boot to other boards based on the Intel Quark SoC, a few things need +to be taken care of. The first important part is the Memory Reference Code (MRC) +parameters. Quark MRC supports memory-down configuration only. All these MRC +parameters are supplied via the board device tree. To get started, first copy +the MRC section of arch/x86/dts/galileo.dts to your board's device tree, then +change these values by consulting board manuals or your hardware vendor. +Available MRC parameter values are listed in include/dt-bindings/mrc/quark.h. +The other tricky part is with PCIe. Quark SoC integrates two PCIe root ports, +but by default they are held in reset after power on. In U-Boot, PCIe +initialization is properly handled as per Quark's firmware writer guide. +In your board support codes, you need provide two routines to aid PCIe +initialization, which are board_assert_perst() and board_deassert_perst(). +The two routines need implement a board-specific mechanism to assert/deassert +PCIe PERST# pin. Care must be taken that in those routines that any APIs that +may trigger PCI enumeration process are strictly forbidden, as any access to +PCIe root port's configuration registers will cause system hang while it is +held in reset. For more details, check how they are implemented by the Intel +Galileo board support codes in board/intel/galileo/galileo.c. + +coreboot +^^^^^^^^ + +See scripts/coreboot.sed which can assist with porting coreboot code into +U-Boot drivers. It will not resolve all build errors, but will perform common +transformations. Remember to add attribution to coreboot for new files added +to U-Boot. This should go at the top of each file and list the coreboot +filename where the code originated. + +Debugging ACPI issues with Windows +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Windows might cache system information and only detect ACPI changes if you +modify the ACPI table versions. So tweak them liberally when debugging ACPI +issues with Windows. + +ACPI Support Status +------------------- +Advanced Configuration and Power Interface (`ACPI`_) aims to establish +industry-standard interfaces enabling OS-directed configuration, power +management, and thermal management of mobile, desktop, and server platforms. + +Linux can boot without ACPI with "acpi=off" command line parameter, but +with ACPI the kernel gains the capabilities to handle power management. +For Windows, ACPI is a must-have firmware feature since Windows Vista. +CONFIG_GENERATE_ACPI_TABLE is the config option to turn on ACPI support in +U-Boot. This requires Intel ACPI compiler to be installed on your host to +compile ACPI DSDT table written in ASL format to AML format. You can get +the compiler via "apt-get install iasl" if you are on Ubuntu or download +the source from https://www.acpica.org/downloads to compile one by yourself. + +Current ACPI support in U-Boot is basically complete. More optional features +can be added in the future. The status as of today is: + + * Support generating RSDT, XSDT, FACS, FADT, MADT, MCFG tables. + * Support one static DSDT table only, compiled by Intel ACPI compiler. + * Support S0/S3/S4/S5, reboot and shutdown from OS. + * Support booting a pre-installed Ubuntu distribution via 'zboot' command. + * Support installing and booting Ubuntu 14.04 (or above) from U-Boot with + the help of SeaBIOS using legacy interface (non-UEFI mode). + * Support installing and booting Windows 8.1/10 from U-Boot with the help + of SeaBIOS using legacy interface (non-UEFI mode). + * Support ACPI interrupts with SCI only. + +Features that are optional: + + * Dynamic AML bytecodes insertion at run-time. We may need this to support + SSDT table generation and DSDT fix up. + * SMI support. Since U-Boot is a modern bootloader, we don't want to bring + those legacy stuff into U-Boot. ACPI spec allows a system that does not + support SMI (a legacy-free system). + +ACPI was initially enabled on BayTrail based boards. Testing was done by booting +a pre-installed Ubuntu 14.04 from a SATA drive. Installing Ubuntu 14.04 and +Windows 8.1/10 to a SATA drive and booting from there is also tested. Most +devices seem to work correctly and the board can respond a reboot/shutdown +command from the OS. + +For other platform boards, ACPI support status can be checked by examining their +board defconfig files to see if CONFIG_GENERATE_ACPI_TABLE is set to y. + +The S3 sleeping state is a low wake latency sleeping state defined by ACPI +spec where all system context is lost except system memory. To test S3 resume +with a Linux kernel, simply run "echo mem > /sys/power/state" and kernel will +put the board to S3 state where the power is off. So when the power button is +pressed again, U-Boot runs as it does in cold boot and detects the sleeping +state via ACPI register to see if it is S3, if yes it means we are waking up. +U-Boot is responsible for restoring the machine state as it is before sleep. +When everything is done, U-Boot finds out the wakeup vector provided by OSes +and jump there. To determine whether ACPI S3 resume is supported, check to +see if CONFIG_HAVE_ACPI_RESUME is set for that specific board. + +Note for testing S3 resume with Windows, correct graphics driver must be +installed for your platform, otherwise you won't find "Sleep" option in +the "Power" submenu from the Windows start menu. + +EFI Support +----------- +U-Boot supports booting as a 32-bit or 64-bit EFI payload, e.g. with UEFI. +This is enabled with CONFIG_EFI_STUB to boot from both 32-bit and 64-bit +UEFI BIOS. U-Boot can also run as an EFI application, with CONFIG_EFI_APP. +The CONFIG_EFI_LOADER option, where U-Boot provides an EFI environment to +the kernel (i.e. replaces UEFI completely but provides the same EFI run-time +services) is supported too. For example, we can even use 'bootefi' command +to load a 'u-boot-payload.efi', see below test logs on QEMU. + +.. code-block:: none + + => load ide 0 3000000 u-boot-payload.efi + 489787 bytes read in 138 ms (3.4 MiB/s) + => bootefi 3000000 + Scanning disk ide.blk#0... + Found 2 disks + WARNING: booting without device tree + ## Starting EFI application at 03000000 ... + U-Boot EFI Payload + + + U-Boot 2018.07-rc2 (Jun 23 2018 - 17:12:58 +0800) + + CPU: x86_64, vendor AMD, device 663h + DRAM: 2 GiB + MMC: + Video: 1024x768x32 + Model: EFI x86 Payload + Net: e1000: 52:54:00:12:34:56 + + Warning: e1000#0 using MAC address from ROM + eth0: e1000#0 + No controllers found + Hit any key to stop autoboot: 0 + +See :doc:`../develop/uefi/u-boot_on_efi` and :doc:`../develop/uefi/uefi` for +details of EFI support in U-Boot. + +Chain-loading +------------- +U-Boot can be chain-loaded from another bootloader, such as coreboot or +Slim Bootloader. Typically this is done by building for targets 'coreboot' or +'slimbootloader'. + +For example, at present we have a 'coreboot' target but this runs very +different code from the bare-metal targets, such as coral. There is very little +in common between them. + +It is useful to be able to boot the same U-Boot on a device, with or without a +first-stage bootloader. For example, with chromebook_coral, it is helpful for +testing to be able to boot the same U-Boot (complete with FSP) on bare metal +and from coreboot. It allows checking of things like CPU speed, comparing +registers, ACPI tables and the like. + +To do this you can use ll_boot_init() in appropriate places to skip init that +has already been done by the previous stage. This works by setting a +GD_FLG_NO_LL_INIT flag when U-Boot detects that it is running from another +bootloader. + +With this feature, you can build a bare-metal target and boot it from +coreboot, for example. + +Note that this is a development feature only. It is not intended for use in +production environments. Also it is not currently part of the automated tests +so may break in the future. + +SMBIOS tables +------------- + +To generate SMBIOS tables in U-Boot, for use by the OS, enable the +CONFIG_GENERATE_SMBIOS_TABLE option. The easiest way to provide the values to +use is via the device tree. For details see +device-tree-bindings/sysinfo/smbios.txt + +TODO List +--------- +- Audio +- Chrome OS verified boot + +.. _coreboot: http://www.coreboot.org +.. _QEMU: http://www.qemu.org +.. _microcode: http://en.wikipedia.org/wiki/Microcode +.. _SFI: http://simplefirmware.org +.. _MP: http://www.intel.com/design/archives/processors/pro/docs/242016.htm +.. _here: https://en.wikipedia.org/wiki/GUID_Partition_Table +.. _this: http://events.linuxfoundation.org/sites/events/files/slides/chromeos_and_diy_vboot_0.pdf +.. _that: http://events.linuxfoundation.org/sites/events/files/slides/elce-2014.pdf +.. _SeaBIOS: http://www.seabios.org/SeaBIOS +.. _ACPI: http://www.acpi.info diff --git a/roms/u-boot/doc/arch/xtensa.rst b/roms/u-boot/doc/arch/xtensa.rst new file mode 100644 index 000000000..176410d96 --- /dev/null +++ b/roms/u-boot/doc/arch/xtensa.rst @@ -0,0 +1,99 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +Xtensa +====== + +Xtensa Architecture and Diamond Cores +------------------------------------- + +Xtensa is a configurable processor architecture from Tensilica, Inc. +Diamond Cores are pre-configured instances available for license and +SoC cores in the same manner as ARM, MIPS, etc. + +Xtensa licensees create their own Xtensa cores with selected features +and custom instructions, registers and co-processors. The custom core +is configured with Tensilica tools and built with Tensilica's Xtensa +Processor Generator. + +There are an effectively infinite number of CPUs in the Xtensa +architecture family. It is, however, not feasible to support individual +Xtensa CPUs in U-Boot. Therefore, there is only a single 'xtensa' CPU +in the cpu tree of U-Boot. + +In the same manner as the Linux port to Xtensa, U-Boot adapts to an +individual Xtensa core configuration using a set of macros provided with +the particular core. This is part of what is known as the hardware +abstraction layer (HAL). For the purpose of U-Boot, the HAL consists only +of a few header files. These provide CPP macros that customize sources, +Makefiles, and the linker script. + + +Adding support for an additional processor configuration +-------------------------------------------------------- + +The header files for one particular processor configuration are inside +a variant-specific directory located in the arch/xtensa/include/asm +directory. The name of that directory starts with 'arch-' followed by +the name for the processor configuration, for example, arch-dc233c for +the Diamond DC233 processor. + +core.h: + Definitions for the core itself. + +The following files are part of the overlay but not used by U-Boot. + +tie.h: + Co-processors and custom extensions defined in the Tensilica Instruction + Extension (TIE) language. +tie-asm.h: + Assembly macros to access custom-defined registers and states. + + +Global Data Pointer, Exported Function Stubs, and the ABI +--------------------------------------------------------- + +To support standalone applications launched with the "go" command, +U-Boot provides a jump table of entrypoints to exported functions +(grep for EXPORT_FUNC). The implementation for Xtensa depends on +which ABI (or function calling convention) is used. + +Windowed ABI presents unique difficulties with the approach based on +keeping global data pointer in dedicated register. Because the register +window rotates during a call, there is no register that is constantly +available for the gd pointer. Therefore, on xtensa gd is a simple +global variable. Another difficulty arises from the requirement to have +an 'entry' at the beginning of a function, which rotates the register +file and reserves a stack frame. This is an integral part of the +windowed ABI implemented in hardware. It makes using a jump table to an +arbitrary (separately compiled) function a bit tricky. Use of a simple +wrapper is also very tedious due to the need to move all possible +register arguments and adjust the stack to handle arguments that cannot +be passed in registers. The most efficient approach is to have the jump +table perform the 'entry' so as to pretend it's the start of the real +function. This requires decoding the target function's 'entry' +instruction to determine the stack frame size, and adjusting the stack +pointer accordingly, then jumping into the target function just after +the 'entry'. Decoding depends on the processor's endianness so uses the +HAL. The implementation (12 instructions) is in examples/stubs.c. + + +Access to Invalid Memory Addresses +---------------------------------- + +U-Boot does not check if memory addresses given as arguments to commands +such as "md" are valid. There are two possible types of invalid +addresses: an area of physical address space may not be mapped to RAM +or peripherals, or in the presence of MMU an area of virtual address +space may not be mapped to physical addresses. + +Accessing first type of invalid addresses may result in hardware lockup, +reading of meaningless data, written data being ignored or an exception, +depending on the CPU wiring to the system. Accessing second type of +invalid addresses always ends with an exception. + +U-Boot for Xtensa provides a special memory exception handler that +reports such access attempts and resets the board. + + +.. Chris Zankel +.. Ross Morley diff --git a/roms/u-boot/doc/board/AndesTech/adp-ag101p.rst b/roms/u-boot/doc/board/AndesTech/adp-ag101p.rst new file mode 100644 index 000000000..879eba029 --- /dev/null +++ b/roms/u-boot/doc/board/AndesTech/adp-ag101p.rst @@ -0,0 +1,40 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +ADP-AG101P +========== + +ADP-AG101P is the SoC with AG101 hardcore CPU. + +AG101P SoC +---------- + +AG101P is the mainline SoC produced by Andes Technology using N1213 CPU core +with FPU and DDR contoller support. +AG101P has integrated both AHB and APB bus and many periphals for application +and product development. + + +Configurations +-------------- + +CONFIG_MEM_REMAP: + Doing memory remap is essential for preparing some non-OS or RTOS + applications. + +CONFIG_SKIP_LOWLEVEL_INIT: + If you want to boot this system from SPI ROM and bypass e-bios (the + other boot loader on ROM). You should undefine CONFIG_SKIP_LOWLEVEL_INIT + in "include/configs/adp-ag101p.h". + +Build and boot steps +-------------------- + +Build: + +1. Prepare the toolchains and make sure the $PATH to toolchains is correct. +2. Use `make adp-ag101p_defconfig` in u-boot root to build the image. + +Burn U-Boot to SPI ROM +---------------------- + +This section will be added later. diff --git a/roms/u-boot/doc/board/AndesTech/ax25-ae350.rst b/roms/u-boot/doc/board/AndesTech/ax25-ae350.rst new file mode 100644 index 000000000..b46f427f4 --- /dev/null +++ b/roms/u-boot/doc/board/AndesTech/ax25-ae350.rst @@ -0,0 +1,524 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +AX25-AE350 +========== + +AE350 is the mainline SoC produced by Andes Technology using AX25 CPU core +base on RISC-V architecture. + +AE350 has integrated both AHB and APB bus and many periphals for application +and product development. + +AX25-AE350 is the SoC with AE350 hardcore CPU. + +AX25 is Andes CPU IP to adopt RISC-V architecture. + +AX25 Features +------------- + +CPU Core + - 5-stage in-order execution pipeline + - Hardware Multiplier + - radix-2/radix-4/radix-16/radix-256/fast + - Hardware Divider + - Optional branch prediction + - Machine mode and optional user mode + - Optional performance monitoring + +ISA + - RV64I base integer instructions + - RVC for 16-bit compressed instructions + - RVM for multiplication and division instructions + +Memory subsystem + - I & D local memory + - Size: 4KB to 16MB + - Memory subsyetem soft-error protection + - Protection scheme: parity-checking or error-checking-and-correction (ECC) + - Automatic hardware error correction + +Bus + - Interface Protocol + - Synchronous AHB (32-bit/64-bit data-width), or + - Synchronous AXI4 (64-bit data-width) + +Power management + - Wait for interrupt (WFI) mode + +Debug + - Configurable number of breakpoints: 2/4/8 + - External Debug Module + - AHB slave port + - External JTAG debug transport module + +Platform Level Interrupt Controller (PLIC) + - AHB slave port + - Configurable number of interrupts: 1-1023 + - Configurable number of interrupt priorities: 3/7/15/63/127/255 + - Configurable number of targets: 1-16 + - Preempted interrupt priority stack + +Build and boot steps +-------------------- + +Build: + +1. Prepare the toolchains and make sure the $PATH to toolchains is correct. +2. Use `make ae350_rv[32|64]_defconfig` in u-boot root to build the image for + 32 or 64 bit. + +Verification: + +1. startup +2. relocation +3. timer driver +4. uart driver +5. mac driver +6. mmc driver +7. spi driver + +Steps +----- + +1. Ping a server by mac driver +2. Scan sd card and copy u-boot image which is booted from flash to ram by sd driver +3. Burn this u-boot image to spi rom by spi driver +4. Re-boot u-boot from spi flash with power off and power on + +Messages of U-Boot boot on AE350 board +-------------------------------------- + +.. code-block:: none + + U-Boot 2018.01-rc2-00033-g824f89a (Dec 21 2017 - 16:51:26 +0800) + + DRAM: 1 GiB + MMC: mmc@f0e00000: 0 + SF: Detected mx25u1635e with page size 256 Bytes, erase size 4 KiB, total 2 MiB + In: serial@f0300000 + Out: serial@f0300000 + Err: serial@f0300000 + Net: + Warning: mac@e0100000 (eth0) using random MAC address - be:dd:d7:e4:e8:10 + eth0: mac@e0100000 + + RISC-V # version + U-Boot 2018.01-rc2-00033-gb265b91-dirty (Dec 22 2017 - 13:54:21 +0800) + + riscv32-unknown-linux-gnu-gcc (GCC) 7.2.0 + GNU ld (GNU Binutils) 2.29 + + RISC-V # setenv ipaddr 10.0.4.200 ; + RISC-V # setenv serverip 10.0.4.97 ; + RISC-V # ping 10.0.4.97 ; + Using mac@e0100000 device + host 10.0.4.97 is alive + + RISC-V # mmc rescan + RISC-V # fatls mmc 0:1 + 318907 u-boot-ae350-64.bin + 1252 hello_world_ae350_32.bin + 328787 u-boot-ae350-32.bin + + 3 file(s), 0 dir(s) + + RISC-V # sf probe 0:0 50000000 0 + SF: Detected mx25u1635e with page size 256 Bytes, erase size 4 KiB, total 2 MiB + + RISC-V # sf test 0x100000 0x1000 + SPI flash test: + 0 erase: 36 ticks, 111 KiB/s 0.888 Mbps + 1 check: 29 ticks, 137 KiB/s 1.096 Mbps + 2 write: 40 ticks, 100 KiB/s 0.800 Mbps + 3 read: 20 ticks, 200 KiB/s 1.600 Mbps + Test passed + 0 erase: 36 ticks, 111 KiB/s 0.888 Mbps + 1 check: 29 ticks, 137 KiB/s 1.096 Mbps + 2 write: 40 ticks, 100 KiB/s 0.800 Mbps + 3 read: 20 ticks, 200 KiB/s 1.600 Mbps + + RISC-V # fatload mmc 0:1 0x600000 u-boot-ae350-32.bin + reading u-boot-ae350-32.bin + 328787 bytes read in 324 ms (990.2 KiB/s) + + RISC-V # sf erase 0x0 0x51000 + SF: 331776 bytes @ 0x0 Erased: OK + + RISC-V # sf write 0x600000 0x0 0x50453 + device 0 offset 0x0, size 0x50453 + SF: 328787 bytes @ 0x0 Written: OK + + RISC-V # crc32 0x600000 0x50453 + crc32 for 00600000 ... 00650452 ==> 692dc44a + + RISC-V # crc32 0x80000000 0x50453 + crc32 for 80000000 ... 80050452 ==> 692dc44a + RISC-V # + + *** power-off and power-on, this U-Boot is booted from spi flash *** + + U-Boot 2018.01-rc2-00032-gf67dd47-dirty (Dec 21 2017 - 13:56:03 +0800) + + DRAM: 1 GiB + MMC: mmc@f0e00000: 0 + SF: Detected mx25u1635e with page size 256 Bytes, erase size 4 KiB, total 2 MiB + In: serial@f0300000 + Out: serial@f0300000 + Err: serial@f0300000 + Net: + Warning: mac@e0100000 (eth0) using random MAC address - ee:4c:58:29:32:f5 + eth0: mac@e0100000 + RISC-V # + + +Boot bbl and riscv-linux via U-Boot on QEMU +------------------------------------------- + +1. Build riscv-linux +2. Build bbl and riscv-linux with --with-payload +3. Prepare ae350.dtb +4. Creating OS-kernel images + +.. code-block:: none + + ./mkimage -A riscv -O linux -T kernel -C none -a 0x0000 -e 0x0000 -d bbl.bin bootmImage-bbl.bin + Image Name: + Created: Tue Mar 13 10:06:42 2018 + Image Type: RISC-V Linux Kernel Image (uncompressed) + Data Size: 17901204 Bytes = 17481.64 KiB = 17.07 MiB + Load Address: 00000000 + Entry Point: 00000000 + +5. Copy bootmImage-bbl.bin and ae350.dtb to qemu sd card image +6. Message of booting riscv-linux from bbl via u-boot on qemu + +.. code-block:: none + + U-Boot 2018.03-rc4-00031-g2631273 (Mar 13 2018 - 15:02:55 +0800) + + DRAM: 1 GiB + main-loop: WARNING: I/O thread spun for 1000 iterations + MMC: mmc@f0e00000: 0 + Loading Environment from SPI Flash... *** Warning - spi_flash_probe_bus_cs() failed, using default environment + + Failed (-22) + In: serial@f0300000 + Out: serial@f0300000 + Err: serial@f0300000 + Net: + Warning: mac@e0100000 (eth0) using random MAC address - 02:00:00:00:00:00 + eth0: mac@e0100000 + RISC-V # mmc rescan + RISC-V # mmc part + + Partition Map for MMC device 0 -- Partition Type: DOS + + Part Start Sector Num Sectors UUID Type + RISC-V # fatls mmc 0:0 + 17901268 bootmImage-bbl.bin + 1954 ae2xx.dtb + + 2 file(s), 0 dir(s) + + RISC-V # fatload mmc 0:0 0x00600000 bootmImage-bbl.bin + 17901268 bytes read in 4642 ms (3.7 MiB/s) + RISC-V # fatload mmc 0:0 0x2000000 ae350.dtb + 1954 bytes read in 1 ms (1.9 MiB/s) + RISC-V # setenv bootm_size 0x2000000 + RISC-V # setenv fdt_high 0x1f00000 + RISC-V # bootm 0x00600000 - 0x2000000 + ## Booting kernel from Legacy Image at 00600000 ... + Image Name: + Image Type: RISC-V Linux Kernel Image (uncompressed) + Data Size: 17901204 Bytes = 17.1 MiB + Load Address: 00000000 + Entry Point: 00000000 + Verifying Checksum ... OK + ## Flattened Device Tree blob at 02000000 + Booting using the fdt blob at 0x2000000 + Loading Kernel Image ... OK + Loading Device Tree to 0000000001efc000, end 0000000001eff7a1 ... OK + [ 0.000000] OF: fdt: Ignoring memory range 0x0 - 0x200000 + [ 0.000000] Linux version 4.14.0-00046-gf3e439f-dirty (rick@atcsqa06) (gcc version 7.1.1 20170509 (GCC)) #1 Tue Jan 9 16:34:25 CST 2018 + [ 0.000000] bootconsole [early0] enabled + [ 0.000000] Initial ramdisk at: 0xffffffe000016a98 (12267008 bytes) + [ 0.000000] Zone ranges: + [ 0.000000] DMA [mem 0x0000000000200000-0x000000007fffffff] + [ 0.000000] Normal empty + [ 0.000000] Movable zone start for each node + [ 0.000000] Early memory node ranges + [ 0.000000] node 0: [mem 0x0000000000200000-0x000000007fffffff] + [ 0.000000] Initmem setup node 0 [mem 0x0000000000200000-0x000000007fffffff] + [ 0.000000] elf_hwcap is 0x112d + [ 0.000000] random: fast init done + [ 0.000000] Built 1 zonelists, mobility grouping on. Total pages: 516615 + [ 0.000000] Kernel command line: console=ttyS0,38400n8 earlyprintk=uart8250-32bit,0xf0300000 debug loglevel=7 + [ 0.000000] PID hash table entries: 4096 (order: 3, 32768 bytes) + [ 0.000000] Dentry cache hash table entries: 262144 (order: 9, 2097152 bytes) + [ 0.000000] Inode-cache hash table entries: 131072 (order: 8, 1048576 bytes) + [ 0.000000] Sorting __ex_table... + [ 0.000000] Memory: 2047832K/2095104K available (1856K kernel code, 204K rwdata, 532K rodata, 12076K init, 756K bss, 47272K reserved, 0K cma-reserved) + [ 0.000000] SLUB: HWalign=64, Order=0-3, MinObjects=0, CPUs=1, Nodes=1 + [ 0.000000] NR_IRQS: 0, nr_irqs: 0, preallocated irqs: 0 + [ 0.000000] riscv,cpu_intc,0: 64 local interrupts mapped + [ 0.000000] riscv,plic0,e4000000: mapped 31 interrupts to 1/2 handlers + [ 0.000000] clocksource: riscv_clocksource: mask: 0xffffffffffffffff max_cycles: 0x24e6a1710, max_idle_ns: 440795202120 ns + [ 0.000000] Calibrating delay loop (skipped), value calculated using timer frequency.. 20.00 BogoMIPS (lpj=40000) + [ 0.000000] pid_max: default: 32768 minimum: 301 + [ 0.004000] Mount-cache hash table entries: 4096 (order: 3, 32768 bytes) + [ 0.004000] Mountpoint-cache hash table entries: 4096 (order: 3, 32768 bytes) + [ 0.056000] devtmpfs: initialized + [ 0.060000] clocksource: jiffies: mask: 0xffffffff max_cycles: 0xffffffff, max_idle_ns: 7645041785100000 ns + [ 0.064000] futex hash table entries: 256 (order: 0, 6144 bytes) + [ 0.068000] NET: Registered protocol family 16 + [ 0.080000] vgaarb: loaded + [ 0.084000] clocksource: Switched to clocksource riscv_clocksource + [ 0.088000] NET: Registered protocol family 2 + [ 0.092000] TCP established hash table entries: 16384 (order: 5, 131072 bytes) + [ 0.096000] TCP bind hash table entries: 16384 (order: 5, 131072 bytes) + [ 0.096000] TCP: Hash tables configured (established 16384 bind 16384) + [ 0.100000] UDP hash table entries: 1024 (order: 3, 32768 bytes) + [ 0.100000] UDP-Lite hash table entries: 1024 (order: 3, 32768 bytes) + [ 0.104000] NET: Registered protocol family 1 + [ 0.616000] Unpacking initramfs... + [ 1.220000] workingset: timestamp_bits=62 max_order=19 bucket_order=0 + [ 1.244000] io scheduler noop registered + [ 1.244000] io scheduler cfq registered (default) + [ 1.244000] io scheduler mq-deadline registered + [ 1.248000] io scheduler kyber registered + [ 1.360000] Serial: 8250/16550 driver, 4 ports, IRQ sharing disabled + [ 1.368000] console [ttyS0] disabled + [ 1.372000] f0300000.serial: ttyS0 at MMIO 0xf0300020 (irq = 10, base_baud = 1228800) is a 16550A + [ 1.392000] console [ttyS0] enabled + [ 1.392000] ftmac100: Loading version 0.2 ... + [ 1.396000] ftmac100 e0100000.mac eth0: irq 8, mapped at ffffffd002005000 + [ 1.400000] ftmac100 e0100000.mac eth0: generated random MAC address 6e:ac:c3:92:36:c0 + [ 1.404000] IR NEC protocol handler initialized + [ 1.404000] IR RC5(x/sz) protocol handler initialized + [ 1.404000] IR RC6 protocol handler initialized + [ 1.404000] IR JVC protocol handler initialized + [ 1.408000] IR Sony protocol handler initialized + [ 1.408000] IR SANYO protocol handler initialized + [ 1.408000] IR Sharp protocol handler initialized + [ 1.408000] IR MCE Keyboard/mouse protocol handler initialized + [ 1.412000] IR XMP protocol handler initialized + [ 1.456000] ftsdc010 f0e00000.mmc: mmc0 - using hw SDIO IRQ + [ 1.464000] bootconsole [early0] uses init memory and must be disabled even before the real one is ready + [ 1.464000] bootconsole [early0] disabled + [ 1.508000] Freeing unused kernel memory: 12076K + [ 1.512000] This architecture does not have kernel memory protection. + [ 1.520000] mmc0: new SD card at address 4567 + [ 1.524000] mmcblk0: mmc0:4567 QEMU! 20.0 MiB + [ 1.844000] mmcblk0: + Wed Dec 1 10:00:00 CST 2010 + / # + + +Running U-Boot SPL +------------------ +The U-Boot SPL will boot in M mode and load the FIT image which include +OpenSBI and U-Boot proper images. After loading progress, it will jump +to OpenSBI first and then U-Boot proper which will run in S mode. + + +How to build U-Boot SPL +----------------------- +Before building U-Boot SPL, OpenSBI must be build first. OpenSBI can be +cloned and build for AE350 as below: + +.. code-block:: none + + git clone https://github.com/riscv/opensbi.git + cd opensbi + make PLATFORM=andes/ae350 + +Copy OpenSBI FW_DYNAMIC image (build/platform/andes/ae350/firmware/fw_dynamic.bin) +into U-Boot root directory + + +How to build U-Boot SPL booting from RAM +---------------------------------------- +With ae350_rv[32|64]_spl_defconfigs: + +U-Boot SPL will be loaded by gdb or FSBL and runs in RAM in machine mode +and then load FIT image from RAM device on AE350. + + +How to build U-Boot SPL booting from ROM +---------------------------------------- +With ae350_rv[32|64]_spl_xip_defconfigs: + +U-Boot SPL can be burned into SPI flash and run in flash in machine mode +and then load FIT image from SPI flash or MMC device on AE350. + + +Messages of U-Boot SPL boots Kernel on AE350 board +-------------------------------------------------- + +.. code-block:: none + + U-Boot SPL 2020.01-rc1-00292-g67a3313-dirty (Nov 14 2019 - 11:26:21 +0800) + Trying to boot from RAM + + OpenSBI v0.5-1-gdd8ef28 (Nov 14 2019 11:08:39) + ____ _____ ____ _____ + / __ \ / ____| _ \_ _| + | | | |_ __ ___ _ __ | (___ | |_) || | + | | | | '_ \ / _ \ '_ \ \___ \| _ < | | + | |__| | |_) | __/ | | |____) | |_) || |_ + \____/| .__/ \___|_| |_|_____/|____/_____| + | | + |_| + + Platform Name : Andes AE350 + Platform HART Features : RV64ACIMSUX + Platform Max HARTs : 4 + Current Hart : 0 + Firmware Base : 0x0 + Firmware Size : 84 KB + Runtime SBI Version : 0.2 + + PMP0: 0x0000000000000000-0x000000000001ffff (A) + PMP1: 0x0000000000000000-0x00000001ffffffff (A,R,W,X) + + + U-Boot 2020.01-rc1-00292-g67a3313-dirty (Nov 14 2019 - 11:26:21 +0800) + + DRAM: 1 GiB + Flash: 64 MiB + MMC: mmc@f0e00000: 0 + Loading Environment from SPI Flash... SF: Detected mx25u1635e with page size 256 Bytes, erase size 4 KiB, total 2 MiB + OK + In: serial@f0300000 + Out: serial@f0300000 + Err: serial@f0300000 + Net: no alias for ethernet0 + + Warning: mac@e0100000 (eth0) using random MAC address - a2:ae:93:7b:cc:8f + eth0: mac@e0100000 + Hit any key to stop autoboot: 0 + 6455 bytes read in 31 ms (203.1 KiB/s) + 20421684 bytes read in 8647 ms (2.3 MiB/s) + ## Booting kernel from Legacy Image at 00600000 ... + Image Name: + Image Type: RISC-V Linux Kernel Image (uncompressed) + Data Size: 20421620 Bytes = 19.5 MiB + Load Address: 00200000 + Entry Point: 00200000 + Verifying Checksum ... OK + ## Flattened Device Tree blob at 20000000 + Booting using the fdt blob at 0x20000000 + Loading Kernel Image + Loading Device Tree to 000000001effb000, end 000000001efff936 ... OK + + Starting kernel ... + + OF: fdt: Ignoring memory range 0x0 - 0x200000 + Linux version 4.17.0-00253-g49136e10bcb2 (sqa@atcsqa07) (gcc version 7.3.0 (2019-04-06_nds64le-linux-glibc-v5_experimental)) #1 SMP PREEMPT Sat Apr 6 23:41:49 CST 2019 + bootconsole [early0] enabled + Initial ramdisk at: 0x (ptrval) (13665712 bytes) + Zone ranges: + DMA32 [mem 0x0000000000200000-0x000000003fffffff] + Normal empty + Movable zone start for each node + Early memory node ranges + node 0: [mem 0x0000000000200000-0x000000003fffffff] + Initmem setup node 0 [mem 0x0000000000200000-0x000000003fffffff] + software IO TLB [mem 0x3b1f8000-0x3f1f8000] (64MB) mapped at [ (ptrval)- (ptrval)] + elf_platform is rv64i2p0m2p0a2p0c2p0xv5-0p0 + compatible privileged spec version 1.10 + percpu: Embedded 16 pages/cpu @ (ptrval) s28184 r8192 d29160 u65536 + Built 1 zonelists, mobility grouping on. Total pages: 258055 + Kernel command line: console=ttyS0,38400n8 debug loglevel=7 + log_buf_len individual max cpu contribution: 4096 bytes + log_buf_len total cpu_extra contributions: 12288 bytes + log_buf_len min size: 16384 bytes + log_buf_len: 32768 bytes + early log buf free: 14608(89%) + Dentry cache hash table entries: 131072 (order: 8, 1048576 bytes) + Inode-cache hash table entries: 65536 (order: 7, 524288 bytes) + Sorting __ex_table... + Memory: 944428K/1046528K available (3979K kernel code, 246K rwdata, 1490K rodata, 13523K init, 688K bss, 102100K reserved, 0K cma-reserved) + SLUB: HWalign=64, Order=0-3, MinObjects=0, CPUs=4, Nodes=1 + Preemptible hierarchical RCU implementation. + Tasks RCU enabled. + NR_IRQS: 72, nr_irqs: 72, preallocated irqs: 0 + riscv,cpu_intc,0: 64 local interrupts mapped + riscv,cpu_intc,1: 64 local interrupts mapped + riscv,cpu_intc,2: 64 local interrupts mapped + riscv,cpu_intc,3: 64 local interrupts mapped + riscv,plic0,e4000000: mapped 71 interrupts to 8/8 handlers + clocksource: riscv_clocksource: mask: 0xffffffffffffffff max_cycles: 0x1bacf917bf, max_idle_ns: 881590412290 ns + sched_clock: 64 bits at 60MHz, resolution 16ns, wraps every 4398046511098ns + Console: colour dummy device 40x30 + Calibrating delay loop (skipped), value calculated using timer frequency.. 120.00 BogoMIPS (lpj=600000) + pid_max: default: 32768 minimum: 301 + Mount-cache hash table entries: 2048 (order: 2, 16384 bytes) + Mountpoint-cache hash table entries: 2048 (order: 2, 16384 bytes) + Hierarchical SRCU implementation. + smp: Bringing up secondary CPUs ... + CPU0: online + CPU2: online + CPU3: online + smp: Brought up 1 node, 4 CPUs + devtmpfs: initialized + random: get_random_u32 called from bucket_table_alloc+0x198/0x1d8 with crng_init=0 + clocksource: jiffies: mask: 0xffffffff max_cycles: 0xffffffff, max_idle_ns: 19112604462750000 ns + futex hash table entries: 1024 (order: 4, 65536 bytes) + NET: Registered protocol family 16 + Advanced Linux Sound Architecture Driver Initialized. + clocksource: Switched to clocksource riscv_clocksource + NET: Registered protocol family 2 + tcp_listen_portaddr_hash hash table entries: 512 (order: 1, 8192 bytes) + TCP established hash table entries: 8192 (order: 4, 65536 bytes) + TCP bind hash table entries: 8192 (order: 5, 131072 bytes) + TCP: Hash tables configured (established 8192 bind 8192) + UDP hash table entries: 512 (order: 2, 16384 bytes) + UDP-Lite hash table entries: 512 (order: 2, 16384 bytes) + NET: Registered protocol family 1 + RPC: Registered named UNIX socket transport module. + RPC: Registered udp transport module. + RPC: Registered tcp transport module. + RPC: Registered tcp NFSv4.1 backchannel transport module. + Unpacking initramfs... + workingset: timestamp_bits=62 max_order=18 bucket_order=0 + NFS: Registering the id_resolver key type + Key type id_resolver registered + Key type id_legacy registered + nfs4filelayout_init: NFSv4 File Layout Driver Registering... + io scheduler noop registered + io scheduler cfq registered (default) + io scheduler mq-deadline registered + io scheduler kyber registered + Console: switching to colour frame buffer device 40x30 + Serial: 8250/16550 driver, 4 ports, IRQ sharing disabled + console [ttyS0] disabled + f0300000.serial: ttyS0 at MMIO 0xf0300020 (irq = 20, base_baud = 1228800) is a 16550A + console [ttyS0] enabled + console [ttyS0] enabled + bootconsole [early0] disabled + bootconsole [early0] disabled + loop: module loaded + tun: Universal TUN/TAP device driver, 1.6 + ftmac100: Loading version 0.2 ... + ftmac100 e0100000.mac eth0: irq 21, mapped at (ptrval) + ftmac100 e0100000.mac eth0: generated random MAC address 4e:fd:bd:f3:04:fc + ftsdc010 f0e00000.mmc: mmc0 - using hw SDIO IRQ + mmc0: new SDHC card at address d555 + ftssp010 card registered! + mmcblk0: mmc0:d555 SD04G 3.79 GiB + NET: Registered protocol family 10 + mmcblk0: p1 + Segment Routing with IPv6 + sit: IPv6, IPv4 and MPLS over IPv4 tunneling driver + NET: Registered protocol family 17 + NET: Registered protocol family 15 + ALSA device list: + #0: ftssp_ac97 controller + Freeing unused kernel memory: 13520K + This architecture does not have kernel memory protection. + Sysinit starting + Sat Apr 6 23:33:53 CST 2019 + nfs4flexfilelayout_init: NFSv4 Flexfile Layout Driver Registering... + + ~ # diff --git a/roms/u-boot/doc/board/AndesTech/index.rst b/roms/u-boot/doc/board/AndesTech/index.rst new file mode 100644 index 000000000..d8f7d155f --- /dev/null +++ b/roms/u-boot/doc/board/AndesTech/index.rst @@ -0,0 +1,10 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +Andes Tech +========== + +.. toctree:: + :maxdepth: 2 + + adp-ag101p + ax25-ae350 diff --git a/roms/u-boot/doc/board/actions/cubieboard7.rst b/roms/u-boot/doc/board/actions/cubieboard7.rst new file mode 100644 index 000000000..74f2b12e4 --- /dev/null +++ b/roms/u-boot/doc/board/actions/cubieboard7.rst @@ -0,0 +1,114 @@ +.. SPDX-License-Identifier: GPL-2.0+ +.. Copyright (C) 2020 Amit Singh Tomar <amittomer25@gmail.com> + +CUBIEBOARD7 +=========== + +About this +---------- + +This document describes build and flash steps for Actions S700 SoC based Cubieboard7 +board. + +Cubieboard7 initial configuration +--------------------------------- + +Default Cubieboard7 comes with pre-installed Android where U-Boot is configured with +a bootdelay of 0, entering a prompt by pressing keys does not seem to work. + +Though, one can enter ADFU mode and flash debian image(from host machine) where +getting into u-boot prompt is easy. + +Enter ADFU Mode +---------------- + +Before write the firmware, let the development board entering the ADFU mode: insert +one end of the USB cable to the PC, press and hold the ADFU button, and then connect +the other end of the USB cable to the Mini USB port of the development board, release +the ADFU button, after connecting it will enter the ADFU mode. + +Check whether entered ADFU Mode +-------------------------------- + +The user needs to run the following command on the PC side to check if the ADFU +device is detected. ID realted to "Actions Semiconductor Co., Ltd" means that +the PC side has been correctly detected ADFU device, the development board +also enter into the ADFU mode. + +.. code-block:: none + + $ lsusb + Bus 001 Device 005: ID 04f2:b2eb Chicony Electronics Co., Ltd + Bus 001 Device 004: ID 0a5c:21e6 Broadcom Corp. BCM20702 Bluetooth 4.0 [ThinkPad] + Bus 001 Device 003: ID 046d:c534 Logitech, Inc. Unifying Receiver + Bus 001 Device 002: ID 8087:0024 Intel Corp. Integrated Rate Matching Hub + Bus 001 Device 001: ID 1d6b:0002 Linux Foundation 2.0 root hub + Bus 004 Device 001: ID 1d6b:0003 Linux Foundation 3.0 root hub + Bus 003 Device 013: ID 10d6:10d6 Actions Semiconductor Co., Ltd + Bus 003 Device 001: ID 1d6b:0002 Linux Foundation 2.0 root hub + +Flashing debian image +--------------------- + +.. code-block:: none + + $ sudo ./ActionsFWU.py --fw=debian-stretch-desktop-cb7-emmc-v2.0.fw + ActionsFWU.py : 1.0.150828.0830 + libScript.so : 2.3.150825.0951 + libFileSystem.so: 2.3.150825.0952 + libProduction.so: 2.3.150915.1527 + =====burn all partition==== + FW_VER: 3.10.37.180608 + 3% DOWNLOAD ADFUDEC ... + 5% DOWNLOAD BOOT PARA ... + 7% SWITCH ADFUDEC ... + 12% DOWNLOAD BL31 ... + 13% DOWNLOAD BL32 ... + 15% DOWNLOAD VMLINUX ... + 20% DOWNLOAD INITRD ... + 24% DOWNLOAD FDT ... + 27% DOWNLOAD ADFUS ... + 30% SWITCH ADFUS ... + 32% DOWNLOAD MBR ... + 35% DOWNLOAD PARTITIONS ... + WRITE_MBRC_PARTITION + 35% write p0 size = 2048 : ok + WRITE_BOOT_PARTITION + 35% write p1 size = 2048 : ok + WRITE_MISC_PARTITION + 36% write p2 size = 98304 : ok + WRITE_SYSTEM_PARTITION + 94% write p3 size = 4608000 : ok + FORMAT_SWAP_PARTITION + 94% write p4 size = 20480 : ok + 95% TRANSFER OVER ... + Firmware upgrade successfully! + +Debian image can be downloaded from here[1]. + +Once debian image is flashed, one can get into u-boot prompt by pressing any key and from +there run ums command(make sure, usb cable is connected between host and target): + +.. code-block:: none + + owl> ums 0 mmc 1 + +Above command would mount debian image partition on host machine. + +Building U-BOOT proper image +---------------------------- + +.. code-block:: none + + $ make clean + $ export CROSS_COMPILE=aarch64-linux-gnu- + $ make cubieboard7_defconfig + $ make u-boot-dtb.img -j16 + +u-boot-dtb.img can now be flashed to debian image partition mounted on host machine. + +.. code-block:: none + + $ sudo dd if=u-boot-dtb.img of=/dev/sdb bs=1024 seek=3072 + +[1]: https://pan.baidu.com/s/1uawPr0Jao2HgWFLZCLzHAg#list/path=%2FCubieBoard_Download%2FBoard%2FCubieBoard7%2F%E6%96%B9%E7%B3%96%E6%96%B9%E6%A1%88%E5%BC%80%E5%8F%91%E8%B5%84%E6%96%99%2FImage%2FDebian%2FV2.1-test&parentPath=%2F diff --git a/roms/u-boot/doc/board/actions/index.rst b/roms/u-boot/doc/board/actions/index.rst new file mode 100644 index 000000000..c59687915 --- /dev/null +++ b/roms/u-boot/doc/board/actions/index.rst @@ -0,0 +1,10 @@ +.. SPDX-License-Identifier: GPL-2.0+ +.. Copyright (C) 2020 Amit Singh Tomar <amittomer25@gmail.com> + +Actions +======== + +.. toctree:: + :maxdepth: 2 + + cubieboard7 diff --git a/roms/u-boot/doc/board/advantech/imx8qm-rom7720-a1.rst b/roms/u-boot/doc/board/advantech/imx8qm-rom7720-a1.rst new file mode 100644 index 000000000..bd4be1dbe --- /dev/null +++ b/roms/u-boot/doc/board/advantech/imx8qm-rom7720-a1.rst @@ -0,0 +1,75 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +U-Boot for the NXP i.MX8QM ROM 7720a1 board +=========================================== + +Quick Start +----------- + +- Build the ARM Trusted firmware binary +- Get scfw_tcm.bin and ahab-container.img +- Get imx-mkimage +- Build U-Boot +- Build imx-mkimage +- Flash the binary into the SD card +- Boot + +Get and Build the ARM Trusted firmware +-------------------------------------- + +.. code-block:: bash + + $ git clone https://source.codeaurora.org/external/imx/imx-atf + $ cd imx-atf/ + $ git checkout origin/imx_4.14.78_1.0.0_ga -b imx_4.14.78_1.0.0_ga + $ make PLAT=imx8qm bl31 + +Get scfw_tcm.bin and ahab-container.img +--------------------------------------- + +.. code-block:: bash + + $ wget https://www.nxp.com/lgfiles/NMG/MAD/YOCTO/imx-sc-firmware-1.1.bin + $ chmod +x imx-sc-firmware-1.1.bin + $ ./imx-sc-firmware-1.1.bin + $ wget https://www.nxp.com/lgfiles/NMG/MAD/YOCTO/firmware-imx-8.0.bin + $ chmod +x firmware-imx-8.0.bin + $ ./firmware-imx-8.0.bin + +Or use this to avoid running random scripts from the internet, +but note that you must agree to the license the script displays: + +.. code-block:: bash + + $ dd if=imx-sc-firmware-1.1.bin of=imx-sc-firmware-1.1.tar.bz2 bs=37185 skip=1 + $ tar -xf imx-sc-firmware-1.1.tar.bz2 + $ cp imx-sc-firmware-1.1/mx8qm-val-scfw-tcm.bin $(builddir) + + $ dd if=firmware-imx-8.0.bin of=firmware-imx-8.0.tar.bz2 bs=37180 skip=1 + $ tar -xf firmware-imx-8.0.tar.bz2 + $ cp firmware-imx-8.0/firmware/seco/mx8qm-ahab-container.img $(builddir) + +Build U-Boot +------------ + +.. code-block:: bash + + $ export ATF_LOAD_ADDR=0x80000000 + $ export BL33_LOAD_ADDR=0x80020000 + $ make imx8qm_rom7720_a1_4G_defconfig + $ make u-boot.bin + $ make flash.bin + +Flash the binary into the SD card +--------------------------------- + +Burn the flash.bin binary to SD card offset 32KB: + +.. code-block:: bash + + $ sudo dd if=flash.bin of=/dev/sd[x] bs=1k seek=32 conv=fsync + +Boot +---- + +Set Boot switch SW2: 1100. diff --git a/roms/u-boot/doc/board/advantech/index.rst b/roms/u-boot/doc/board/advantech/index.rst new file mode 100644 index 000000000..e9b198c5c --- /dev/null +++ b/roms/u-boot/doc/board/advantech/index.rst @@ -0,0 +1,9 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +Advantech +========= + +.. toctree:: + :maxdepth: 2 + + imx8qm-rom7720-a1.rst diff --git a/roms/u-boot/doc/board/amlogic/beelink-gtking.rst b/roms/u-boot/doc/board/amlogic/beelink-gtking.rst new file mode 100644 index 000000000..56ce2cb27 --- /dev/null +++ b/roms/u-boot/doc/board/amlogic/beelink-gtking.rst @@ -0,0 +1,115 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +U-Boot for Beelink GT-King +========================== + +The Shenzen AZW (Beelink) GT-King is based on the Amlogic W400 reference +board with an S922X-H chip. + +- 4GB LPDDR4 RAM +- 64GB eMMC storage +- 10/100/1000 Base-T Ethernet +- AP6356S Wireless (802.11 a/b/g/n/ac, BT 4.1) +- HDMI 2.1 video +- S/PDIF optical output +- Analogue audio output +- 1x USB 2.0 port +- 2x USB 3.0 ports +- IR receiver +- 1x micro SD card slot + +Beelink do not provide public schematics, but have been willing +to share them with known distro developers on request. + +U-Boot compilation +------------------ + +.. code-block:: bash + + $ export CROSS_COMPILE=aarch64-none-elf- + $ make beelink-gtking_defconfig + $ make + +Image creation +-------------- + +Amlogic does not provide sources for the firmware and for tools needed +to create the bootloader image. Beelink have provided the Amlogic "SDK" +in their forums, but the u-boot sources included result in 2GB RAM being +detected. The following FIPs were generated with newer private sources +and give correct (4GB) RAM detection: + +https://github.com/LibreELEC/amlogic-boot-fip/tree/master/beelink-s922x + +NB: Beelink use a common board config for GT-King, GT-King Pro and the +GS-King-X model, hence the "beelink-s922x" name. + +.. code-block:: bash + + $ wget https://github.com/LibreELEC/amlogic-boot-fip/archive/master.zip + $ unzip master.zip + $ export FIPDIR=$PWD/amlogic-boot-fip/beelink-s922x + +Go back to the mainline U-Boot source tree then: + +.. code-block:: bash + + $ mkdir fip + $ cp $FIPDIR/* fip/ + $ cp u-boot.bin fip/bl33.bin + + $ sh fip/blx_fix.sh \ + fip/bl30.bin \ + fip/zero_tmp \ + fip/bl30_zero.bin \ + fip/bl301.bin \ + fip/bl301_zero.bin \ + fip/bl30_new.bin \ + bl30 + + $ sh fip/blx_fix.sh \ + fip/bl2.bin \ + fip/zero_tmp \ + fip/bl2_zero.bin \ + fip/acs.bin \ + fip/bl21_zero.bin \ + fip/bl2_new.bin \ + bl2 + + $ fip/aml_encrypt_g12b --bl30sig --input fip/bl30_new.bin \ + --output fip/bl30_new.bin.g12a.enc \ + --level v3 + $ fip/aml_encrypt_g12b --bl3sig --input fip/bl30_new.bin.g12a.enc \ + --output fip/bl30_new.bin.enc \ + --level v3 --type bl30 + $ fip/aml_encrypt_g12b --bl3sig --input fip/bl31.img \ + --output fip/bl31.img.enc \ + --level v3 --type bl31 + $ fip/aml_encrypt_g12b --bl3sig --input fip/bl33.bin --compress lz4 \ + --output fip/bl33.bin.enc \ + --level v3 --type bl33 + $ fip/aml_encrypt_g12b --bl2sig --input fip/bl2_new.bin \ + --output fip/bl2.n.bin.sig + $ fip/aml_encrypt_g12b --bootmk \ + --output fip/u-boot.bin \ + --bl2 fip/bl2.n.bin.sig \ + --bl30 fip/bl30_new.bin.enc \ + --bl31 fip/bl31.img.enc \ + --bl33 fip/bl33.bin.enc \ + --ddrfw1 fip/ddr4_1d.fw \ + --ddrfw2 fip/ddr4_2d.fw \ + --ddrfw3 fip/ddr3_1d.fw \ + --ddrfw4 fip/piei.fw \ + --ddrfw5 fip/lpddr4_1d.fw \ + --ddrfw6 fip/lpddr4_2d.fw \ + --ddrfw7 fip/diag_lpddr4.fw \ + --ddrfw8 fip/aml_ddr.fw \ + --level v3 + +and then write the image to SD with: + +.. code-block:: bash + + $ DEV=/dev/your_sd_device + $ dd if=fip/u-boot.bin.sd.bin of=$DEV conv=fsync,notrunc bs=512 skip=1 seek=1 + $ dd if=fip/u-boot.bin.sd.bin of=$DEV conv=fsync,notrunc bs=1 count=444 diff --git a/roms/u-boot/doc/board/amlogic/beelink-gtkingpro.rst b/roms/u-boot/doc/board/amlogic/beelink-gtkingpro.rst new file mode 100644 index 000000000..d75035136 --- /dev/null +++ b/roms/u-boot/doc/board/amlogic/beelink-gtkingpro.rst @@ -0,0 +1,116 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +U-Boot for Beelink GT-King Pro +============================== + +The Shenzen AZW (Beelink) GT-King Pro is based on the Amlogic W400 reference +board with an S922X-H chip. + +- 4GB LPDDR4 RAM +- 64GB eMMC storage +- 10/100/1000 Base-T Ethernet +- AP6356S Wireless (802.11 a/b/g/n/ac, BT 4.1) +- HDMI 2.1 video +- Analogue audio output +- 1x RS232 port +- 2x USB 2.0 port +- 2x USB 3.0 ports +- IR receiver +- 1x SD card slot +- 1x Power on/off button + +Beelink do not provide public schematics, but have been willing +to share them with known distro developers on request. + +U-Boot compilation +------------------ + +.. code-block:: bash + + $ export CROSS_COMPILE=aarch64-none-elf- + $ make beelink-gtkingpro_defconfig + $ make + +Image creation +-------------- + +Amlogic does not provide sources for the firmware and for tools needed +to create the bootloader image. Beelink have provided the Amlogic "SDK" +in their forums, but the u-boot sources included result in 2GB RAM being +detected. The following FIPs were generated with newer private sources +and give correct (4GB) RAM detection: + +https://github.com/LibreELEC/amlogic-boot-fip/tree/master/beelink-s922x + +NB: Beelink use a common board config for GT-King, GT-King Pro and the +GS-King-X model, hence the "beelink-s922x" name. + +.. code-block:: bash + + $ wget https://github.com/LibreELEC/amlogic-boot-fip/archive/master.zip + $ unzip master.zip + $ export FIPDIR=$PWD/amlogic-boot-fip/beelink-s922x + +Go back to the mainline U-Boot source tree then: + +.. code-block:: bash + + $ mkdir fip + $ cp $FIPDIR/* fip/ + $ cp u-boot.bin fip/bl33.bin + + $ sh fip/blx_fix.sh \ + fip/bl30.bin \ + fip/zero_tmp \ + fip/bl30_zero.bin \ + fip/bl301.bin \ + fip/bl301_zero.bin \ + fip/bl30_new.bin \ + bl30 + + $ sh fip/blx_fix.sh \ + fip/bl2.bin \ + fip/zero_tmp \ + fip/bl2_zero.bin \ + fip/acs.bin \ + fip/bl21_zero.bin \ + fip/bl2_new.bin \ + bl2 + + $ fip/aml_encrypt_g12b --bl30sig --input fip/bl30_new.bin \ + --output fip/bl30_new.bin.g12a.enc \ + --level v3 + $ fip/aml_encrypt_g12b --bl3sig --input fip/bl30_new.bin.g12a.enc \ + --output fip/bl30_new.bin.enc \ + --level v3 --type bl30 + $ fip/aml_encrypt_g12b --bl3sig --input fip/bl31.img \ + --output fip/bl31.img.enc \ + --level v3 --type bl31 + $ fip/aml_encrypt_g12b --bl3sig --input fip/bl33.bin --compress lz4 \ + --output fip/bl33.bin.enc \ + --level v3 --type bl33 + $ fip/aml_encrypt_g12b --bl2sig --input fip/bl2_new.bin \ + --output fip/bl2.n.bin.sig + $ fip/aml_encrypt_g12b --bootmk \ + --output fip/u-boot.bin \ + --bl2 fip/bl2.n.bin.sig \ + --bl30 fip/bl30_new.bin.enc \ + --bl31 fip/bl31.img.enc \ + --bl33 fip/bl33.bin.enc \ + --ddrfw1 fip/ddr4_1d.fw \ + --ddrfw2 fip/ddr4_2d.fw \ + --ddrfw3 fip/ddr3_1d.fw \ + --ddrfw4 fip/piei.fw \ + --ddrfw5 fip/lpddr4_1d.fw \ + --ddrfw6 fip/lpddr4_2d.fw \ + --ddrfw7 fip/diag_lpddr4.fw \ + --ddrfw8 fip/aml_ddr.fw \ + --level v3 + +and then write the image to SD with: + +.. code-block:: bash + + $ DEV=/dev/your_sd_device + $ dd if=fip/u-boot.bin.sd.bin of=$DEV conv=fsync,notrunc bs=512 skip=1 seek=1 + $ dd if=fip/u-boot.bin.sd.bin of=$DEV conv=fsync,notrunc bs=1 count=444 diff --git a/roms/u-boot/doc/board/amlogic/index.rst b/roms/u-boot/doc/board/amlogic/index.rst new file mode 100644 index 000000000..8da7afddb --- /dev/null +++ b/roms/u-boot/doc/board/amlogic/index.rst @@ -0,0 +1,103 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +Amlogic +======= + +Hardware Support Matrix +----------------------- + +An up-do-date matrix is also available on: http://linux-meson.com + +This matrix concerns the actual source code version. + ++-------------------------------+-----------+-----------------+--------------+------------+------------+-------------+--------------+ +| | S905 | S905X | S912 | A113X | S905X2 | S922X | S905X3 | +| | | S805X | S905D | | S905D2 | A311D | S905D3 | +| | | | | | S905Y2 | | | ++===============================+===========+=================+==============+============+============+=============+==============+ +| Boards | Odroid-C2 | P212 | Khadas VIM2 | S400 | U200 | Odroid-N2 | SEI610 | +| | Nanopi-K2 | Khadas-VIM | Libretech-PC | | SEI510 | Khadas-VIM3 | Khadas-VIM3L | +| | P200 | LibreTech-CC v1 | WeTek Core2 | | | GT-King/Pro | Odroid-C4 | +| | P201 | LibreTech-AC v2 | | | | | | ++-------------------------------+-----------+-----------------+--------------+------------+------------+-------------+--------------+ +| UART | **Yes** | **Yes** | **Yes** | **Yes** | **Yes** | **Yes** | **Yes** | ++-------------------------------+-----------+-----------------+--------------+------------+------------+-------------+--------------+ +| Pinctrl/GPIO | **Yes** | **Yes** | **Yes** | **Yes** | **Yes** | **Yes** | **Yes** | ++-------------------------------+-----------+-----------------+--------------+------------+------------+-------------+--------------+ +| Clock Control | **Yes** | **Yes** | **Yes** | **Yes** | **Yes** | **Yes** | **Yes** | ++-------------------------------+-----------+-----------------+--------------+------------+------------+-------------+--------------+ +| PWM | **Yes** | **Yes** | **Yes** | **Yes** | **Yes** | **Yes** | **Yes** | ++-------------------------------+-----------+-----------------+--------------+------------+------------+-------------+--------------+ +| Reset Control | **Yes** | **Yes** | **Yes** | **Yes** | **Yes** | **Yes** | **Yes** | ++-------------------------------+-----------+-----------------+--------------+------------+------------+-------------+--------------+ +| Infrared Decoder | No | No | No | No | No | No | No | ++-------------------------------+-----------+-----------------+--------------+------------+------------+-------------+--------------+ +| Ethernet | **Yes** | **Yes** | **Yes** | **Yes** | **Yes** | **Yes** | **Yes** | ++-------------------------------+-----------+-----------------+--------------+------------+------------+-------------+--------------+ +| Multi-core | **Yes** | **Yes** | **Yes** | **Yes** | **Yes** | **Yes** | **Yes** | ++-------------------------------+-----------+-----------------+--------------+------------+------------+-------------+--------------+ +| Fuse access | **Yes** | **Yes** |**Yes** |**Yes** |**Yes** |**Yes** | **Yes** | ++-------------------------------+-----------+-----------------+--------------+------------+------------+-------------+--------------+ +| SPI (FC) | **Yes** | **Yes** | **Yes** | **Yes** |**Yes** | **Yes** | No | ++-------------------------------+-----------+-----------------+--------------+------------+------------+-------------+--------------+ +| SPI (CC) | No | No | No | No | No | No | No | ++-------------------------------+-----------+-----------------+--------------+------------+------------+-------------+--------------+ +| I2C | **Yes** | **Yes** | **Yes** | **Yes** | **Yes** | **Yes** | **Yes** | ++-------------------------------+-----------+-----------------+--------------+------------+------------+-------------+--------------+ +| USB | **Yes** | **Yes** | **Yes** | **Yes** | **Yes** | **Yes** | **Yes** | ++-------------------------------+-----------+-----------------+--------------+------------+------------+-------------+--------------+ +| USB OTG | No | **Yes** | **Yes** | **Yes** | **Yes** | **Yes** | **Yes** | ++-------------------------------+-----------+-----------------+--------------+------------+------------+-------------+--------------+ +| eMMC | **Yes** | **Yes** | **Yes** | **Yes** | **Yes** | **Yes** | **Yes** | ++-------------------------------+-----------+-----------------+--------------+------------+------------+-------------+--------------+ +| SDCard | **Yes** | **Yes** | **Yes** | **Yes** | **Yes** | **Yes** | **Yes** | ++-------------------------------+-----------+-----------------+--------------+------------+------------+-------------+--------------+ +| NAND | No | No | No | No | No | No | No | ++-------------------------------+-----------+-----------------+--------------+------------+------------+-------------+--------------+ +| ADC | **Yes** | **Yes** | **Yes** | No | No | No | No | ++-------------------------------+-----------+-----------------+--------------+------------+------------+-------------+--------------+ +| CVBS Output | **Yes** | **Yes** | **Yes** | *N/A* | **Yes** | **Yes** | **Yes** | ++-------------------------------+-----------+-----------------+--------------+------------+------------+-------------+--------------+ +| HDMI Output | **Yes** | **Yes** | **Yes** | *N/A* | **Yes** | **Yes** | **Yes** | ++-------------------------------+-----------+-----------------+--------------+------------+------------+-------------+--------------+ +| CEC | No | No | No | *N/A* | No | No | No | ++-------------------------------+-----------+-----------------+--------------+------------+------------+-------------+--------------+ +| Thermal Sensor | No | No | No | No | No | No | No | ++-------------------------------+-----------+-----------------+--------------+------------+------------+-------------+--------------+ +| LCD/LVDS Output | No | *N/A* | No | No | No | No | No | ++-------------------------------+-----------+-----------------+--------------+------------+------------+-------------+--------------+ +| MIPI DSI Output | *N/A* | *N/A* | *N/A* | No | No | No | No | ++-------------------------------+-----------+-----------------+--------------+------------+------------+-------------+--------------+ +| SoC (version) information | **Yes** | **Yes** | **Yes** | **Yes** | **Yes** | **Yes** | **Yes** | ++-------------------------------+-----------+-----------------+--------------+------------+------------+-------------+--------------+ +| PCIe (+NVMe) | *N/A* | *N/A* | *N/A* | **Yes** | **Yes** | **Yes** | **Yes** | ++-------------------------------+-----------+-----------------+--------------+------------+------------+-------------+--------------+ + +Board Documentation +------------------- + +.. toctree:: + :maxdepth: 1 + + beelink-gtking + beelink-gtkingpro + khadas-vim2 + khadas-vim3l + khadas-vim3 + khadas-vim + libretech-ac + libretech-cc + nanopi-k2 + odroid-c2 + odroid-c4 + odroid-n2 + p200 + p201 + p212 + q200 + s400 + sei510 + sei610 + u200 + wetek-core2 + w400 diff --git a/roms/u-boot/doc/board/amlogic/khadas-vim.rst b/roms/u-boot/doc/board/amlogic/khadas-vim.rst new file mode 100644 index 000000000..bbb61c29e --- /dev/null +++ b/roms/u-boot/doc/board/amlogic/khadas-vim.rst @@ -0,0 +1,101 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +U-Boot for Khadas VIM +====================== + +Khadas VIM is an Open Source DIY Box manufactured by Shenzhen Wesion +Technology Co., Ltd with the following specifications: + + - Amlogic S905X ARM Cortex-A53 quad-core SoC @ 1.5GHz + - ARM Mali 450 GPU + - 2GB DDR3 SDRAM + - 10/100 Ethernet + - HDMI 2.0 4K/60Hz display + - 40-pin GPIO header + - 2 x USB 2.0 Host, 1 x USB 2.0 Type-C OTG + - 8GB/16GBeMMC + - microSD + - SDIO Wifi Module, Bluetooth + - Two channels IR receiver + +U-Boot compilation +------------------ + +.. code-block:: bash + + $ export CROSS_COMPILE=aarch64-none-elf- + $ make khadas-vim_defconfig + $ make + +Image creation +-------------- + +Amlogic doesn't provide sources for the firmware and for tools needed +to create the bootloader image, so it is necessary to obtain them from +the git tree published by the board vendor: + +.. code-block:: bash + + $ wget https://releases.linaro.org/archive/13.11/components/toolchain/binaries/gcc-linaro-aarch64-none-elf-4.8-2013.11_linux.tar.xz + $ wget https://releases.linaro.org/archive/13.11/components/toolchain/binaries/gcc-linaro-arm-none-eabi-4.8-2013.11_linux.tar.xz + $ tar xvfJ gcc-linaro-aarch64-none-elf-4.8-2013.11_linux.tar.xz + $ tar xvfJ gcc-linaro-arm-none-eabi-4.8-2013.11_linux.tar.xz + $ export PATH=$PWD/gcc-linaro-aarch64-none-elf-4.8-2013.11_linux/bin:$PWD/gcc-linaro-arm-none-eabi-4.8-2013.11_linux/bin:$PATH + $ git clone https://github.com/khadas/u-boot -b Vim vim-u-boot + $ cd vim-u-boot + $ make kvim_defconfig + $ make CROSS_COMPILE=aarch64-none-elf- + $ export FIPDIR=$PWD/fip + +Go back to mainline U-Boot source tree then : + +.. code-block:: bash + + $ mkdir fip + + $ cp $FIPDIR/gxl/bl2.bin fip/ + $ cp $FIPDIR/gxl/acs.bin fip/ + $ cp $FIPDIR/gxl/bl21.bin fip/ + $ cp $FIPDIR/gxl/bl30.bin fip/ + $ cp $FIPDIR/gxl/bl301.bin fip/ + $ cp $FIPDIR/gxl/bl31.img fip/ + $ cp u-boot.bin fip/bl33.bin + + $ $FIPDIR/blx_fix.sh \ + fip/bl30.bin \ + fip/zero_tmp \ + fip/bl30_zero.bin \ + fip/bl301.bin \ + fip/bl301_zero.bin \ + fip/bl30_new.bin \ + bl30 + + $ python $FIPDIR/acs_tool.pyc fip/bl2.bin fip/bl2_acs.bin fip/acs.bin 0 + + $ $FIPDIR/blx_fix.sh \ + fip/bl2_acs.bin \ + fip/zero_tmp \ + fip/bl2_zero.bin \ + fip/bl21.bin \ + fip/bl21_zero.bin \ + fip/bl2_new.bin \ + bl2 + + $ $FIPDIR/gxl/aml_encrypt_gxl --bl3enc --input fip/bl30_new.bin + $ $FIPDIR/gxl/aml_encrypt_gxl --bl3enc --input fip/bl31.img + $ $FIPDIR/gxl/aml_encrypt_gxl --bl3enc --input fip/bl33.bin + $ $FIPDIR/gxl/aml_encrypt_gxl --bl2sig --input fip/bl2_new.bin --output fip/bl2.n.bin.sig + $ $FIPDIR/gxl/aml_encrypt_gxl --bootmk \ + --output fip/u-boot.bin \ + --bl2 fip/bl2.n.bin.sig \ + --bl30 fip/bl30_new.bin.enc \ + --bl31 fip/bl31.img.enc \ + --bl33 fip/bl33.bin.enc + +and then write the image to SD with: + +.. code-block:: bash + + $ DEV=/dev/your_sd_device + $ dd if=fip/u-boot.bin.sd.bin of=$DEV conv=fsync,notrunc bs=512 skip=1 seek=1 + $ dd if=fip/u-boot.bin.sd.bin of=$DEV conv=fsync,notrunc bs=1 count=444 diff --git a/roms/u-boot/doc/board/amlogic/khadas-vim2.rst b/roms/u-boot/doc/board/amlogic/khadas-vim2.rst new file mode 100644 index 000000000..c57d96d8b --- /dev/null +++ b/roms/u-boot/doc/board/amlogic/khadas-vim2.rst @@ -0,0 +1,102 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +U-Boot for Khadas VIM2 +======================= + +Khadas VIM2 is an Open Source DIY Box manufactured by Shenzhen Wesion +Technology Co., Ltd with the following specifications: + + - Amlogic S912 ARM Cortex-A53 octo-core SoC @ 1.5GHz + - ARM Mali T860 GPU + - 2/3GB DDR4 SDRAM + - 10/100/1000 Ethernet + - HDMI 2.0 4K/60Hz display + - 40-pin GPIO header + - 2 x USB 2.0 Host, 1 x USB 2.0 Type-C OTG + - 16GB/32GB/64GB eMMC + - 2MB SPI Flash + - microSD + - SDIO Wifi Module, Bluetooth + - Two channels IR receiver + +U-Boot compilation +------------------ + +.. code-block:: bash + + $ export CROSS_COMPILE=aarch64-none-elf- + $ make khadas-vim2_defconfig + $ make + +Image creation +-------------- + +Amlogic doesn't provide sources for the firmware and for tools needed +to create the bootloader image, so it is necessary to obtain them from +the git tree published by the board vendor: + +.. code-block:: bash + + $ wget https://releases.linaro.org/archive/13.11/components/toolchain/binaries/gcc-linaro-aarch64-none-elf-4.8-2013.11_linux.tar.xz + $ wget https://releases.linaro.org/archive/13.11/components/toolchain/binaries/gcc-linaro-arm-none-eabi-4.8-2013.11_linux.tar.xz + $ tar xvfJ gcc-linaro-aarch64-none-elf-4.8-2013.11_linux.tar.xz + $ tar xvfJ gcc-linaro-arm-none-eabi-4.8-2013.11_linux.tar.xz + $ export PATH=$PWD/gcc-linaro-aarch64-none-elf-4.8-2013.11_linux/bin:$PWD/gcc-linaro-arm-none-eabi-4.8-2013.11_linux/bin:$PATH + $ git clone https://github.com/khadas/u-boot -b khadas-vim-v2015.01 vim-u-boot + $ cd vim-u-boot + $ make kvim2_defconfig + $ make + $ export FIPDIR=$PWD/fip + +Go back to mainline U-Boot source tree then : + +.. code-block:: bash + + $ mkdir fip + + $ cp $FIPDIR/gxl/bl2.bin fip/ + $ cp $FIPDIR/gxl/acs.bin fip/ + $ cp $FIPDIR/gxl/bl21.bin fip/ + $ cp $FIPDIR/gxl/bl30.bin fip/ + $ cp $FIPDIR/gxl/bl301.bin fip/ + $ cp $FIPDIR/gxl/bl31.img fip/ + $ cp u-boot.bin fip/bl33.bin + + $ $FIPDIR/blx_fix.sh \ + fip/bl30.bin \ + fip/zero_tmp \ + fip/bl30_zero.bin \ + fip/bl301.bin \ + fip/bl301_zero.bin \ + fip/bl30_new.bin \ + bl30 + + $ python $FIPDIR/acs_tool.pyc fip/bl2.bin fip/bl2_acs.bin fip/acs.bin 0 + + $ $FIPDIR/blx_fix.sh \ + fip/bl2_acs.bin \ + fip/zero_tmp \ + fip/bl2_zero.bin \ + fip/bl21.bin \ + fip/bl21_zero.bin \ + fip/bl2_new.bin \ + bl2 + + $ $FIPDIR/gxl/aml_encrypt_gxl --bl3enc --input fip/bl30_new.bin + $ $FIPDIR/gxl/aml_encrypt_gxl --bl3enc --input fip/bl31.img + $ $FIPDIR/gxl/aml_encrypt_gxl --bl3enc --input fip/bl33.bin + $ $FIPDIR/gxl/aml_encrypt_gxl --bl2sig --input fip/bl2_new.bin --output fip/bl2.n.bin.sig + $ $FIPDIR/gxl/aml_encrypt_gxl --bootmk \ + --output fip/u-boot.bin \ + --bl2 fip/bl2.n.bin.sig \ + --bl30 fip/bl30_new.bin.enc \ + --bl31 fip/bl31.img.enc \ + --bl33 fip/bl33.bin.enc + +and then write the image to SD with: + +.. code-block:: bash + + $ DEV=/dev/your_sd_device + $ dd if=fip/u-boot.bin.sd.bin of=$DEV conv=fsync,notrunc bs=512 skip=1 seek=1 + $ dd if=fip/u-boot.bin.sd.bin of=$DEV conv=fsync,notrunc bs=1 count=444 diff --git a/roms/u-boot/doc/board/amlogic/khadas-vim3.rst b/roms/u-boot/doc/board/amlogic/khadas-vim3.rst new file mode 100644 index 000000000..8b7196d98 --- /dev/null +++ b/roms/u-boot/doc/board/amlogic/khadas-vim3.rst @@ -0,0 +1,160 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +U-Boot for Khadas VIM3 +====================== + +Khadas VIM3 is a single board computer manufactured by Shenzhen Wesion +Technology Co., Ltd. with the following specifications: + + - Amlogic A311D Arm Cortex-A53 dual-core + Cortex-A73 quad-core SoC + - 4GB LPDDR4 SDRAM + - Gigabit Ethernet + - HDMI 2.1 display + - 40-pin GPIO header + - 1 x USB 3.0 Host, 1 x USB 2.0 Host + - eMMC, microSD + - M.2 + - Infrared receiver + +Schematics are available on the manufacturer website. + +PCIe Setup +---------- +The VIM3 on-board MCU can mux the PCIe/USB3.0 shared differential +lines using a FUSB340TMX USB 3.1 SuperSpeed Data Switch between +an USB3.0 Type A connector and a M.2 Key M slot. +The PHY driving these differential lines is shared between +the USB3.0 controller and the PCIe Controller, thus only +a single controller can use it. + +To setup for PCIe, run the following commands from U-Boot: + +.. code-block:: none + + i2c dev i2c@5000 + i2c mw 0x18 0x33 1 + +Then power-cycle the board. + +To set back to USB3.0, run the following commands from U-Boot: + +.. code-block:: none + + i2c dev i2c@5000 + i2c mw 0x18 0x33 0 + +Then power-cycle the board. + +U-Boot compilation +------------------ + +.. code-block:: bash + + $ export CROSS_COMPILE=aarch64-none-elf- + $ make khadas-vim3_defconfig + $ make + +Image creation +-------------- + +Amlogic doesn't provide sources for the firmware and for tools needed +to create the bootloader image, so it is necessary to obtain them from +the git tree published by the board vendor: + +.. code-block:: bash + + $ wget https://releases.linaro.org/archive/13.11/components/toolchain/binaries/gcc-linaro-aarch64-none-elf-4.8-2013.11_linux.tar.xz + $ wget https://releases.linaro.org/archive/13.11/components/toolchain/binaries/gcc-linaro-arm-none-eabi-4.8-2013.11_linux.tar.xz + $ tar xvfJ gcc-linaro-aarch64-none-elf-4.8-2013.11_linux.tar.xz + $ tar xvfJ gcc-linaro-arm-none-eabi-4.8-2013.11_linux.tar.xz + $ export PATH=$PWD/gcc-linaro-aarch64-none-elf-4.8-2013.11_linux/bin:$PWD/gcc-linaro-arm-none-eabi-4.8-2013.11_linux/bin:$PATH + + $ DIR=vim3-u-boot + $ git clone --depth 1 \ + https://github.com/khadas/u-boot.git -b khadas-vims-v2015.01 \ + $DIR + + $ cd vim3-u-boot + $ make kvim3_defconfig + $ make CROSS_COMPILE=aarch64-none-elf- + $ export UBOOTDIR=$PWD + +Go back to mainline U-Boot source tree then : + +.. code-block:: bash + + $ mkdir fip + + $ wget https://github.com/BayLibre/u-boot/releases/download/v2017.11-libretech-cc/blx_fix_g12a.sh -O fip/blx_fix.sh + $ cp $UBOOTDIR/build/scp_task/bl301.bin fip/ + $ cp $UBOOTDIR/build/board/khadas/kvim3/firmware/acs.bin fip/ + $ cp $UBOOTDIR/fip/g12b/bl2.bin fip/ + $ cp $UBOOTDIR/fip/g12b/bl30.bin fip/ + $ cp $UBOOTDIR/fip/g12b/bl31.img fip/ + $ cp $UBOOTDIR/fip/g12b/ddr3_1d.fw fip/ + $ cp $UBOOTDIR/fip/g12b/ddr4_1d.fw fip/ + $ cp $UBOOTDIR/fip/g12b/ddr4_2d.fw fip/ + $ cp $UBOOTDIR/fip/g12b/diag_lpddr4.fw fip/ + $ cp $UBOOTDIR/fip/g12b/lpddr3_1d.fw fip/ + $ cp $UBOOTDIR/fip/g12b/lpddr4_1d.fw fip/ + $ cp $UBOOTDIR/fip/g12b/lpddr4_2d.fw fip/ + $ cp $UBOOTDIR/fip/g12b/piei.fw fip/ + $ cp $UBOOTDIR/fip/g12b/aml_ddr.fw fip/ + $ cp u-boot.bin fip/bl33.bin + + $ bash fip/blx_fix.sh \ + fip/bl30.bin \ + fip/zero_tmp \ + fip/bl30_zero.bin \ + fip/bl301.bin \ + fip/bl301_zero.bin \ + fip/bl30_new.bin \ + bl30 + + $ bash fip/blx_fix.sh \ + fip/bl2.bin \ + fip/zero_tmp \ + fip/bl2_zero.bin \ + fip/acs.bin \ + fip/bl21_zero.bin \ + fip/bl2_new.bin \ + bl2 + + $ $UBOOTDIR/fip/g12b/aml_encrypt_g12b --bl30sig --input fip/bl30_new.bin \ + --output fip/bl30_new.bin.g12a.enc \ + --level v3 + $ $UBOOTDIR/fip/g12b/aml_encrypt_g12b --bl3sig --input fip/bl30_new.bin.g12a.enc \ + --output fip/bl30_new.bin.enc \ + --level v3 --type bl30 + $ $UBOOTDIR/fip/g12b/aml_encrypt_g12b --bl3sig --input fip/bl31.img \ + --output fip/bl31.img.enc \ + --level v3 --type bl31 + $ $UBOOTDIR/fip/g12b/aml_encrypt_g12b --bl3sig --input fip/bl33.bin --compress lz4 \ + --output fip/bl33.bin.enc \ + --level v3 --type bl33 --compress lz4 + $ $UBOOTDIR/fip/g12b/aml_encrypt_g12b --bl2sig --input fip/bl2_new.bin \ + --output fip/bl2.n.bin.sig + $ $UBOOTDIR/fip/g12b/aml_encrypt_g12b --bootmk \ + --output fip/u-boot.bin \ + --bl2 fip/bl2.n.bin.sig \ + --bl30 fip/bl30_new.bin.enc \ + --bl31 fip/bl31.img.enc \ + --bl33 fip/bl33.bin.enc \ + --ddrfw1 fip/ddr4_1d.fw \ + --ddrfw2 fip/ddr4_2d.fw \ + --ddrfw3 fip/ddr3_1d.fw \ + --ddrfw4 fip/piei.fw \ + --ddrfw5 fip/lpddr4_1d.fw \ + --ddrfw6 fip/lpddr4_2d.fw \ + --ddrfw7 fip/diag_lpddr4.fw \ + --ddrfw8 fip/aml_ddr.fw \ + --ddrfw9 fip/lpddr3_1d.fw \ + --level v3 + +and then write the image to SD with: + +.. code-block:: bash + + $ DEV=/dev/your_sd_device + $ dd if=fip/u-boot.bin.sd.bin of=$DEV conv=fsync,notrunc bs=512 skip=1 seek=1 + $ dd if=fip/u-boot.bin.sd.bin of=$DEV conv=fsync,notrunc bs=1 count=444 diff --git a/roms/u-boot/doc/board/amlogic/khadas-vim3l.rst b/roms/u-boot/doc/board/amlogic/khadas-vim3l.rst new file mode 100644 index 000000000..aed895539 --- /dev/null +++ b/roms/u-boot/doc/board/amlogic/khadas-vim3l.rst @@ -0,0 +1,160 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +U-Boot for Khadas VIM3L +======================= + +Khadas VIM3L is a single board computer manufactured by Shenzhen Wesion +Technology Co., Ltd. with the following specifications: + + - Amlogic S905D3 Arm Cortex-A55 quad-core SoC + - 2GB LPDDR4 SDRAM + - Gigabit Ethernet + - HDMI 2.1 display + - 40-pin GPIO header + - 1 x USB 3.0 Host, 1 x USB 2.0 Host + - eMMC, microSD + - M.2 + - Infrared receiver + +Schematics are available on the manufacturer website. + +PCIe Setup +---------- +The VIM3 on-board MCU can mux the PCIe/USB3.0 shared differential +lines using a FUSB340TMX USB 3.1 SuperSpeed Data Switch between +an USB3.0 Type A connector and a M.2 Key M slot. +The PHY driving these differential lines is shared between +the USB3.0 controller and the PCIe Controller, thus only +a single controller can use it. + +To setup for PCIe, run the following commands from U-Boot: + +.. code-block:: none + + i2c dev i2c@5000 + i2c mw 0x18 0x33 1 + +Then power-cycle the board. + +To set back to USB3.0, run the following commands from U-Boot: + +.. code-block:: none + + i2c dev i2c@5000 + i2c mw 0x18 0x33 0 + +Then power-cycle the board. + +U-Boot compilation +------------------ + +.. code-block:: bash + + $ export CROSS_COMPILE=aarch64-none-elf- + $ make khadas-vim3l_defconfig + $ make + +Image creation +-------------- + +Amlogic doesn't provide sources for the firmware and for tools needed +to create the bootloader image, so it is necessary to obtain them from +the git tree published by the board vendor: + +.. code-block:: bash + + $ wget https://releases.linaro.org/archive/13.11/components/toolchain/binaries/gcc-linaro-aarch64-none-elf-4.8-2013.11_linux.tar.xz + $ wget https://releases.linaro.org/archive/13.11/components/toolchain/binaries/gcc-linaro-arm-none-eabi-4.8-2013.11_linux.tar.xz + $ tar xvfJ gcc-linaro-aarch64-none-elf-4.8-2013.11_linux.tar.xz + $ tar xvfJ gcc-linaro-arm-none-eabi-4.8-2013.11_linux.tar.xz + $ export PATH=$PWD/gcc-linaro-aarch64-none-elf-4.8-2013.11_linux/bin:$PWD/gcc-linaro-arm-none-eabi-4.8-2013.11_linux/bin:$PATH + + $ DIR=vim3l-u-boot + $ git clone --depth 1 \ + https://github.com/khadas/u-boot.git -b khadas-vims-v2015.01 \ + $DIR + + $ cd vim3l-u-boot + $ make kvim3l_defconfig + $ make CROSS_COMPILE=aarch64-none-elf- + $ export UBOOTDIR=$PWD + +Go back to mainline U-Boot source tree then : + +.. code-block:: bash + + $ mkdir fip + + $ wget https://github.com/BayLibre/u-boot/releases/download/v2017.11-libretech-cc/blx_fix_g12a.sh -O fip/blx_fix.sh + $ cp $UBOOTDIR/build/scp_task/bl301.bin fip/ + $ cp $UBOOTDIR/build/board/khadas/kvim3l/firmware/acs.bin fip/ + $ cp $UBOOTDIR/fip/g12a/bl2.bin fip/ + $ cp $UBOOTDIR/fip/g12a/bl30.bin fip/ + $ cp $UBOOTDIR/fip/g12a/bl31.img fip/ + $ cp $UBOOTDIR/fip/g12a/ddr3_1d.fw fip/ + $ cp $UBOOTDIR/fip/g12a/ddr4_1d.fw fip/ + $ cp $UBOOTDIR/fip/g12a/ddr4_2d.fw fip/ + $ cp $UBOOTDIR/fip/g12a/diag_lpddr4.fw fip/ + $ cp $UBOOTDIR/fip/g12a/lpddr3_1d.fw fip/ + $ cp $UBOOTDIR/fip/g12a/lpddr4_1d.fw fip/ + $ cp $UBOOTDIR/fip/g12a/lpddr4_2d.fw fip/ + $ cp $UBOOTDIR/fip/g12a/piei.fw fip/ + $ cp $UBOOTDIR/fip/g12a/aml_ddr.fw fip/ + $ cp u-boot.bin fip/bl33.bin + + $ bash fip/blx_fix.sh \ + fip/bl30.bin \ + fip/zero_tmp \ + fip/bl30_zero.bin \ + fip/bl301.bin \ + fip/bl301_zero.bin \ + fip/bl30_new.bin \ + bl30 + + $ bash fip/blx_fix.sh \ + fip/bl2.bin \ + fip/zero_tmp \ + fip/bl2_zero.bin \ + fip/acs.bin \ + fip/bl21_zero.bin \ + fip/bl2_new.bin \ + bl2 + + $ $UBOOTDIR/fip/g12a/aml_encrypt_g12a --bl30sig --input fip/bl30_new.bin \ + --output fip/bl30_new.bin.g12a.enc \ + --level v3 + $ $UBOOTDIR/fip/g12a/aml_encrypt_g12a --bl3sig --input fip/bl30_new.bin.g12a.enc \ + --output fip/bl30_new.bin.enc \ + --level v3 --type bl30 + $ $UBOOTDIR/fip/g12a/aml_encrypt_g12a --bl3sig --input fip/bl31.img \ + --output fip/bl31.img.enc \ + --level v3 --type bl31 + $ $UBOOTDIR/fip/g12a/aml_encrypt_g12a --bl3sig --input fip/bl33.bin --compress lz4 \ + --output fip/bl33.bin.enc \ + --level v3 --type bl33 --compress lz4 + $ $UBOOTDIR/fip/g12a/aml_encrypt_g12a --bl2sig --input fip/bl2_new.bin \ + --output fip/bl2.n.bin.sig + $ $UBOOTDIR/fip/g12a/aml_encrypt_g12a --bootmk \ + --output fip/u-boot.bin \ + --bl2 fip/bl2.n.bin.sig \ + --bl30 fip/bl30_new.bin.enc \ + --bl31 fip/bl31.img.enc \ + --bl33 fip/bl33.bin.enc \ + --ddrfw1 fip/ddr4_1d.fw \ + --ddrfw2 fip/ddr4_2d.fw \ + --ddrfw3 fip/ddr3_1d.fw \ + --ddrfw4 fip/piei.fw \ + --ddrfw5 fip/lpddr4_1d.fw \ + --ddrfw6 fip/lpddr4_2d.fw \ + --ddrfw7 fip/diag_lpddr4.fw \ + --ddrfw8 fip/aml_ddr.fw \ + --ddrfw9 fip/lpddr3_1d.fw \ + --level v3 + +and then write the image to SD with: + +.. code-block:: bash + + $ DEV=/dev/your_sd_device + $ dd if=fip/u-boot.bin.sd.bin of=$DEV conv=fsync,notrunc bs=512 skip=1 seek=1 + $ dd if=fip/u-boot.bin.sd.bin of=$DEV conv=fsync,notrunc bs=1 count=444 diff --git a/roms/u-boot/doc/board/amlogic/libretech-ac.rst b/roms/u-boot/doc/board/amlogic/libretech-ac.rst new file mode 100644 index 000000000..39bae86d3 --- /dev/null +++ b/roms/u-boot/doc/board/amlogic/libretech-ac.rst @@ -0,0 +1,110 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +U-Boot for LibreTech AC +======================= + +LibreTech AC is a single board computer manufactured by Libre Technology +with the following specifications: + + - Amlogic S805X ARM Cortex-A53 quad-core SoC @ 1.2GHz + - ARM Mali 450 GPU + - 512MiB DDR4 SDRAM + - 10/100 Ethernet + - HDMI 2.0 4K/60Hz display + - 40-pin GPIO header + - 4 x USB 2.0 Host + - eMMC, SPI NOR Flash + - Infrared receiver + +Schematics are available on the manufacturer website. + +U-Boot compilation +------------------ + +.. code-block:: bash + + $ export CROSS_COMPILE=aarch64-none-elf- + $ make libretech-ac_defconfig + $ make + +Image creation +-------------- + +Amlogic doesn't provide sources for the firmware and for tools needed +to create the bootloader image, so it is necessary to obtain them from +the git tree published by the board vendor: + +.. code-block:: bash + + $ wget https://releases.linaro.org/archive/13.11/components/toolchain/binaries/gcc-linaro-aarch64-none-elf-4.8-2013.11_linux.tar.xz + $ wget https://releases.linaro.org/archive/13.11/components/toolchain/binaries/gcc-linaro-arm-none-eabi-4.8-2013.11_linux.tar.xz + $ tar xvfJ gcc-linaro-aarch64-none-elf-4.8-2013.11_linux.tar.xz + $ tar xvfJ gcc-linaro-arm-none-eabi-4.8-2013.11_linux.tar.xz + $ export PATH=$PWD/gcc-linaro-aarch64-none-elf-4.8-2013.11_linux/bin:$PWD/gcc-linaro-arm-none-eabi-4.8-2013.11_linux/bin:$PATH + $ git clone https://github.com/BayLibre/u-boot.git -b libretech-ac amlogic-u-boot + $ cd amlogic-u-boot + $ wget https://raw.githubusercontent.com/BayLibre/u-boot/libretech-cc/fip/blx_fix.sh + $ make libretech_ac_defconfig + $ make + $ export UBOOTDIR=$PWD + +Download the latest Amlogic Buildroot package, and extract it : + +.. code-block:: bash + + $ wget http://openlinux2.amlogic.com:8000/ARM/filesystem/Linux_BSP/buildroot_openlinux_kernel_4.9_fbdev_20180418.tar.gz + $ tar xfz buildroot_openlinux_kernel_4.9_fbdev_20180418.tar.gz buildroot_openlinux_kernel_4.9_fbdev_20180418/bootloader + $ export BRDIR=$PWD/buildroot_openlinux_kernel_4.9_fbdev_20180418 + +Go back to mainline U-Boot source tree then : + +.. code-block:: bash + + $ mkdir fip + + $ cp $UBOOTDIR/build/scp_task/bl301.bin fip/ + $ cp $UBOOTDIR/build/board/amlogic/libretech_ac/firmware/bl21.bin fip/ + $ cp $UBOOTDIR/build/board/amlogic/libretech_ac/firmware/acs.bin fip/ + $ cp $BRDIR/bootloader/uboot-repo/bl2/bin/gxl/bl2.bin fip/ + $ cp $BRDIR/bootloader/uboot-repo/bl30/bin/gxl/bl30.bin fip/ + $ cp $BRDIR/bootloader/uboot-repo/bl31/bin/gxl/bl31.img fip/ + $ cp u-boot.bin fip/bl33.bin + + $ sh $UBOOTDIR/blx_fix.sh \ + fip/bl30.bin \ + fip/zero_tmp \ + fip/bl30_zero.bin \ + fip/bl301.bin \ + fip/bl301_zero.bin \ + fip/bl30_new.bin \ + bl30 + + $ $BRDIR/bootloader/uboot-repo/fip/acs_tool.pyc fip/bl2.bin fip/bl2_acs.bin fip/acs.bin 0 + + $ sh $UBOOTDIR/blx_fix.sh \ + fip/bl2_acs.bin \ + fip/zero_tmp \ + fip/bl2_zero.bin \ + fip/bl21.bin \ + fip/bl21_zero.bin \ + fip/bl2_new.bin \ + bl2 + + $ $BRDIR/bootloader/uboot-repo/fip/gxl/aml_encrypt_gxl --bl3enc --input fip/bl30_new.bin + $ $BRDIR/bootloader/uboot-repo/fip/gxl/aml_encrypt_gxl --bl3enc --input fip/bl31.img + $ $BRDIR/bootloader/uboot-repo/fip/gxl/aml_encrypt_gxl --bl3enc --input fip/bl33.bin + $ $BRDIR/bootloader/uboot-repo/fip/gxl/aml_encrypt_gxl --bl2sig --input fip/bl2_new.bin --output fip/bl2.n.bin.sig + $ $BRDIR/bootloader/uboot-repo/fip/gxl/aml_encrypt_gxl --bootmk \ + --output fip/u-boot.bin \ + --bl2 fip/bl2.n.bin.sig \ + --bl30 fip/bl30_new.bin.enc \ + --bl31 fip/bl31.img.enc \ + --bl33 fip/bl33.bin.enc + +and then write the image to SD with: + +.. code-block:: bash + + $ DEV=/dev/your_sd_device + $ dd if=fip/u-boot.bin.sd.bin of=$DEV conv=fsync,notrunc bs=512 skip=1 seek=1 + $ dd if=fip/u-boot.bin.sd.bin of=$DEV conv=fsync,notrunc bs=1 count=444 diff --git a/roms/u-boot/doc/board/amlogic/libretech-cc.rst b/roms/u-boot/doc/board/amlogic/libretech-cc.rst new file mode 100644 index 000000000..94c74c5a8 --- /dev/null +++ b/roms/u-boot/doc/board/amlogic/libretech-cc.rst @@ -0,0 +1,146 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +U-Boot for LibreTech CCs +======================== + +LibreTech CC is a single board computer manufactured by Libre Technology +with the following specifications: + +V1: + + - Amlogic S905X ARM Cortex-A53 quad-core SoC @ 1.5GHz + - ARM Mali 450 GPU + - 2GB DDR3 SDRAM + - 10/100 Ethernet + - HDMI 2.0 4K/60Hz display + - 40-pin GPIO header + - 4 x USB 2.0 Host + - eMMC, microSD + - Infrared receiver + - Jack for CVBS and Audio + +V2: + + - Added SPI NOR + - Removed Jack + +Schematics are available on the manufacturer website. + +U-Boot compilation +------------------ + +.. code-block:: bash + + $ export CROSS_COMPILE=aarch64-none-elf- + $ make libretech-cc_defconfig + $ make + +Use libretech-cc_v2_defconfig for v2. + +Image creation +-------------- + +To boot the system, u-boot must be combined with several earlier stage +bootloaders: + +* bl2.bin: vendor-provided binary blob +* bl21.bin: built from vendor u-boot source +* bl30.bin: vendor-provided binary blob +* bl301.bin: built from vendor u-boot source +* bl31.bin: vendor-provided binary blob +* acs.bin: built from vendor u-boot source + +These binaries and the tools required below have been collected and prebuilt +for convenience at <https://github.com/BayLibre/u-boot/releases/>. These +apply to both v1 and v2. + +Download and extract the libretech-cc release from there, and set FIPDIR to +point to the `fip` subdirectory. + +.. code-block:: bash + + $ export FIPDIR=/path/to/extracted/fip + +Alternatively, you can obtain the original vendor u-boot tree which +contains the required blobs and sources, and build yourself. +Note that old compilers are required for this to build. The compilers here +are suggested by Amlogic, and they are 32-bit x86 binaries. + +.. code-block:: bash + + $ wget https://releases.linaro.org/archive/13.11/components/toolchain/binaries/gcc-linaro-aarch64-none-elf-4.8-2013.11_linux.tar.xz + $ wget https://releases.linaro.org/archive/13.11/components/toolchain/binaries/gcc-linaro-arm-none-eabi-4.8-2013.11_linux.tar.xz + $ tar xvfJ gcc-linaro-aarch64-none-elf-4.8-2013.11_linux.tar.xz + $ tar xvfJ gcc-linaro-arm-none-eabi-4.8-2013.11_linux.tar.xz + $ export PATH=$PWD/gcc-linaro-aarch64-none-elf-4.8-2013.11_linux/bin:$PWD/gcc-linaro-arm-none-eabi-4.8-2013.11_linux/bin:$PATH + $ git clone https://github.com/BayLibre/u-boot.git -b libretech-cc amlogic-u-boot + $ cd amlogic-u-boot + $ make libretech_cc_defconfig + $ make + $ export FIPDIR=$PWD/fip + +Once you have the binaries available (either through the prebuilt download, +or having built the vendor u-boot yourself), you can then proceed to glue +everything together. Go back to mainline U-Boot source tree then : + +.. code-block:: bash + + $ mkdir fip + + $ cp $FIPDIR/gxl/bl2.bin fip/ + $ cp $FIPDIR/gxl/acs.bin fip/ + $ cp $FIPDIR/gxl/bl21.bin fip/ + $ cp $FIPDIR/gxl/bl30.bin fip/ + $ cp $FIPDIR/gxl/bl301.bin fip/ + $ cp $FIPDIR/gxl/bl31.img fip/ + $ cp u-boot.bin fip/bl33.bin + + $ $FIPDIR/blx_fix.sh \ + fip/bl30.bin \ + fip/zero_tmp \ + fip/bl30_zero.bin \ + fip/bl301.bin \ + fip/bl301_zero.bin \ + fip/bl30_new.bin \ + bl30 + + $ $FIPDIR/acs_tool.pyc fip/bl2.bin fip/bl2_acs.bin fip/acs.bin 0 + + $ $FIPDIR/blx_fix.sh \ + fip/bl2_acs.bin \ + fip/zero_tmp \ + fip/bl2_zero.bin \ + fip/bl21.bin \ + fip/bl21_zero.bin \ + fip/bl2_new.bin \ + bl2 + + $ $FIPDIR/gxl/aml_encrypt_gxl --bl3enc --input fip/bl30_new.bin + $ $FIPDIR/gxl/aml_encrypt_gxl --bl3enc --input fip/bl31.img + $ $FIPDIR/gxl/aml_encrypt_gxl --bl3enc --input fip/bl33.bin + $ $FIPDIR/gxl/aml_encrypt_gxl --bl2sig --input fip/bl2_new.bin --output fip/bl2.n.bin.sig + $ $FIPDIR/gxl/aml_encrypt_gxl --bootmk \ + --output fip/u-boot.bin \ + --bl2 fip/bl2.n.bin.sig \ + --bl30 fip/bl30_new.bin.enc \ + --bl31 fip/bl31.img.enc \ + --bl33 fip/bl33.bin.enc + +and then write the image to SD with: + +.. code-block:: bash + + $ DEV=/dev/your_sd_device + $ dd if=fip/u-boot.bin.sd.bin of=$DEV conv=fsync,notrunc bs=512 skip=1 seek=1 + $ dd if=fip/u-boot.bin.sd.bin of=$DEV conv=fsync,notrunc bs=1 count=444 + +Note that Amlogic provides aml_encrypt_gxl as a 32-bit x86 binary with no +source code. Should you prefer to avoid that, there are open source reverse +engineered versions available: + +1. gxlimg <https://github.com/repk/gxlimg>, which comes with a handy + Makefile that automates the whole process. +2. meson-tools <https://github.com/afaerber/meson-tools> + +However, these community-developed alternatives are not endorsed by or +supported by Amlogic. diff --git a/roms/u-boot/doc/board/amlogic/nanopi-k2.rst b/roms/u-boot/doc/board/amlogic/nanopi-k2.rst new file mode 100644 index 000000000..1222ee4e8 --- /dev/null +++ b/roms/u-boot/doc/board/amlogic/nanopi-k2.rst @@ -0,0 +1,104 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +U-Boot for NanoPi-K2 +==================== + +NanoPi-K2 is a single board computer manufactured by FriendlyElec +with the following specifications: + + - Amlogic S905 ARM Cortex-A53 quad-core SoC @ 1.5GHz + - ARM Mali 450 GPU + - 2GB DDR3 SDRAM + - Gigabit Ethernet + - HDMI 2.0 4K/60Hz display + - 40-pin GPIO header + - 4 x USB 2.0 Host, 1 x USB OTG + - eMMC, microSD + - Infrared receiver + +Schematics are available on the manufacturer website. + +U-Boot compilation +------------------ + +.. code-block:: bash + + $ export CROSS_COMPILE=aarch64-none-elf- + $ make nanopi-k2_defconfig + $ make + +Image creation +-------------- + +Amlogic doesn't provide sources for the firmware and for tools needed +to create the bootloader image, so it is necessary to obtain them from +the git tree published by the board vendor: + +.. code-block:: bash + + $ wget https://releases.linaro.org/archive/13.11/components/toolchain/binaries/gcc-linaro-aarch64-none-elf-4.8-2013.11_linux.tar.xz + $ wget https://releases.linaro.org/archive/13.11/components/toolchain/binaries/gcc-linaro-arm-none-eabi-4.8-2013.11_linux.tar.xz + $ tar xvfJ gcc-linaro-aarch64-none-elf-4.8-2013.11_linux.tar.xz + $ tar xvfJ gcc-linaro-arm-none-eabi-4.8-2013.11_linux.tar.xz + $ export PATH=$PWD/gcc-linaro-aarch64-none-elf-4.8-2013.11_linux/bin:$PWD/gcc-linaro-arm-none-eabi-4.8-2013.11_linux/bin:$PATH + $ git clone https://github.com/BayLibre/u-boot.git -b libretech-cc amlogic-u-boot + $ git clone https://github.com/friendlyarm/u-boot.git -b nanopi-k2-v2015.01 amlogic-u-boot + $ cd amlogic-u-boot + $ sed -i 's/aarch64-linux-gnu-/aarch64-none-elf-/' Makefile + $ sed -i 's/arm-linux-/arm-none-eabi-/' arch/arm/cpu/armv8/gxb/firmware/scp_task/Makefile + $ make nanopi-k2_defconfig + $ make + $ export FIPDIR=$PWD/fip + +Go back to mainline U-Boot source tree then : + +.. code-block:: bash + + $ mkdir fip + + $ cp $FIPDIR/gxb/bl2.bin fip/ + $ cp $FIPDIR/gxb/acs.bin fip/ + $ cp $FIPDIR/gxb/bl21.bin fip/ + $ cp $FIPDIR/gxb/bl30.bin fip/ + $ cp $FIPDIR/gxb/bl301.bin fip/ + $ cp $FIPDIR/gxb/bl31.img fip/ + $ cp u-boot.bin fip/bl33.bin + + $ $FIPDIR/blx_fix.sh \ + fip/bl30.bin \ + fip/zero_tmp \ + fip/bl30_zero.bin \ + fip/bl301.bin \ + fip/bl301_zero.bin \ + fip/bl30_new.bin \ + bl30 + + $ $FIPDIR/fip_create \ + --bl30 fip/bl30_new.bin \ + --bl31 fip/bl31.img \ + --bl33 fip/bl33.bin \ + fip/fip.bin + + $ python $FIPDIR/acs_tool.pyc fip/bl2.bin fip/bl2_acs.bin fip/acs.bin 0 + + $ $FIPDIR/blx_fix.sh \ + fip/bl2_acs.bin \ + fip/zero_tmp \ + fip/bl2_zero.bin \ + fip/bl21.bin \ + fip/bl21_zero.bin \ + fip/bl2_new.bin \ + bl2 + + $ cat fip/bl2_new.bin fip/fip.bin > fip/boot_new.bin + + $ $FIPDIR/gxb/aml_encrypt_gxb --bootsig \ + --input fip/boot_new.bin + --output fip/u-boot.bin + +and then write the image to SD with: + +.. code-block:: bash + + $ DEV=/dev/your_sd_device + $ dd if=fip/u-boot.bin of=$DEV conv=fsync,notrunc bs=512 seek=1 diff --git a/roms/u-boot/doc/board/amlogic/odroid-c2.rst b/roms/u-boot/doc/board/amlogic/odroid-c2.rst new file mode 100644 index 000000000..966c18b36 --- /dev/null +++ b/roms/u-boot/doc/board/amlogic/odroid-c2.rst @@ -0,0 +1,63 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +U-Boot for ODROID-C2 +==================== + +ODROID-C2 is a single board computer manufactured by Hardkernel +Co. Ltd with the following specifications: + + - Amlogic S905 ARM Cortex-A53 quad-core SoC @ 2GHz + - ARM Mali 450 GPU + - 2GB DDR3 SDRAM + - Gigabit Ethernet + - HDMI 2.0 4K/60Hz display + - 40-pin GPIO header + - 4 x USB 2.0 Host, 1 x USB OTG + - eMMC, microSD + - Infrared receiver + +Schematics are available on the manufacturer website. + +U-Boot compilation +------------------ + +.. code-block:: bash + + $ export CROSS_COMPILE=aarch64-none-elf- + $ make odroid-c2_defconfig + $ make + +Image creation +-------------- + +Amlogic doesn't provide sources for the firmware and for tools needed +to create the bootloader image, so it is necessary to obtain them from +the git tree published by the board vendor: + +.. code-block:: bash + + $ DIR=odroid-c2 + $ git clone --depth 1 \ + https://github.com/hardkernel/u-boot.git -b odroidc2-v2015.01 \ + $DIR + $ $DIR/fip/fip_create --bl30 $DIR/fip/gxb/bl30.bin \ + --bl301 $DIR/fip/gxb/bl301.bin \ + --bl31 $DIR/fip/gxb/bl31.bin \ + --bl33 u-boot.bin \ + $DIR/fip.bin + $ $DIR/fip/fip_create --dump $DIR/fip.bin + $ cat $DIR/fip/gxb/bl2.package $DIR/fip.bin > $DIR/boot_new.bin + $ $DIR/fip/gxb/aml_encrypt_gxb --bootsig \ + --input $DIR/boot_new.bin \ + --output $DIR/u-boot.img + $ dd if=$DIR/u-boot.img of=$DIR/u-boot.gxbb bs=512 skip=96 + +and then write the image to SD with: + +.. code-block:: bash + + $ DEV=/dev/your_sd_device + $ BL1=$DIR/sd_fuse/bl1.bin.hardkernel + $ dd if=$BL1 of=$DEV conv=fsync bs=1 count=442 + $ dd if=$BL1 of=$DEV conv=fsync bs=512 skip=1 seek=1 + $ dd if=$DIR/u-boot.gxbb of=$DEV conv=fsync bs=512 seek=97 diff --git a/roms/u-boot/doc/board/amlogic/odroid-c4.rst b/roms/u-boot/doc/board/amlogic/odroid-c4.rst new file mode 100644 index 000000000..5a5a8688b --- /dev/null +++ b/roms/u-boot/doc/board/amlogic/odroid-c4.rst @@ -0,0 +1,134 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +U-Boot for ODROID-C4 +==================== + +ODROID-C4 is a single board computer manufactured by Hardkernel +Co. Ltd with the following specifications: + + - Amlogic S905X3 Arm Cortex-A55 quad-core SoC + - 4GB DDR4 SDRAM + - Gigabit Ethernet + - HDMI 2.1 display + - 40-pin GPIO header + - 4x USB 3.0 Host + - 1x USB 2.0 Host/OTG (micro) + - eMMC, microSD + - UART serial + - Infrared receiver + +Schematics are available on the manufacturer website. + +U-Boot compilation +------------------ + +.. code-block:: bash + + $ export CROSS_COMPILE=aarch64-none-elf- + $ make odroid-c4_defconfig + $ make + +Image creation +-------------- + +Amlogic doesn't provide sources for the firmware and for tools needed +to create the bootloader image, so it is necessary to obtain them from +the git tree published by the board vendor: + +.. code-block:: bash + + $ wget https://releases.linaro.org/archive/13.11/components/toolchain/binaries/gcc-linaro-aarch64-none-elf-4.8-2013.11_linux.tar.xz + $ wget https://releases.linaro.org/archive/13.11/components/toolchain/binaries/gcc-linaro-arm-none-eabi-4.8-2013.11_linux.tar.xz + $ tar xvfJ gcc-linaro-aarch64-none-elf-4.8-2013.11_linux.tar.xz + $ tar xvfJ gcc-linaro-arm-none-eabi-4.8-2013.11_linux.tar.xz + $ export PATH=$PWD/gcc-linaro-aarch64-none-elf-4.8-2013.11_linux/bin:$PWD/gcc-linaro-arm-none-eabi-4.8-2013.11_linux/bin:$PATH + + $ DIR=odroid-c4 + $ git clone --depth 1 \ + https://github.com/hardkernel/u-boot.git -b odroidg12-v2015.01 \ + $DIR + + $ cd odroid-c4 + $ make odroidc4_defconfig + $ make + $ export UBOOTDIR=$PWD + +Go back to mainline U-Boot source tree then : + +.. code-block:: bash + + $ mkdir fip + + $ wget https://github.com/BayLibre/u-boot/releases/download/v2017.11-libretech-cc/blx_fix_g12a.sh -O fip/blx_fix.sh + $ cp $UBOOTDIR/build/scp_task/bl301.bin fip/ + $ cp $UBOOTDIR/build/board/hardkernel/odroidc4/firmware/acs.bin fip/ + $ cp $UBOOTDIR/fip/g12a/bl2.bin fip/ + $ cp $UBOOTDIR/fip/g12a/bl30.bin fip/ + $ cp $UBOOTDIR/fip/g12a/bl31.img fip/ + $ cp $UBOOTDIR/fip/g12a/ddr3_1d.fw fip/ + $ cp $UBOOTDIR/fip/g12a/ddr4_1d.fw fip/ + $ cp $UBOOTDIR/fip/g12a/ddr4_2d.fw fip/ + $ cp $UBOOTDIR/fip/g12a/diag_lpddr4.fw fip/ + $ cp $UBOOTDIR/fip/g12a/lpddr3_1d.fw fip/ + $ cp $UBOOTDIR/fip/g12a/lpddr4_1d.fw fip/ + $ cp $UBOOTDIR/fip/g12a/lpddr4_2d.fw fip/ + $ cp $UBOOTDIR/fip/g12a/piei.fw fip/ + $ cp $UBOOTDIR/fip/g12a/aml_ddr.fw fip/ + $ cp u-boot.bin fip/bl33.bin + + $ sh fip/blx_fix.sh \ + fip/bl30.bin \ + fip/zero_tmp \ + fip/bl30_zero.bin \ + fip/bl301.bin \ + fip/bl301_zero.bin \ + fip/bl30_new.bin \ + bl30 + + $ sh fip/blx_fix.sh \ + fip/bl2.bin \ + fip/zero_tmp \ + fip/bl2_zero.bin \ + fip/acs.bin \ + fip/bl21_zero.bin \ + fip/bl2_new.bin \ + bl2 + + $ $UBOOTDIR/fip/g12a/aml_encrypt_g12a --bl30sig --input fip/bl30_new.bin \ + --output fip/bl30_new.bin.g12a.enc \ + --level v3 + $ $UBOOTDIR/fip/g12a/aml_encrypt_g12a --bl3sig --input fip/bl30_new.bin.g12a.enc \ + --output fip/bl30_new.bin.enc \ + --level v3 --type bl30 + $ $UBOOTDIR/fip/g12a/aml_encrypt_g12a --bl3sig --input fip/bl31.img \ + --output fip/bl31.img.enc \ + --level v3 --type bl31 + $ $UBOOTDIR/fip/g12a/aml_encrypt_g12a --bl3sig --input fip/bl33.bin --compress lz4 \ + --output fip/bl33.bin.enc \ + --level v3 --type bl33 --compress lz4 + $ $UBOOTDIR/fip/g12a/aml_encrypt_g12a --bl2sig --input fip/bl2_new.bin \ + --output fip/bl2.n.bin.sig + $ $UBOOTDIR/fip/g12a/aml_encrypt_g12a --bootmk \ + --output fip/u-boot.bin \ + --bl2 fip/bl2.n.bin.sig \ + --bl30 fip/bl30_new.bin.enc \ + --bl31 fip/bl31.img.enc \ + --bl33 fip/bl33.bin.enc \ + --ddrfw1 fip/ddr4_1d.fw \ + --ddrfw2 fip/ddr4_2d.fw \ + --ddrfw3 fip/ddr3_1d.fw \ + --ddrfw4 fip/piei.fw \ + --ddrfw5 fip/lpddr4_1d.fw \ + --ddrfw6 fip/lpddr4_2d.fw \ + --ddrfw7 fip/diag_lpddr4.fw \ + --ddrfw8 fip/aml_ddr.fw \ + --ddrfw9 fip/lpddr3_1d.fw \ + --level v3 + +and then write the image to SD with: + +.. code-block:: bash + + $ DEV=/dev/your_sd_device + $ dd if=fip/u-boot.bin.sd.bin of=$DEV conv=fsync,notrunc bs=512 skip=1 seek=1 + $ dd if=fip/u-boot.bin.sd.bin of=$DEV conv=fsync,notrunc bs=1 count=444 diff --git a/roms/u-boot/doc/board/amlogic/odroid-n2.rst b/roms/u-boot/doc/board/amlogic/odroid-n2.rst new file mode 100644 index 000000000..fe6311323 --- /dev/null +++ b/roms/u-boot/doc/board/amlogic/odroid-n2.rst @@ -0,0 +1,130 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +U-Boot for ODROID-N2 +==================== + +ODROID-N2 is a single board computer manufactured by Hardkernel +Co. Ltd with the following specifications: + + - Amlogic S922X ARM Cortex-A53 dual-core + Cortex-A73 quad-core SoC + - 4GB DDR4 SDRAM + - Gigabit Ethernet + - HDMI 2.1 4K/60Hz display + - 40-pin GPIO header + - 4 x USB 3.0 Host, 1 x USB OTG + - eMMC, microSD + - Infrared receiver + +Schematics are available on the manufacturer website. + +U-Boot compilation +------------------ + +.. code-block:: bash + + $ export CROSS_COMPILE=aarch64-none-elf- + $ make odroid-n2_defconfig + $ make + +Image creation +-------------- + +Amlogic doesn't provide sources for the firmware and for tools needed +to create the bootloader image, so it is necessary to obtain them from +the git tree published by the board vendor: + +.. code-block:: bash + + $ wget https://releases.linaro.org/archive/13.11/components/toolchain/binaries/gcc-linaro-aarch64-none-elf-4.8-2013.11_linux.tar.xz + $ wget https://releases.linaro.org/archive/13.11/components/toolchain/binaries/gcc-linaro-arm-none-eabi-4.8-2013.11_linux.tar.xz + $ tar xvfJ gcc-linaro-aarch64-none-elf-4.8-2013.11_linux.tar.xz + $ tar xvfJ gcc-linaro-arm-none-eabi-4.8-2013.11_linux.tar.xz + $ export PATH=$PWD/gcc-linaro-aarch64-none-elf-4.8-2013.11_linux/bin:$PWD/gcc-linaro-arm-none-eabi-4.8-2013.11_linux/bin:$PATH + + $ DIR=odroid-n2 + $ git clone --depth 1 \ + https://github.com/hardkernel/u-boot.git -b odroidn2-v2015.01 \ + $DIR + + $ cd odroid-n2 + $ make odroidn2_defconfig + $ make + $ export UBOOTDIR=$PWD + + Go back to mainline U-Boot source tree then : + +.. code-block:: bash + + $ mkdir fip + + $ wget https://github.com/BayLibre/u-boot/releases/download/v2017.11-libretech-cc/blx_fix_g12a.sh -O fip/blx_fix.sh + $ cp $UBOOTDIR/build/scp_task/bl301.bin fip/ + $ cp $UBOOTDIR/build/board/hardkernel/odroidn2/firmware/acs.bin fip/ + $ cp $UBOOTDIR/fip/g12b/bl2.bin fip/ + $ cp $UBOOTDIR/fip/g12b/bl30.bin fip/ + $ cp $UBOOTDIR/fip/g12b/bl31.img fip/ + $ cp $UBOOTDIR/fip/g12b/ddr3_1d.fw fip/ + $ cp $UBOOTDIR/fip/g12b/ddr4_1d.fw fip/ + $ cp $UBOOTDIR/fip/g12b/ddr4_2d.fw fip/ + $ cp $UBOOTDIR/fip/g12b/diag_lpddr4.fw fip/ + $ cp $UBOOTDIR/fip/g12b/lpddr4_1d.fw fip/ + $ cp $UBOOTDIR/fip/g12b/lpddr4_2d.fw fip/ + $ cp $UBOOTDIR/fip/g12b/piei.fw fip/ + $ cp $UBOOTDIR/fip/g12b/aml_ddr.fw fip/ + $ cp u-boot.bin fip/bl33.bin + + $ sh fip/blx_fix.sh \ + fip/bl30.bin \ + fip/zero_tmp \ + fip/bl30_zero.bin \ + fip/bl301.bin \ + fip/bl301_zero.bin \ + fip/bl30_new.bin \ + bl30 + + $ sh fip/blx_fix.sh \ + fip/bl2.bin \ + fip/zero_tmp \ + fip/bl2_zero.bin \ + fip/acs.bin \ + fip/bl21_zero.bin \ + fip/bl2_new.bin \ + bl2 + + $ $UBOOTDIR/fip/g12b/aml_encrypt_g12b --bl30sig --input fip/bl30_new.bin \ + --output fip/bl30_new.bin.g12a.enc \ + --level v3 + $ $UBOOTDIR/fip/g12b/aml_encrypt_g12b --bl3sig --input fip/bl30_new.bin.g12a.enc \ + --output fip/bl30_new.bin.enc \ + --level v3 --type bl30 + $ $UBOOTDIR/fip/g12b/aml_encrypt_g12b --bl3sig --input fip/bl31.img \ + --output fip/bl31.img.enc \ + --level v3 --type bl31 + $ $UBOOTDIR/fip/g12b/aml_encrypt_g12b --bl3sig --input fip/bl33.bin --compress lz4 \ + --output fip/bl33.bin.enc \ + --level v3 --type bl33 --compress lz4 + $ $UBOOTDIR/fip/g12b/aml_encrypt_g12b --bl2sig --input fip/bl2_new.bin \ + --output fip/bl2.n.bin.sig + $ $UBOOTDIR/fip/g12b/aml_encrypt_g12b --bootmk \ + --output fip/u-boot.bin \ + --bl2 fip/bl2.n.bin.sig \ + --bl30 fip/bl30_new.bin.enc \ + --bl31 fip/bl31.img.enc \ + --bl33 fip/bl33.bin.enc \ + --ddrfw1 fip/ddr4_1d.fw \ + --ddrfw2 fip/ddr4_2d.fw \ + --ddrfw3 fip/ddr3_1d.fw \ + --ddrfw4 fip/piei.fw \ + --ddrfw5 fip/lpddr4_1d.fw \ + --ddrfw6 fip/lpddr4_2d.fw \ + --ddrfw7 fip/diag_lpddr4.fw \ + --ddrfw8 fip/aml_ddr.fw \ + --level v3 + +and then write the image to SD with: + +.. code-block:: bash + + $ DEV=/dev/your_sd_device + $ dd if=fip/u-boot.bin.sd.bin of=$DEV conv=fsync,notrunc bs=512 skip=1 seek=1 + $ dd if=fip/u-boot.bin.sd.bin of=$DEV conv=fsync,notrunc bs=1 count=444 diff --git a/roms/u-boot/doc/board/amlogic/p200.rst b/roms/u-boot/doc/board/amlogic/p200.rst new file mode 100644 index 000000000..c3d6441fd --- /dev/null +++ b/roms/u-boot/doc/board/amlogic/p200.rst @@ -0,0 +1,102 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +U-Boot for Amlogic P200 +======================= + +P200 is a reference board manufactured by Amlogic with the following +specifications: + + - Amlogic S905 ARM Cortex-A53 quad-core SoC @ 1.5GHz + - ARM Mali 450 GPU + - 2GB DDR3 SDRAM + - Gigabit Ethernet + - HDMI 2.0 4K/60Hz display + - 2 x USB 2.0 Host + - eMMC, microSD + - Infrared receiver + - SDIO WiFi Module + - CVBS+Stereo Audio Jack + +Schematics are available from Amlogic on demand. + +U-Boot compilation +------------------ + +.. code-block:: bash + + $ export CROSS_COMPILE=aarch64-none-elf- + $ make p200_defconfig + $ make + +Image creation +-------------- + +Amlogic doesn't provide sources for the firmware and for tools needed +to create the bootloader image, so it is necessary to obtain them from +the git tree published by the board vendor: + +.. code-block:: bash + + $ wget https://releases.linaro.org/archive/13.11/components/toolchain/binaries/gcc-linaro-aarch64-none-elf-4.8-2013.11_linux.tar.xz + $ wget https://releases.linaro.org/archive/13.11/components/toolchain/binaries/gcc-linaro-arm-none-eabi-4.8-2013.11_linux.tar.xz + $ tar xvfJ gcc-linaro-aarch64-none-elf-4.8-2013.11_linux.tar.xz + $ tar xvfJ gcc-linaro-arm-none-eabi-4.8-2013.11_linux.tar.xz + $ export PATH=$PWD/gcc-linaro-aarch64-none-elf-4.8-2013.11_linux/bin:$PWD/gcc-linaro-arm-none-eabi-4.8-2013.11_linux/bin:$PATH + $ git clone https://github.com/BayLibre/u-boot.git -b n-amlogic-openlinux-20170606 amlogic-u-boot + $ cd amlogic-u-boot + $ make gxb_p200_v1_defconfig + $ make + $ export FIPDIR=$PWD/fip + +Go back to mainline U-boot source tree then : + +.. code-block:: bash + + $ mkdir fip + + $ cp $FIPDIR/gxl/bl2.bin fip/ + $ cp $FIPDIR/gxl/acs.bin fip/ + $ cp $FIPDIR/gxl/bl21.bin fip/ + $ cp $FIPDIR/gxl/bl30.bin fip/ + $ cp $FIPDIR/gxl/bl301.bin fip/ + $ cp $FIPDIR/gxl/bl31.img fip/ + $ cp u-boot.bin fip/bl33.bin + + $ $FIPDIR/blx_fix.sh \ + fip/bl30.bin \ + fip/zero_tmp \ + fip/bl30_zero.bin \ + fip/bl301.bin \ + fip/bl301_zero.bin \ + fip/bl30_new.bin \ + bl30 + + $ $FIPDIR/acs_tool.pyc fip/bl2.bin fip/bl2_acs.bin fip/acs.bin 0 + + $ $FIPDIR/blx_fix.sh \ + fip/bl2_acs.bin \ + fip/zero_tmp \ + fip/bl2_zero.bin \ + fip/bl21.bin \ + fip/bl21_zero.bin \ + fip/bl2_new.bin \ + bl2 + + $ $FIPDIR/gxl/aml_encrypt_gxl --bl3enc --input fip/bl30_new.bin + $ $FIPDIR/gxl/aml_encrypt_gxl --bl3enc --input fip/bl31.img + $ $FIPDIR/gxl/aml_encrypt_gxl --bl3enc --input fip/bl33.bin + $ $FIPDIR/gxl/aml_encrypt_gxl --bl2sig --input fip/bl2_new.bin --output fip/bl2.n.bin.sig + $ $FIPDIR/gxl/aml_encrypt_gxl --bootmk \ + --output fip/u-boot.bin \ + --bl2 fip/bl2.n.bin.sig \ + --bl30 fip/bl30_new.bin.enc \ + --bl31 fip/bl31.img.enc \ + --bl33 fip/bl33.bin.enc + +and then write the image to SD with: + +.. code-block:: bash + + $ DEV=/dev/your_sd_device + $ dd if=fip/u-boot.bin.sd.bin of=$DEV conv=fsync,notrunc bs=512 skip=1 seek=1 + $ dd if=fip/u-boot.bin.sd.bin of=$DEV conv=fsync,notrunc bs=1 count=444 diff --git a/roms/u-boot/doc/board/amlogic/p201.rst b/roms/u-boot/doc/board/amlogic/p201.rst new file mode 100644 index 000000000..06da933a2 --- /dev/null +++ b/roms/u-boot/doc/board/amlogic/p201.rst @@ -0,0 +1,102 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +U-Boot for Amlogic P201 +======================= + +P201 is a reference board manufactured by Amlogic with the following +specifications: + + - Amlogic S905 ARM Cortex-A53 quad-core SoC @ 1.5GHz + - ARM Mali 450 GPU + - 2GB DDR3 SDRAM + - 10/100 Ethernet + - HDMI 2.0 4K/60Hz display + - 2 x USB 2.0 Host + - eMMC, microSD + - Infrared receiver + - SDIO WiFi Module + - CVBS+Stereo Audio Jack + +Schematics are available from Amlogic on demand. + +U-Boot compilation +------------------ + +.. code-block:: bash + + $ export CROSS_COMPILE=aarch64-none-elf- + $ make p201_defconfig + $ make + +Image creation +-------------- + +Amlogic doesn't provide sources for the firmware and for tools needed +to create the bootloader image, so it is necessary to obtain them from +the git tree published by the board vendor: + +.. code-block:: bash + + $ wget https://releases.linaro.org/archive/13.11/components/toolchain/binaries/gcc-linaro-aarch64-none-elf-4.8-2013.11_linux.tar.xz + $ wget https://releases.linaro.org/archive/13.11/components/toolchain/binaries/gcc-linaro-arm-none-eabi-4.8-2013.11_linux.tar.xz + $ tar xvfJ gcc-linaro-aarch64-none-elf-4.8-2013.11_linux.tar.xz + $ tar xvfJ gcc-linaro-arm-none-eabi-4.8-2013.11_linux.tar.xz + $ export PATH=$PWD/gcc-linaro-aarch64-none-elf-4.8-2013.11_linux/bin:$PWD/gcc-linaro-arm-none-eabi-4.8-2013.11_linux/bin:$PATH + $ git clone https://github.com/BayLibre/u-boot.git -b n-amlogic-openlinux-20170606 amlogic-u-boot + $ cd amlogic-u-boot + $ make gxb_p201_v1_defconfig + $ make + $ export FIPDIR=$PWD/fip + +Go back to mainline U-boot source tree then : + +.. code-block:: bash + + $ mkdir fip + + $ cp $FIPDIR/gxl/bl2.bin fip/ + $ cp $FIPDIR/gxl/acs.bin fip/ + $ cp $FIPDIR/gxl/bl21.bin fip/ + $ cp $FIPDIR/gxl/bl30.bin fip/ + $ cp $FIPDIR/gxl/bl301.bin fip/ + $ cp $FIPDIR/gxl/bl31.img fip/ + $ cp u-boot.bin fip/bl33.bin + + $ $FIPDIR/blx_fix.sh \ + fip/bl30.bin \ + fip/zero_tmp \ + fip/bl30_zero.bin \ + fip/bl301.bin \ + fip/bl301_zero.bin \ + fip/bl30_new.bin \ + bl30 + + $ $FIPDIR/acs_tool.pyc fip/bl2.bin fip/bl2_acs.bin fip/acs.bin 0 + + $ $FIPDIR/blx_fix.sh \ + fip/bl2_acs.bin \ + fip/zero_tmp \ + fip/bl2_zero.bin \ + fip/bl21.bin \ + fip/bl21_zero.bin \ + fip/bl2_new.bin \ + bl2 + + $ $FIPDIR/gxl/aml_encrypt_gxl --bl3enc --input fip/bl30_new.bin + $ $FIPDIR/gxl/aml_encrypt_gxl --bl3enc --input fip/bl31.img + $ $FIPDIR/gxl/aml_encrypt_gxl --bl3enc --input fip/bl33.bin + $ $FIPDIR/gxl/aml_encrypt_gxl --bl2sig --input fip/bl2_new.bin --output fip/bl2.n.bin.sig + $ $FIPDIR/gxl/aml_encrypt_gxl --bootmk \ + --output fip/u-boot.bin \ + --bl2 fip/bl2.n.bin.sig \ + --bl30 fip/bl30_new.bin.enc \ + --bl31 fip/bl31.img.enc \ + --bl33 fip/bl33.bin.enc + +and then write the image to SD with: + +.. code-block:: bash + + $ DEV=/dev/your_sd_device + $ dd if=fip/u-boot.bin.sd.bin of=$DEV conv=fsync,notrunc bs=512 skip=1 seek=1 + $ dd if=fip/u-boot.bin.sd.bin of=$DEV conv=fsync,notrunc bs=1 count=444 diff --git a/roms/u-boot/doc/board/amlogic/p212.rst b/roms/u-boot/doc/board/amlogic/p212.rst new file mode 100644 index 000000000..e2f3fe313 --- /dev/null +++ b/roms/u-boot/doc/board/amlogic/p212.rst @@ -0,0 +1,102 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +U-Boot for Amlogic P212 +======================= + +P212 is a reference board manufactured by Amlogic with the following +specifications: + + - Amlogic S905X ARM Cortex-A53 quad-core SoC @ 1.5GHz + - ARM Mali 450 GPU + - 2GB DDR3 SDRAM + - 10/100 Ethernet + - HDMI 2.0 4K/60Hz display + - 2 x USB 2.0 Host + - eMMC, microSD + - Infrared receiver + - SDIO WiFi Module + - CVBS+Stereo Audio Jack + +Schematics are available from Amlogic on demand. + +U-Boot compilation +------------------ + +.. code-block:: bash + + $ export CROSS_COMPILE=aarch64-none-elf- + $ make p212_defconfig + $ make + +Image creation +-------------- + +Amlogic doesn't provide sources for the firmware and for tools needed +to create the bootloader image, so it is necessary to obtain them from +the git tree published by the board vendor: + +.. code-block:: bash + + $ wget https://releases.linaro.org/archive/13.11/components/toolchain/binaries/gcc-linaro-aarch64-none-elf-4.8-2013.11_linux.tar.xz + $ wget https://releases.linaro.org/archive/13.11/components/toolchain/binaries/gcc-linaro-arm-none-eabi-4.8-2013.11_linux.tar.xz + $ tar xvfJ gcc-linaro-aarch64-none-elf-4.8-2013.11_linux.tar.xz + $ tar xvfJ gcc-linaro-arm-none-eabi-4.8-2013.11_linux.tar.xz + $ export PATH=$PWD/gcc-linaro-aarch64-none-elf-4.8-2013.11_linux/bin:$PWD/gcc-linaro-arm-none-eabi-4.8-2013.11_linux/bin:$PATH + $ git clone https://github.com/BayLibre/u-boot.git -b n-amlogic-openlinux-20170606 amlogic-u-boot + $ cd amlogic-u-boot + $ make gxl_p212_v1_defconfig + $ make + $ export FIPDIR=$PWD/fip + +Go back to mainline U-boot source tree then : + +.. code-block:: bash + + $ mkdir fip + + $ cp $FIPDIR/gxl/bl2.bin fip/ + $ cp $FIPDIR/gxl/acs.bin fip/ + $ cp $FIPDIR/gxl/bl21.bin fip/ + $ cp $FIPDIR/gxl/bl30.bin fip/ + $ cp $FIPDIR/gxl/bl301.bin fip/ + $ cp $FIPDIR/gxl/bl31.img fip/ + $ cp u-boot.bin fip/bl33.bin + + $ $FIPDIR/blx_fix.sh \ + fip/bl30.bin \ + fip/zero_tmp \ + fip/bl30_zero.bin \ + fip/bl301.bin \ + fip/bl301_zero.bin \ + fip/bl30_new.bin \ + bl30 + + $ $FIPDIR/acs_tool.pyc fip/bl2.bin fip/bl2_acs.bin fip/acs.bin 0 + + $ $FIPDIR/blx_fix.sh \ + fip/bl2_acs.bin \ + fip/zero_tmp \ + fip/bl2_zero.bin \ + fip/bl21.bin \ + fip/bl21_zero.bin \ + fip/bl2_new.bin \ + bl2 + + $ $FIPDIR/gxl/aml_encrypt_gxl --bl3enc --input fip/bl30_new.bin + $ $FIPDIR/gxl/aml_encrypt_gxl --bl3enc --input fip/bl31.img + $ $FIPDIR/gxl/aml_encrypt_gxl --bl3enc --input fip/bl33.bin + $ $FIPDIR/gxl/aml_encrypt_gxl --bl2sig --input fip/bl2_new.bin --output fip/bl2.n.bin.sig + $ $FIPDIR/gxl/aml_encrypt_gxl --bootmk \ + --output fip/u-boot.bin \ + --bl2 fip/bl2.n.bin.sig \ + --bl30 fip/bl30_new.bin.enc \ + --bl31 fip/bl31.img.enc \ + --bl33 fip/bl33.bin.enc + +and then write the image to SD with: + +.. code-block:: bash + + $ DEV=/dev/your_sd_device + $ dd if=fip/u-boot.bin.sd.bin of=$DEV conv=fsync,notrunc bs=512 skip=1 seek=1 + $ dd if=fip/u-boot.bin.sd.bin of=$DEV conv=fsync,notrunc bs=1 count=444 diff --git a/roms/u-boot/doc/board/amlogic/q200.rst b/roms/u-boot/doc/board/amlogic/q200.rst new file mode 100644 index 000000000..3ac4116be --- /dev/null +++ b/roms/u-boot/doc/board/amlogic/q200.rst @@ -0,0 +1,101 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +U-Boot for Amlogic Q200 +======================= + +Q200 is a reference board manufactured by Amlogic with the following +specifications: + + - Amlogic S912 ARM Cortex-A53 octo-core SoC @ 1.5GHz + - ARM Mali T860 GPU + - 2/3GB DDR4 SDRAM + - 10/100/1000 Ethernet + - HDMI 2.0 4K/60Hz display + - 2 x USB 2.0 Host, 1 x USB 2.0 Device + - 16GB/32GB/64GB eMMC + - 2MB SPI Flash + - microSD + - SDIO Wifi Module, Bluetooth + - IR receiver + +U-Boot compilation +------------------ + +.. code-block:: bash + + $ export CROSS_COMPILE=aarch64-none-elf- + $ make khadas-vim2_defconfig + $ make + +Image creation +-------------- + +Amlogic doesn't provide sources for the firmware and for tools needed +to create the bootloader image, so it is necessary to obtain them from +the git tree published by the board vendor: + +.. code-block:: bash + + $ wget https://releases.linaro.org/archive/13.11/components/toolchain/binaries/gcc-linaro-aarch64-none-elf-4.8-2013.11_linux.tar.xz + $ wget https://releases.linaro.org/archive/13.11/components/toolchain/binaries/gcc-linaro-arm-none-eabi-4.8-2013.11_linux.tar.xz + $ tar xvfJ gcc-linaro-aarch64-none-elf-4.8-2013.11_linux.tar.xz + $ tar xvfJ gcc-linaro-arm-none-eabi-4.8-2013.11_linux.tar.xz + $ export PATH=$PWD/gcc-linaro-aarch64-none-elf-4.8-2013.11_linux/bin:$PWD/gcc-linaro-arm-none-eabi-4.8-2013.11_linux/bin:$PATH + $ git clone https://github.com/BayLibre/u-boot.git -b n-amlogic-openlinux-20170606 amlogic-u-boot + $ cd amlogic-u-boot + $ make gxm_q200_v1_defconfig + $ make + $ export FIPDIR=$PWD/fip + +Go back to mainline U-Boot source tree then : + +.. code-block:: bash + + $ mkdir fip + + $ cp $FIPDIR/gxl/bl2.bin fip/ + $ cp $FIPDIR/gxl/acs.bin fip/ + $ cp $FIPDIR/gxl/bl21.bin fip/ + $ cp $FIPDIR/gxl/bl30.bin fip/ + $ cp $FIPDIR/gxl/bl301.bin fip/ + $ cp $FIPDIR/gxl/bl31.img fip/ + $ cp u-boot.bin fip/bl33.bin + + $ $FIPDIR/blx_fix.sh \ + fip/bl30.bin \ + fip/zero_tmp \ + fip/bl30_zero.bin \ + fip/bl301.bin \ + fip/bl301_zero.bin \ + fip/bl30_new.bin \ + bl30 + + $ python $FIPDIR/acs_tool.pyc fip/bl2.bin fip/bl2_acs.bin fip/acs.bin 0 + + $ $FIPDIR/blx_fix.sh \ + fip/bl2_acs.bin \ + fip/zero_tmp \ + fip/bl2_zero.bin \ + fip/bl21.bin \ + fip/bl21_zero.bin \ + fip/bl2_new.bin \ + bl2 + + $ $FIPDIR/gxl/aml_encrypt_gxl --bl3enc --input fip/bl30_new.bin + $ $FIPDIR/gxl/aml_encrypt_gxl --bl3enc --input fip/bl31.img + $ $FIPDIR/gxl/aml_encrypt_gxl --bl3enc --input fip/bl33.bin + $ $FIPDIR/gxl/aml_encrypt_gxl --bl2sig --input fip/bl2_new.bin --output fip/bl2.n.bin.sig + $ $FIPDIR/gxl/aml_encrypt_gxl --bootmk \ + --output fip/u-boot.bin \ + --bl2 fip/bl2.n.bin.sig \ + --bl30 fip/bl30_new.bin.enc \ + --bl31 fip/bl31.img.enc \ + --bl33 fip/bl33.bin.enc + +and then write the image to SD with: + +.. code-block:: bash + + $ DEV=/dev/your_sd_device + $ dd if=fip/u-boot.bin.sd.bin of=$DEV conv=fsync,notrunc bs=512 skip=1 seek=1 + $ dd if=fip/u-boot.bin.sd.bin of=$DEV conv=fsync,notrunc bs=1 count=444 diff --git a/roms/u-boot/doc/board/amlogic/s400.rst b/roms/u-boot/doc/board/amlogic/s400.rst new file mode 100644 index 000000000..52c7b2733 --- /dev/null +++ b/roms/u-boot/doc/board/amlogic/s400.rst @@ -0,0 +1,109 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +U-Boot for Amlogic S400 +======================= + +S400 is a reference board manufactured by Amlogic with the following +specifications: + + - Amlogic A113DX ARM Cortex-A53 quad-core SoC @ 1.2GHz + - 1GB DDR4 SDRAM + - 10/100 Ethernet + - 2 x USB 2.0 Host + - eMMC + - Infrared receiver + - SDIO WiFi Module + - MIPI DSI Connector + - Audio HAT Connector + - PCI-E M.2 Connectors + +Schematics are available from Amlogic on demand. + +U-Boot compilation +------------------ + +.. code-block:: bash + + $ export CROSS_COMPILE=aarch64-none-elf- + $ make s400_defconfig + $ make + +Image creation +-------------- + +Amlogic doesn't provide sources for the firmware and for tools needed +to create the bootloader image, so it is necessary to obtain them from +the git tree published by the board vendor: + +.. code-block:: bash + + $ wget https://releases.linaro.org/archive/13.11/components/toolchain/binaries/gcc-linaro-aarch64-none-elf-4.8-2013.11_linux.tar.xz + $ wget https://releases.linaro.org/archive/13.11/components/toolchain/binaries/gcc-linaro-arm-none-eabi-4.8-2013.11_linux.tar.xz + $ tar xvfJ gcc-linaro-aarch64-none-elf-4.8-2013.11_linux.tar.xz + $ tar xvfJ gcc-linaro-arm-none-eabi-4.8-2013.11_linux.tar.xz + $ export PATH=$PWD/gcc-linaro-aarch64-none-elf-4.8-2013.11_linux/bin:$PWD/gcc-linaro-arm-none-eabi-4.8-2013.11_linux/bin:$PATH + $ git clone https://github.com/BayLibre/u-boot.git -b n-amlogic-openlinux-20170606 amlogic-u-boot + $ cd amlogic-u-boot + $ make axg_s400_v1_defconfig + $ make + $ export FIPDIR=$PWD/fip + +Go back to mainline U-boot source tree then : + +.. code-block:: bash + + $ mkdir fip + + $ cp $FIPDIR/axg/bl2.bin fip/ + $ cp $FIPDIR/axg/acs.bin fip/ + $ cp $FIPDIR/axg/bl21.bin fip/ + $ cp $FIPDIR/axg/bl30.bin fip/ + $ cp $FIPDIR/axg/bl301.bin fip/ + $ cp $FIPDIR/axg/bl31.img fip/ + $ cp u-boot.bin fip/bl33.bin + + $ $FIPDIR/blx_fix.sh \ + fip/bl30.bin \ + fip/zero_tmp \ + fip/bl30_zero.bin \ + fip/bl301.bin \ + fip/bl301_zero.bin \ + fip/bl30_new.bin \ + bl30 + + $ $FIPDIR/acs_tool.pyc fip/bl2.bin fip/bl2_acs.bin fip/acs.bin 0 + + $ $FIPDIR/blx_fix.sh \ + fip/bl2_acs.bin \ + fip/zero_tmp \ + fip/bl2_zero.bin \ + fip/bl21.bin \ + fip/bl21_zero.bin \ + fip/bl2_new.bin \ + bl2 + + $ $FIPDIR/axg/aml_encrypt_axg --bl3sig --input fip/bl30_new.bin \ + --output fip/bl30_new.bin.enc \ + --level v3 --type bl30 + $ $FIPDIR/axg/aml_encrypt_axg --bl3sig --input fip/bl31.img \ + --output fip/bl31.img.enc \ + --level v3 --type bl31 + $ $FIPDIR/axg/aml_encrypt_axg --bl3sig --input fip/bl33.bin --compress lz4 \ + --output fip/bl33.bin.enc \ + --level v3 --type bl33 + $ $FIPDIR/axg/aml_encrypt_axg --bl2sig --input fip/bl2_new.bin \ + --output fip/bl2.n.bin.sig + $ $FIPDIR/axg/aml_encrypt_axg --bootmk \ + --output fip/u-boot.bin \ + --bl2 fip/bl2.n.bin.sig \ + --bl30 fip/bl30_new.bin.enc \ + --bl31 fip/bl31.img.enc \ + --bl33 fip/bl33.bin.enc --level v3 + +and then write the image to SD with: + +.. code-block:: bash + + $ DEV=/dev/your_sd_device + $ dd if=fip/u-boot.bin.sd.bin of=$DEV conv=fsync,notrunc bs=512 skip=1 seek=1 + $ dd if=fip/u-boot.bin.sd.bin of=$DEV conv=fsync,notrunc bs=1 count=444 diff --git a/roms/u-boot/doc/board/amlogic/sei510.rst b/roms/u-boot/doc/board/amlogic/sei510.rst new file mode 100644 index 000000000..2d296b1c3 --- /dev/null +++ b/roms/u-boot/doc/board/amlogic/sei510.rst @@ -0,0 +1,130 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +U-Boot for Amlogic SEI510 +========================= + +SEI510 is a customer board manufactured by SEI Robotics with the following +specifications: + + - Amlogic S905X2 ARM Cortex-A53 quad-core SoC + - 2GB DDR4 SDRAM + - 10/100 Ethernet (Internal PHY) + - 1 x USB 3.0 Host + - eMMC + - SDcard + - Infrared receiver + - SDIO WiFi Module + +U-Boot compilation +------------------ + +.. code-block:: bash + + $ export CROSS_COMPILE=aarch64-none-elf- + $ make sei510_defconfig + $ make + +Image creation +-------------- + +Amlogic doesn't provide sources for the firmware and for tools needed +to create the bootloader image, so it is necessary to obtain them from +the git tree published by the board vendor: + +.. code-block:: bash + + $ wget https://releases.linaro.org/archive/13.11/components/toolchain/binaries/gcc-linaro-aarch64-none-elf-4.8-2013.11_linux.tar.xz + $ wget https://releases.linaro.org/archive/13.11/components/toolchain/binaries/gcc-linaro-arm-none-eabi-4.8-2013.11_linux.tar.xz + $ tar xvfJ gcc-linaro-aarch64-none-elf-4.8-2013.11_linux.tar.xz + $ tar xvfJ gcc-linaro-arm-none-eabi-4.8-2013.11_linux.tar.xz + $ export PATH=$PWD/gcc-linaro-aarch64-none-elf-4.8-2013.11_linux/bin:$PWD/gcc-linaro-arm-none-eabi-4.8-2013.11_linux/bin:$PATH + $ git clone https://github.com/BayLibre/u-boot.git -b buildroot-openlinux-20180418 amlogic-u-boot + $ cd amlogic-u-boot + $ make g12a_u200_v1_defconfig + $ make + $ export UBOOTDIR=$PWD + +Download the latest Amlogic Buildroot package, and extract it : + +.. code-block:: bash + + $ wget http://openlinux2.amlogic.com:8000/ARM/filesystem/Linux_BSP/buildroot_openlinux_kernel_4.9_fbdev_20180706.tar.gz + $ tar xfz buildroot_openlinux_kernel_4.9_fbdev_20180706.tar.gz buildroot_openlinux_kernel_4.9_fbdev_20180706/bootloader + $ export BRDIR=$PWD/buildroot_openlinux_kernel_4.9_fbdev_20180706 + $ export FIPDIR=$BRDIR/bootloader/uboot-repo/fip + +Go back to mainline U-Boot source tree then : + +.. code-block:: bash + + $ mkdir fip + + $ wget https://github.com/BayLibre/u-boot/releases/download/v2017.11-libretech-cc/blx_fix_g12a.sh -O fip/blx_fix.sh + $ cp $UBOOTDIR/build/scp_task/bl301.bin fip/ + $ cp $UBOOTDIR/build/board/amlogic/g12a_u200_v1/firmware/acs.bin fip/ + $ cp $BRDIR/bootloader/uboot-repo/bl2/bin/g12a/bl2.bin fip/ + $ cp $BRDIR/bootloader/uboot-repo/bl30/bin/g12a/bl30.bin fip/ + $ cp $BRDIR/bootloader/uboot-repo/bl31_1.3/bin/g12a/bl31.img fip/ + $ cp $FIPDIR/g12a/ddr3_1d.fw fip/ + $ cp $FIPDIR/g12a/ddr4_1d.fw fip/ + $ cp $FIPDIR/g12a/ddr4_2d.fw fip/ + $ cp $FIPDIR/g12a/diag_lpddr4.fw fip/ + $ cp $FIPDIR/g12a/lpddr4_1d.fw fip/ + $ cp $FIPDIR/g12a/lpddr4_2d.fw fip/ + $ cp $FIPDIR/g12a/piei.fw fip/ + $ cp u-boot.bin fip/bl33.bin + + $ sh fip/blx_fix.sh \ + fip/bl30.bin \ + fip/zero_tmp \ + fip/bl30_zero.bin \ + fip/bl301.bin \ + fip/bl301_zero.bin \ + fip/bl30_new.bin \ + bl30 + + $ sh fip/blx_fix.sh \ + fip/bl2.bin \ + fip/zero_tmp \ + fip/bl2_zero.bin \ + fip/acs.bin \ + fip/bl21_zero.bin \ + fip/bl2_new.bin \ + bl2 + + $ $FIPDIR/g12a/aml_encrypt_g12a --bl30sig --input fip/bl30_new.bin \ + --output fip/bl30_new.bin.g12a.enc \ + --level v3 + $ $FIPDIR/g12a/aml_encrypt_g12a --bl3sig --input fip/bl30_new.bin.g12a.enc \ + --output fip/bl30_new.bin.enc \ + --level v3 --type bl30 + $ $FIPDIR/g12a/aml_encrypt_g12a --bl3sig --input fip/bl31.img \ + --output fip/bl31.img.enc \ + --level v3 --type bl31 + $ $FIPDIR/g12a/aml_encrypt_g12a --bl3sig --input fip/bl33.bin --compress lz4 \ + --output fip/bl33.bin.enc \ + --level v3 --type bl33 + $ $FIPDIR/g12a/aml_encrypt_g12a --bl2sig --input fip/bl2_new.bin \ + --output fip/bl2.n.bin.sig + $ $FIPDIR/g12a/aml_encrypt_g12a --bootmk \ + --output fip/u-boot.bin \ + --bl2 fip/bl2.n.bin.sig \ + --bl30 fip/bl30_new.bin.enc \ + --bl31 fip/bl31.img.enc \ + --bl33 fip/bl33.bin.enc \ + --ddrfw1 fip/ddr4_1d.fw \ + --ddrfw2 fip/ddr4_2d.fw \ + --ddrfw3 fip/ddr3_1d.fw \ + --ddrfw4 fip/piei.fw \ + --ddrfw5 fip/lpddr4_1d.fw \ + --ddrfw6 fip/lpddr4_2d.fw \ + --ddrfw7 fip/diag_lpddr4.fw \ + --level v3 + +and then write the image to SD with: + +.. code-block:: bash + + $ DEV=/dev/your_sd_device + $ dd if=fip/u-boot.bin.sd.bin of=$DEV conv=fsync,notrunc bs=512 skip=1 seek=1 + $ dd if=fip/u-boot.bin.sd.bin of=$DEV conv=fsync,notrunc bs=1 count=444 diff --git a/roms/u-boot/doc/board/amlogic/sei610.rst b/roms/u-boot/doc/board/amlogic/sei610.rst new file mode 100644 index 000000000..9434e6f02 --- /dev/null +++ b/roms/u-boot/doc/board/amlogic/sei610.rst @@ -0,0 +1,133 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +U-Boot for Amlogic SEI610 +========================= + +SEI610 is a customer board manufactured by SEI Robotics with the following +specifications: + + - Amlogic S905X3 ARM Cortex-A55 quad-core SoC + - 2GB DDR4 SDRAM + - 10/100 Ethernet (Internal PHY) + - 1 x USB 3.0 Host + - 1 x USB Type-C DRD + - 1 x FTDI USB Serial Debug Interface + - eMMC + - SDcard + - Infrared receiver + - SDIO WiFi Module + +U-Boot compilation +------------------ + +.. code-block:: bash + + $ export CROSS_COMPILE=aarch64-none-elf- + $ make sei610_defconfig + $ make + +Image creation +-------------- + +Amlogic doesn't provide sources for the firmware and for tools needed +to create the bootloader image, so it is necessary to obtain them from +the git tree published by the board vendor: + +.. code-block:: bash + + $ wget https://releases.linaro.org/archive/13.11/components/toolchain/binaries/gcc-linaro-aarch64-none-elf-4.8-2013.11_linux.tar.xz + $ wget https://releases.linaro.org/archive/13.11/components/toolchain/binaries/gcc-linaro-arm-none-eabi-4.8-2013.11_linux.tar.xz + $ tar xvfJ gcc-linaro-aarch64-none-elf-4.8-2013.11_linux.tar.xz + $ tar xvfJ gcc-linaro-arm-none-eabi-4.8-2013.11_linux.tar.xz + $ export PATH=$PWD/gcc-linaro-aarch64-none-elf-4.8-2013.11_linux/bin:$PWD/gcc-linaro-arm-none-eabi-4.8-2013.11_linux/bin:$PATH + $ git clone https://github.com/BayLibre/u-boot.git -b buildroot-openlinux-4.9-g12a-201904 amlogic-u-boot + $ cd amlogic-u-boot + $ make sm1_ac200_v1_defconfig + $ make + $ export UBOOTDIR=$PWD + +Download the latest Amlogic Buildroot package, and extract it : + +.. code-block:: bash + + $ wget http://openlinux2.amlogic.com:8000/ARM/filesystem/buildroot-openlinux-A113-201901.tgz + $ tar xfz buildroot-openlinux-A113-201901.tgz buildroot-openlinux-A113-201901/bootloader + $ export BRDIR=$PWD/buildroot-openlinux-A113-201901 + $ export FIPDIR=$BRDIR/bootloader/uboot-repo/fip + +Go back to mainline U-Boot source tree then : + + +.. code-block:: bash + + $ mkdir fip + + $ wget https://github.com/BayLibre/u-boot/releases/download/v2017.11-libretech-cc/blx_fix_g12a.sh -O fip/blx_fix.sh + $ cp $UBOOTDIR/build/scp_task/bl301.bin fip/ + $ cp $UBOOTDIR/build/board/amlogic/g12a_u200_v1/firmware/acs.bin fip/ + $ cp $BRDIR/bootloader/uboot-repo/bl2/bin/g12a/bl2.bin fip/ + $ cp $BRDIR/bootloader/uboot-repo/bl30/bin/g12a/bl30.bin fip/ + $ cp $BRDIR/bootloader/uboot-repo/bl31_1.3/bin/g12a/bl31.img fip/ + $ cp $FIPDIR/g12a/ddr3_1d.fw fip/ + $ cp $FIPDIR/g12a/ddr4_1d.fw fip/ + $ cp $FIPDIR/g12a/ddr4_2d.fw fip/ + $ cp $FIPDIR/g12a/diag_lpddr4.fw fip/ + $ cp $FIPDIR/g12a/lpddr4_1d.fw fip/ + $ cp $FIPDIR/g12a/lpddr4_2d.fw fip/ + $ cp $FIPDIR/g12a/piei.fw fip/ + $ cp u-boot.bin fip/bl33.bin + + $ sh fip/blx_fix.sh \ + fip/bl30.bin \ + fip/zero_tmp \ + fip/bl30_zero.bin \ + fip/bl301.bin \ + fip/bl301_zero.bin \ + fip/bl30_new.bin \ + bl30 + + $ sh fip/blx_fix.sh \ + fip/bl2.bin \ + fip/zero_tmp \ + fip/bl2_zero.bin \ + fip/acs.bin \ + fip/bl21_zero.bin \ + fip/bl2_new.bin \ + bl2 + + $ $FIPDIR/g12a/aml_encrypt_g12a --bl30sig --input fip/bl30_new.bin \ + --output fip/bl30_new.bin.g12a.enc \ + --level v3 + $ $FIPDIR/g12a/aml_encrypt_g12a --bl3sig --input fip/bl30_new.bin.g12a.enc \ + --output fip/bl30_new.bin.enc \ + --level v3 --type bl30 + $ $FIPDIR/g12a/aml_encrypt_g12a --bl3sig --input fip/bl31.img \ + --output fip/bl31.img.enc \ + --level v3 --type bl31 + $ $FIPDIR/g12a/aml_encrypt_g12a --bl3sig --input fip/bl33.bin --compress lz4 \ + --output fip/bl33.bin.enc \ + --level v3 --type bl33 + $ $FIPDIR/g12a/aml_encrypt_g12a --bl2sig --input fip/bl2_new.bin \ + --output fip/bl2.n.bin.sig + $ $FIPDIR/g12a/aml_encrypt_g12a --bootmk \ + --output fip/u-boot.bin \ + --bl2 fip/bl2.n.bin.sig \ + --bl30 fip/bl30_new.bin.enc \ + --bl31 fip/bl31.img.enc \ + --bl33 fip/bl33.bin.enc \ + --ddrfw1 fip/ddr4_1d.fw \ + --ddrfw2 fip/ddr4_2d.fw \ + --ddrfw3 fip/ddr3_1d.fw \ + --ddrfw4 fip/piei.fw \ + --ddrfw5 fip/lpddr4_1d.fw \ + --ddrfw6 fip/lpddr4_2d.fw \ + --ddrfw7 fip/diag_lpddr4.fw \ + --level v3 + +and then write the image to SD with: + +.. code-block:: bash + + $ DEV=/dev/your_sd_device + $ dd if=fip/u-boot.bin.sd.bin of=$DEV conv=fsync,notrunc bs=512 skip=1 seek=1 + $ dd if=fip/u-boot.bin.sd.bin of=$DEV conv=fsync,notrunc bs=1 count=444 diff --git a/roms/u-boot/doc/board/amlogic/u200.rst b/roms/u-boot/doc/board/amlogic/u200.rst new file mode 100644 index 000000000..5aa3936c2 --- /dev/null +++ b/roms/u-boot/doc/board/amlogic/u200.rst @@ -0,0 +1,135 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +U-Boot for Amlogic U200 +======================= + +U200 is a reference board manufactured by Amlogic with the following +specifications: + + - Amlogic S905D2 ARM Cortex-A53 quad-core SoC + - 2GB DDR4 SDRAM + - 10/100 Ethernet (Internal PHY) + - 1 x USB 3.0 Host + - eMMC + - SDcard + - Infrared receiver + - SDIO WiFi Module + - MIPI DSI Connector + - Audio HAT Connector + - PCI-E M.2 Connector + +Schematics are available from Amlogic on demand. + +U-Boot compilation +------------------ + +.. code-block:: bash + + $ export CROSS_COMPILE=aarch64-none-elf- + $ make u200_defconfig + $ make + +Image creation +-------------- + +Amlogic doesn't provide sources for the firmware and for tools needed +to create the bootloader image, so it is necessary to obtain them from +the git tree published by the board vendor: + +.. code-block:: bash + + $ wget https://releases.linaro.org/archive/13.11/components/toolchain/binaries/gcc-linaro-aarch64-none-elf-4.8-2013.11_linux.tar.xz + $ wget https://releases.linaro.org/archive/13.11/components/toolchain/binaries/gcc-linaro-arm-none-eabi-4.8-2013.11_linux.tar.xz + $ tar xvfJ gcc-linaro-aarch64-none-elf-4.8-2013.11_linux.tar.xz + $ tar xvfJ gcc-linaro-arm-none-eabi-4.8-2013.11_linux.tar.xz + $ export PATH=$PWD/gcc-linaro-aarch64-none-elf-4.8-2013.11_linux/bin:$PWD/gcc-linaro-arm-none-eabi-4.8-2013.11_linux/bin:$PATH + $ git clone https://github.com/BayLibre/u-boot.git -b buildroot-openlinux-20180418 amlogic-u-boot + $ cd amlogic-u-boot + $ make g12a_u200_v1_defconfig + $ make + $ export UBOOTDIR=$PWD + +Download the latest Amlogic Buildroot package, and extract it : + +.. code-block:: bash + + $ wget http://openlinux2.amlogic.com:8000/ARM/filesystem/Linux_BSP/buildroot_openlinux_kernel_4.9_fbdev_20180706.tar.gz + $ tar xfz buildroot_openlinux_kernel_4.9_fbdev_20180706.tar.gz buildroot_openlinux_kernel_4.9_fbdev_20180706/bootloader + $ export BRDIR=$PWD/buildroot_openlinux_kernel_4.9_fbdev_20180706 + $ export FIPDIR=$BRDIR/bootloader/uboot-repo/fip + +Go back to mainline U-Boot source tree then : + +.. code-block:: bash + + $ mkdir fip + + $ wget https://github.com/BayLibre/u-boot/releases/download/v2017.11-libretech-cc/blx_fix_g12a.sh -O fip/blx_fix.sh + $ cp $UBOOTDIR/build/scp_task/bl301.bin fip/ + $ cp $UBOOTDIR/build/board/amlogic/g12a_u200_v1/firmware/acs.bin fip/ + $ cp $BRDIR/bootloader/uboot-repo/bl2/bin/g12a/bl2.bin fip/ + $ cp $BRDIR/bootloader/uboot-repo/bl30/bin/g12a/bl30.bin fip/ + $ cp $BRDIR/bootloader/uboot-repo/bl31_1.3/bin/g12a/bl31.img fip/ + $ cp $FIPDIR/g12a/ddr3_1d.fw fip/ + $ cp $FIPDIR/g12a/ddr4_1d.fw fip/ + $ cp $FIPDIR/g12a/ddr4_2d.fw fip/ + $ cp $FIPDIR/g12a/diag_lpddr4.fw fip/ + $ cp $FIPDIR/g12a/lpddr4_1d.fw fip/ + $ cp $FIPDIR/g12a/lpddr4_2d.fw fip/ + $ cp $FIPDIR/g12a/piei.fw fip/ + $ cp u-boot.bin fip/bl33.bin + + $ sh fip/blx_fix.sh \ + fip/bl30.bin \ + fip/zero_tmp \ + fip/bl30_zero.bin \ + fip/bl301.bin \ + fip/bl301_zero.bin \ + fip/bl30_new.bin \ + bl30 + + $ sh fip/blx_fix.sh \ + fip/bl2.bin \ + fip/zero_tmp \ + fip/bl2_zero.bin \ + fip/acs.bin \ + fip/bl21_zero.bin \ + fip/bl2_new.bin \ + bl2 + + $ $FIPDIR/g12a/aml_encrypt_g12a --bl30sig --input fip/bl30_new.bin \ + --output fip/bl30_new.bin.g12a.enc \ + --level v3 + $ $FIPDIR/g12a/aml_encrypt_g12a --bl3sig --input fip/bl30_new.bin.g12a.enc \ + --output fip/bl30_new.bin.enc \ + --level v3 --type bl30 + $ $FIPDIR/g12a/aml_encrypt_g12a --bl3sig --input fip/bl31.img \ + --output fip/bl31.img.enc \ + --level v3 --type bl31 + $ $FIPDIR/g12a/aml_encrypt_g12a --bl3sig --input fip/bl33.bin --compress lz4 \ + --output fip/bl33.bin.enc \ + --level v3 --type bl33 + $ $FIPDIR/g12a/aml_encrypt_g12a --bl2sig --input fip/bl2_new.bin \ + --output fip/bl2.n.bin.sig + $ $FIPDIR/g12a/aml_encrypt_g12a --bootmk \ + --output fip/u-boot.bin \ + --bl2 fip/bl2.n.bin.sig \ + --bl30 fip/bl30_new.bin.enc \ + --bl31 fip/bl31.img.enc \ + --bl33 fip/bl33.bin.enc \ + --ddrfw1 fip/ddr4_1d.fw \ + --ddrfw2 fip/ddr4_2d.fw \ + --ddrfw3 fip/ddr3_1d.fw \ + --ddrfw4 fip/piei.fw \ + --ddrfw5 fip/lpddr4_1d.fw \ + --ddrfw6 fip/lpddr4_2d.fw \ + --ddrfw7 fip/diag_lpddr4.fw \ + --level v3 + +and then write the image to SD with: + +.. code-block:: bash + + $ DEV=/dev/your_sd_device + $ dd if=fip/u-boot.bin.sd.bin of=$DEV conv=fsync,notrunc bs=512 skip=1 seek=1 + $ dd if=fip/u-boot.bin.sd.bin of=$DEV conv=fsync,notrunc bs=1 count=444 diff --git a/roms/u-boot/doc/board/amlogic/w400.rst b/roms/u-boot/doc/board/amlogic/w400.rst new file mode 100644 index 000000000..38dbf52fb --- /dev/null +++ b/roms/u-boot/doc/board/amlogic/w400.rst @@ -0,0 +1,137 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +U-Boot for Amlogic W400 +======================= + +U200 is a reference board manufactured by Amlogic with the following +specifications: + + - Amlogic S922X ARM Cortex-A53 dual-core + Cortex-A73 quad-core SoC + - 2GB DDR4 SDRAM + - 10/100 Ethernet (Internal PHY) + - 1 x USB 3.0 Host + - eMMC + - SDcard + - Infrared receiver + - SDIO WiFi Module + - MIPI DSI Connector + - Audio HAT Connector + - PCI-E M.2 Connector + +Schematics are available from Amlogic on demand. + +U-Boot compilation +------------------ + +.. code-block:: bash + + $ export CROSS_COMPILE=aarch64-none-elf- + $ make w400_defconfig + $ make + +Image creation +-------------- + +Amlogic doesn't provide sources for the firmware and for tools needed +to create the bootloader image, so it is necessary to obtain them from +the git tree published by the board vendor: + +.. code-block:: bash + + $ wget https://releases.linaro.org/archive/13.11/components/toolchain/binaries/gcc-linaro-aarch64-none-elf-4.8-2013.11_linux.tar.xz + $ wget https://releases.linaro.org/archive/13.11/components/toolchain/binaries/gcc-linaro-arm-none-eabi-4.8-2013.11_linux.tar.xz + $ tar xvfJ gcc-linaro-aarch64-none-elf-4.8-2013.11_linux.tar.xz + $ tar xvfJ gcc-linaro-arm-none-eabi-4.8-2013.11_linux.tar.xz + $ export PATH=$PWD/gcc-linaro-aarch64-none-elf-4.8-2013.11_linux/bin:$PWD/gcc-linaro-arm-none-eabi-4.8-2013.11_linux/bin:$PATH + $ git clone https://github.com/BayLibre/u-boot.git -b buildroot-openlinux-20180418 amlogic-u-boot + $ cd amlogic-u-boot + $ make g12b_w400_v1_defconfig + $ make + $ export UBOOTDIR=$PWD + +Download the latest Amlogic Buildroot package, and extract it : + +.. code-block:: bash + + $ wget http://openlinux2.amlogic.com:8000/ARM/filesystem/Linux_BSP/buildroot_openlinux_kernel_4.9_fbdev_20180706.tar.gz + $ tar xfz buildroot_openlinux_kernel_4.9_fbdev_20180706.tar.gz buildroot_openlinux_kernel_4.9_fbdev_20180706/bootloader + $ export BRDIR=$PWD/buildroot_openlinux_kernel_4.9_fbdev_20180706 + $ export FIPDIR=$BRDIR/bootloader/uboot-repo/fip + +Go back to mainline U-Boot source tree then : + +.. code-block:: bash + + $ mkdir fip + + $ wget https://github.com/BayLibre/u-boot/releases/download/v2017.11-libretech-cc/blx_fix_g12a.sh -O fip/blx_fix.sh + $ cp $UBOOTDIR/build/scp_task/bl301.bin fip/ + $ cp $UBOOTDIR/build/board/amlogic/g12b_w400_v1/firmware/acs.bin fip/ + $ cp $BRDIR/bootloader/uboot-repo/bl2/bin/g12b/bl2.bin fip/ + $ cp $BRDIR/bootloader/uboot-repo/bl30/bin/g12b/bl30.bin fip/ + $ cp $BRDIR/bootloader/uboot-repo/bl31_1.3/bin/g12b/bl31.img fip/ + $ cp $FIPDIR/g12b/ddr3_1d.fw fip/ + $ cp $FIPDIR/g12b/ddr4_1d.fw fip/ + $ cp $FIPDIR/g12b/ddr4_2d.fw fip/ + $ cp $FIPDIR/g12b/diag_lpddr4.fw fip/ + $ cp $FIPDIR/g12b/lpddr4_1d.fw fip/ + $ cp $FIPDIR/g12b/lpddr4_2d.fw fip/ + $ cp $FIPDIR/g12b/piei.fw fip/ + $ cp $FIPDIR/g12b/aml_ddr.fw fip/ + $ cp u-boot.bin fip/bl33.bin + + $ sh fip/blx_fix.sh \ + fip/bl30.bin \ + fip/zero_tmp \ + fip/bl30_zero.bin \ + fip/bl301.bin \ + fip/bl301_zero.bin \ + fip/bl30_new.bin \ + bl30 + + $ sh fip/blx_fix.sh \ + fip/bl2.bin \ + fip/zero_tmp \ + fip/bl2_zero.bin \ + fip/acs.bin \ + fip/bl21_zero.bin \ + fip/bl2_new.bin \ + bl2 + + $ $FIPDIR/g12b/aml_encrypt_g12b --bl30sig --input fip/bl30_new.bin \ + --output fip/bl30_new.bin.g12a.enc \ + --level v3 + $ $FIPDIR/g12b/aml_encrypt_g12b --bl3sig --input fip/bl30_new.bin.g12a.enc \ + --output fip/bl30_new.bin.enc \ + --level v3 --type bl30 + $ $FIPDIR/g12b/aml_encrypt_g12b --bl3sig --input fip/bl31.img \ + --output fip/bl31.img.enc \ + --level v3 --type bl31 + $ $FIPDIR/g12b/aml_encrypt_g12b --bl3sig --input fip/bl33.bin --compress lz4 \ + --output fip/bl33.bin.enc \ + --level v3 --type bl33 + $ $FIPDIR/g12b/aml_encrypt_g12b --bl2sig --input fip/bl2_new.bin \ + --output fip/bl2.n.bin.sig + $ $FIPDIR/g12b/aml_encrypt_g12b --bootmk \ + --output fip/u-boot.bin \ + --bl2 fip/bl2.n.bin.sig \ + --bl30 fip/bl30_new.bin.enc \ + --bl31 fip/bl31.img.enc \ + --bl33 fip/bl33.bin.enc \ + --ddrfw1 fip/ddr4_1d.fw \ + --ddrfw2 fip/ddr4_2d.fw \ + --ddrfw3 fip/ddr3_1d.fw \ + --ddrfw4 fip/piei.fw \ + --ddrfw5 fip/lpddr4_1d.fw \ + --ddrfw6 fip/lpddr4_2d.fw \ + --ddrfw7 fip/diag_lpddr4.fw \ + --ddrfw8 fip/aml_ddr.fw \ + --level v3 + +and then write the image to SD with: + +.. code-block:: bash + + $ DEV=/dev/your_sd_device + $ dd if=fip/u-boot.bin.sd.bin of=$DEV conv=fsync,notrunc bs=512 skip=1 seek=1 + $ dd if=fip/u-boot.bin.sd.bin of=$DEV conv=fsync,notrunc bs=1 count=444 diff --git a/roms/u-boot/doc/board/amlogic/wetek-core2.rst b/roms/u-boot/doc/board/amlogic/wetek-core2.rst new file mode 100644 index 000000000..1012079de --- /dev/null +++ b/roms/u-boot/doc/board/amlogic/wetek-core2.rst @@ -0,0 +1,96 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +U-Boot for WeTek Core2 +====================== + +WeTek Core2 is an Android STB based on the Q200 reference design with +the following specifications: + + - Amlogic S912 ARM Cortex-A53 octo-core SoC @ 1.5GHz + - ARM Mali T820 GPU + - 3GB DDR4 SDRAM + - 10/100 Realtek RTL8152 Ethernet (internal USB) + - HDMI 2.0 4K/60Hz display + - 2x USB 2.0 Host, 1x USB 2.0 OTG (internal) + - 32GB eMMC + - microSD + - SDIO Wifi Module, Bluetooth + - Two channel IR receiver + +U-Boot compilation +------------------ + +.. code-block:: bash + + $ export CROSS_COMPILE=aarch64-none-elf- + $ make wetek-core2_defconfig + $ make + +Image creation +-------------- + +Amlogic does not provide sources for the firmware or the tools needed +to create the bootloader image, and WeTek has not publicly shared the +precompiled FIP binaries. However the public Khadas VIM2 sources also +work with the Core2 box so we can use the Khadas git tree: + +.. code-block:: bash + + $ wget https://releases.linaro.org/archive/13.11/components/toolchain/binaries/gcc-linaro-aarch64-none-elf-4.8-2013.11_linux.tar.xz + $ wget https://releases.linaro.org/archive/13.11/components/toolchain/binaries/gcc-linaro-arm-none-eabi-4.8-2013.11_linux.tar.xz + $ tar xvfJ gcc-linaro-aarch64-none-elf-4.8-2013.11_linux.tar.xz + $ tar xvfJ gcc-linaro-arm-none-eabi-4.8-2013.11_linux.tar.xz + $ export PATH=$PWD/gcc-linaro-aarch64-none-elf-4.8-2013.11_linux/bin:$PWD/gcc-linaro-arm-none-eabi-4.8-2013.11_linux/bin:$PATH + $ git clone https://github.com/khadas/u-boot -b khadas-vim-v2015.01 vim-u-boot + $ cd vim-u-boot + $ make kvim2_defconfig + $ make + $ export FIPDIR=$PWD/fip + +Go back to mainline U-Boot source tree then: + +.. code-block:: bash + + $ mkdir fip + $ cp $FIPDIR/gxl/bl2.bin fip/ + $ cp $FIPDIR/gxl/acs.bin fip/ + $ cp $FIPDIR/gxl/bl21.bin fip/ + $ cp $FIPDIR/gxl/bl30.bin fip/ + $ cp $FIPDIR/gxl/bl301.bin fip/ + $ cp $FIPDIR/gxl/bl31.img fip/ + $ cp u-boot.bin fip/bl33.bin + $ $FIPDIR/blx_fix.sh \ + fip/bl30.bin \ + fip/zero_tmp \ + fip/bl30_zero.bin \ + fip/bl301.bin \ + fip/bl301_zero.bin \ + fip/bl30_new.bin \ + bl30 + $ python $FIPDIR/acs_tool.pyc fip/bl2.bin fip/bl2_acs.bin fip/acs.bin 0 + $ $FIPDIR/blx_fix.sh \ + fip/bl2_acs.bin \ + fip/zero_tmp \ + fip/bl2_zero.bin \ + fip/bl21.bin \ + fip/bl21_zero.bin \ + fip/bl2_new.bin \ + bl2 + $ $FIPDIR/gxl/aml_encrypt_gxl --bl3enc --input fip/bl30_new.bin + $ $FIPDIR/gxl/aml_encrypt_gxl --bl3enc --input fip/bl31.img + $ $FIPDIR/gxl/aml_encrypt_gxl --bl3enc --input fip/bl33.bin + $ $FIPDIR/gxl/aml_encrypt_gxl --bl2sig --input fip/bl2_new.bin --output fip/bl2.n.bin.sig + $ $FIPDIR/gxl/aml_encrypt_gxl --bootmk \ + --output fip/u-boot.bin \ + --bl2 fip/bl2.n.bin.sig \ + --bl30 fip/bl30_new.bin.enc \ + --bl31 fip/bl31.img.enc \ + --bl33 fip/bl33.bin.enc + +then write the image to SD with: + +.. code-block:: bash + + $ DEV=/dev/your_sd_device + $ dd if=fip/u-boot.bin.sd.bin of=$DEV conv=fsync,notrunc bs=512 skip=1 seek=1 + $ dd if=fip/u-boot.bin.sd.bin of=$DEV conv=fsync,notrunc bs=1 count=444 diff --git a/roms/u-boot/doc/board/atmel/at91ek.rst b/roms/u-boot/doc/board/atmel/at91ek.rst new file mode 100644 index 000000000..6185b1dfb --- /dev/null +++ b/roms/u-boot/doc/board/atmel/at91ek.rst @@ -0,0 +1,192 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +AT91 Evaluation kits +==================== + +Board mapping & boot media +-------------------------- + +AT91SAM9260EK, AT91SAM9G20EK & AT91SAM9XEEK +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Memory map:: + + 0x20000000 - 23FFFFFF SDRAM (64 MB) + 0xC0000000 - Cxxxxxxx Atmel Dataflash card (J13) + 0xD0000000 - D07FFFFF Soldered Atmel Dataflash (AT45DB642) + +Environment variables + +U-Boot environment variables can be stored at different places: + + - Dataflash on SPI chip select 1 (default) + - Dataflash on SPI chip select 0 (dataflash card) + - Nand flash + +You can choose your storage location at config step (here for at91sam9260ek):: + + make at91sam9260ek_nandflash_config - use nand flash + make at91sam9260ek_dataflash_cs0_config - use data flash (spi cs0) + make at91sam9260ek_dataflash_cs1_config - use data flash (spi cs1) + + +AT91SAM9261EK, AT91SAM9G10EK +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Memory map:: + + 0x20000000 - 23FFFFFF SDRAM (64 MB) + 0xC0000000 - C07FFFFF Soldered Atmel Dataflash (AT45DB642) + 0xD0000000 - Dxxxxxxx Atmel Dataflash card (J22) + +Environment variables + +U-Boot environment variables can be stored at different places: + + - Dataflash on SPI chip select 0 (default) + - Dataflash on SPI chip select 3 (dataflash card) + - Nand flash + +You can choose your storage location at config step (here for at91sam9260ek):: + + make at91sam9261ek_nandflash_config - use nand flash + make at91sam9261ek_dataflash_cs0_config - use data flash (spi cs0) + make at91sam9261ek_dataflash_cs3_config - use data flash (spi cs3) + + +AT91SAM9263EK +^^^^^^^^^^^^^ + +Memory map:: + + 0x20000000 - 23FFFFFF SDRAM (64 MB) + 0xC0000000 - Cxxxxxxx Atmel Dataflash card (J9) + +Environment variables + +U-Boot environment variables can be stored at different places: + + - Dataflash on SPI chip select 0 (dataflash card) + - Nand flash + - Nor flash (not populate by default) + +You can choose your storage location at config step (here for at91sam9260ek):: + + make at91sam9263ek_nandflash_config - use nand flash + make at91sam9263ek_dataflash_cs0_config - use data flash (spi cs0) + make at91sam9263ek_norflash_config - use nor flash + +You can choose to boot directly from U-Boot at config step:: + + make at91sam9263ek_norflash_boot_config - boot from nor flash + + +AT91SAM9M10G45EK +^^^^^^^^^^^^^^^^ + +Memory map:: + + 0x70000000 - 77FFFFFF SDRAM (128 MB) + +Environment variables + +U-Boot environment variables can be stored at different places: + + - Nand flash + +You can choose your storage location at config step (here for at91sam9m10g45ek):: + + make at91sam9m10g45ek_nandflash_config - use nand flash + + +AT91SAM9RLEK +^^^^^^^^^^^^ + +Memory map:: + + 0x20000000 - 23FFFFFF SDRAM (64 MB) + 0xC0000000 - C07FFFFF Soldered Atmel Dataflash (AT45DB642) + +Environment variables + +U-Boot environment variables can be stored at different places: + + - Dataflash on SPI chip select 0 + - Nand flash. + +You can choose your storage location at config step (here for at91sam9rlek):: + + make at91sam9rlek_nandflash_config - use nand flash + + +AT91SAM9N12EK, AT91SAM9X5EK +^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Memory map:: + + 0x20000000 - 27FFFFFF SDRAM (128 MB) + +Environment variables + +U-Boot environment variables can be stored at different places: + + - Nand flash + - SD/MMC card + - Serialflash/Dataflash on SPI chip select 0 + +You can choose your storage location at config step (here for at91sam9x5ek):: + + make at91sam9x5ek_dataflash_config - use data flash + make at91sam9x5ek_mmc_config - use sd/mmc card + make at91sam9x5ek_nandflash_config - use nand flash + make at91sam9x5ek_spiflash_config - use serial flash + + +SAMA5D3XEK +^^^^^^^^^^ + +Memory map:: + + 0x20000000 - 3FFFFFFF SDRAM (512 MB) + +Environment variables + +U-Boot environment variables can be stored at different places: + + - Nand flash + - SD/MMC card + - Serialflash on SPI chip select 0 + +You can choose your storage location at config step (here for sama5d3xek):: + + make sama5d3xek_mmc_config - use SD/MMC card + make sama5d3xek_nandflash_config - use nand flash + make sama5d3xek_serialflash_config - use serial flash + + +NAND partition table +-------------------- + +All the board support boot from NAND flash will use the following NAND +partition table:: + + 0x00000000 - 0x0003FFFF bootstrap (256 KiB) + 0x00040000 - 0x000BFFFF u-boot (512 KiB) + 0x000C0000 - 0x000FFFFF env (256 KiB) + 0x00100000 - 0x0013FFFF env_redundant (256 KiB) + 0x00140000 - 0x0017FFFF spare (256 KiB) + 0x00180000 - 0x001FFFFF dtb (512 KiB) + 0x00200000 - 0x007FFFFF kernel (6 MiB) + 0x00800000 - 0xxxxxxxxx rootfs (All left) + + +Watchdog support +---------------- + +For security reasons, the at91 watchdog is running at boot time and, +if deactivated, cannot be used anymore. +If you want to use the watchdog, you will need to keep it running in +your code (make sure not to disable it in AT91Bootstrap for instance). + +In the U-Boot configuration, the AT91 watchdog support is enabled using +the CONFIG_WDT and CONFIG_WDT_AT91 options. diff --git a/roms/u-boot/doc/board/atmel/index.rst b/roms/u-boot/doc/board/atmel/index.rst new file mode 100644 index 000000000..8ba00fc22 --- /dev/null +++ b/roms/u-boot/doc/board/atmel/index.rst @@ -0,0 +1,9 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +Atmel +===== + +.. toctree:: + :maxdepth: 2 + + at91ek diff --git a/roms/u-boot/doc/board/congatec/cgtqmx8.rst b/roms/u-boot/doc/board/congatec/cgtqmx8.rst new file mode 100644 index 000000000..bccdef2f1 --- /dev/null +++ b/roms/u-boot/doc/board/congatec/cgtqmx8.rst @@ -0,0 +1,70 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +U-Boot for the Congatec conga-QMX8 board +======================================== + +Quick Start +----------- + +- Build the ARM Trusted firmware binary +- Get scfw_tcm.bin and ahab-container.img +- Get imx-mkimage +- Build U-Boot +- Build imx-mkimage +- Flash the binary into the SD card +- Boot + +Get and Build the ARM Trusted firmware +-------------------------------------- + +.. code-block:: bash + + $ git clone https://source.codeaurora.org/external/imx/imx-atf + $ cd imx-atf/ + $ git checkout origin/imx_4.14.78_1.0.0_ga -b imx_4.14.78_1.0.0_ga + $ make PLAT=imx8qm bl31 + +Get scfw_tcm.bin and ahab-container.img +--------------------------------------- + +.. code-block:: bash + + $ wget https://www.nxp.com/lgfiles/NMG/MAD/YOCTO/imx-sc-firmware-1.1.bin + $ chmod +x imx-sc-firmware-1.1.bin + $ ./imx-sc-firmware-1.1.bin + $ wget https://www.nxp.com/lgfiles/NMG/MAD/YOCTO/firmware-imx-8.0.bin + $ chmod +x firmware-imx-8.0.bin + $ ./firmware-imx-8.0.bin + +Or use this to avoid running random scripts from the internet, +but note that you must agree to the license the script displays: + +.. code-block:: bash + + $ dd if=imx-sc-firmware-1.1.bin of=imx-sc-firmware-1.1.tar.bz2 bs=37185 skip=1 + $ tar -xf imx-sc-firmware-1.1.tar.bz2 + $ cp imx-sc-firmware-1.1/mx8qx-val-scfw-tcm.bin $(builddir) + + $ dd if=firmware-imx-8.0.bin of=firmware-imx-8.0.tar.bz2 bs=37180 skip=1 + $ tar -xf firmware-imx-8.0.tar.bz2 + $ cp firmware-imx-8.0/firmware/seco/mx8qm-ahab-container.img $(builddir) + +Build U-Boot +------------ + +.. code-block:: bash + + $ export ATF_LOAD_ADDR=0x80000000 + $ export BL33_LOAD_ADDR=0x80020000 + $ make cgtqmx8_defconfig + $ make u-boot.bin + $ make flash.bin + +Flash the binary into the SD card +--------------------------------- + +Burn the flash.bin binary to SD card offset 32KB: + +.. code-block:: bash + + $ sudo dd if=flash.bin of=/dev/sd[x] bs=1k seek=32 conv=fsync diff --git a/roms/u-boot/doc/board/congatec/index.rst b/roms/u-boot/doc/board/congatec/index.rst new file mode 100644 index 000000000..cc57b36b2 --- /dev/null +++ b/roms/u-boot/doc/board/congatec/index.rst @@ -0,0 +1,9 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +Congatec +======== + +.. toctree:: + :maxdepth: 2 + + cgtqmx8.rst diff --git a/roms/u-boot/doc/board/coreboot/coreboot.rst b/roms/u-boot/doc/board/coreboot/coreboot.rst new file mode 100644 index 000000000..9c44c025a --- /dev/null +++ b/roms/u-boot/doc/board/coreboot/coreboot.rst @@ -0,0 +1,52 @@ +.. SPDX-License-Identifier: GPL-2.0+ +.. sectionauthor:: Bin Meng <bmeng.cn@gmail.com> + +Coreboot +======== + +Build Instructions for U-Boot as coreboot payload +------------------------------------------------- +Building U-Boot as a coreboot payload is just like building U-Boot for targets +on other architectures, like below:: + + $ make coreboot_defconfig + $ make all + +Test with coreboot +------------------ +For testing U-Boot as the coreboot payload, there are things that need be paid +attention to. coreboot supports loading an ELF executable and a 32-bit plain +binary, as well as other supported payloads. With the default configuration, +U-Boot is set up to use a separate Device Tree Blob (dtb). As of today, the +generated u-boot-dtb.bin needs to be packaged by the cbfstool utility (a tool +provided by coreboot) manually as coreboot's 'make menuconfig' does not provide +this capability yet. The command is as follows:: + + # in the coreboot root directory + $ ./build/util/cbfstool/cbfstool build/coreboot.rom add-flat-binary \ + -f u-boot-dtb.bin -n fallback/payload -c lzma -l 0x1110000 -e 0x1110000 + +Make sure 0x1110000 matches CONFIG_SYS_TEXT_BASE, which is the symbol address +of _x86boot_start (in arch/x86/cpu/start.S). + +If you want to use ELF as the coreboot payload, change U-Boot configuration to +use CONFIG_OF_EMBED instead of CONFIG_OF_SEPARATE. + +To enable video you must enable these options in coreboot: + + - Set framebuffer graphics resolution (1280x1024 32k-color (1:5:5)) + - Keep VESA framebuffer + +At present it seems that for Minnowboard Max, coreboot does not pass through +the video information correctly (it always says the resolution is 0x0). This +works correctly for link though. + +64-bit U-Boot +------------- + +In addition to the 32-bit 'coreboot' build there is a 'coreboot64' build. This +produces an image which can be booted from coreboot (32-bit). Internally it +works by using a 32-bit SPL binary to switch to 64-bit for running U-Boot. It +can be useful for running UEFI applications, for example. + +This has only been lightly tested. diff --git a/roms/u-boot/doc/board/coreboot/index.rst b/roms/u-boot/doc/board/coreboot/index.rst new file mode 100644 index 000000000..d148db95f --- /dev/null +++ b/roms/u-boot/doc/board/coreboot/index.rst @@ -0,0 +1,9 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +Coreboot +======== + +.. toctree:: + :maxdepth: 2 + + coreboot diff --git a/roms/u-boot/doc/board/emulation/index.rst b/roms/u-boot/doc/board/emulation/index.rst new file mode 100644 index 000000000..be66b6bb6 --- /dev/null +++ b/roms/u-boot/doc/board/emulation/index.rst @@ -0,0 +1,14 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +Emulation +========= + +.. toctree:: + :maxdepth: 2 + + qemu-arm + qemu-mips + qemu-ppce500 + qemu-riscv + qemu-x86 + qemu_capsule_update diff --git a/roms/u-boot/doc/board/emulation/qemu-arm.rst b/roms/u-boot/doc/board/emulation/qemu-arm.rst new file mode 100644 index 000000000..8d7fda10f --- /dev/null +++ b/roms/u-boot/doc/board/emulation/qemu-arm.rst @@ -0,0 +1,92 @@ +.. SPDX-License-Identifier: GPL-2.0+ +.. Copyright (C) 2017, Tuomas Tynkkynen <tuomas.tynkkynen@iki.fi> + +QEMU ARM +======== + +QEMU for ARM supports a special 'virt' machine designed for emulation and +virtualization purposes. This document describes how to run U-Boot under it. +Both 32-bit ARM and AArch64 are supported. + +The 'virt' platform provides the following as the basic functionality: + + - A freely configurable amount of CPU cores + - U-Boot loaded and executing in the emulated flash at address 0x0 + - A generated device tree blob placed at the start of RAM + - A freely configurable amount of RAM, described by the DTB + - A PL011 serial port, discoverable via the DTB + - An ARMv7/ARMv8 architected timer + - PSCI for rebooting the system + - A generic ECAM-based PCI host controller, discoverable via the DTB + +Additionally, a number of optional peripherals can be added to the PCI bus. + +Building U-Boot +--------------- +Set the CROSS_COMPILE environment variable as usual, and run: + +- For ARM:: + + make qemu_arm_defconfig + make + +- For AArch64:: + + make qemu_arm64_defconfig + make + +Running U-Boot +-------------- +The minimal QEMU command line to get U-Boot up and running is: + +- For ARM:: + + qemu-system-arm -machine virt -bios u-boot.bin + +- For AArch64:: + + qemu-system-aarch64 -machine virt -cpu cortex-a57 -bios u-boot.bin + +Note that for some odd reason qemu-system-aarch64 needs to be explicitly +told to use a 64-bit CPU or it will boot in 32-bit mode. + +Additional persistent U-boot environment support can be added as follows: + +- Create envstore.img using qemu-img:: + + qemu-img create -f raw envstore.img 64M + +- Add a pflash drive parameter to the command line:: + + -drive if=pflash,format=raw,index=1,file=envstore.img + +Additional peripherals that have been tested to work in both U-Boot and Linux +can be enabled with the following command line parameters: + +- To add a Serial ATA disk via an Intel ICH9 AHCI controller, pass e.g.:: + + -drive if=none,file=disk.img,id=mydisk -device ich9-ahci,id=ahci -device ide-drive,drive=mydisk,bus=ahci.0 + +- To add an Intel E1000 network adapter, pass e.g.:: + + -netdev user,id=net0 -device e1000,netdev=net0 + +- To add an EHCI-compliant USB host controller, pass e.g.:: + + -device usb-ehci,id=ehci + +- To add a NVMe disk, pass e.g.:: + + -drive if=none,file=disk.img,id=mydisk -device nvme,drive=mydisk,serial=foo + +These have been tested in QEMU 2.9.0 but should work in at least 2.5.0 as well. + +Debug UART +---------- + +The debug UART on the ARM virt board uses these settings:: + + CONFIG_DEBUG_UART=y + CONFIG_DEBUG_UART_PL010=y + CONFIG_DEBUG_UART_BASE=0x9000000 + CONFIG_DEBUG_UART_CLOCK=0 diff --git a/roms/u-boot/doc/board/emulation/qemu-mips.rst b/roms/u-boot/doc/board/emulation/qemu-mips.rst new file mode 100644 index 000000000..5fd8a0a23 --- /dev/null +++ b/roms/u-boot/doc/board/emulation/qemu-mips.rst @@ -0,0 +1,129 @@ +.. SPDX-License-Identifier: GPL-2.0+ +.. sectionauthor:: Daniel Schwierzeck <daniel.schwierzeck@gmail.com> + +QEMU MIPS +========= + +Qemu for MIPS is based on the MIPS Malta board. The built Malta U-Boot +images can be used for Qemu and on physical hardware. The Malta board +supports all combinations of Little and Big Endian as well as 32 bit +and 64 bit. + +Limitations & comments +---------------------- +The memory size for Qemu is hard-coded to 256 MiB. For Malta Little Endian +targets an extra endianness swapped image named *u-boot-swap.bin* is +generated and required for Qemu. + +Example usage +------------- + +Build for 32 bit, big endian: + +.. code-block:: bash + + make malta_defconfig + make + UBOOT_BIN=u-boot.bin + QEMU_BIN=qemu-system-mips + QEMU_CPU=24Kc + +Build for 32 bit, little endian: + +.. code-block:: bash + + make maltael_defconfig + make + UBOOT_BIN=u-boot-swap.bin + QEMU_BIN=qemu-system-mipsel + QEMU_CPU=24Kc + +Build for 64 bit, big endian: + +.. code-block:: bash + + make malta64_defconfig + make + UBOOT_BIN=u-boot.bin + QEMU_BIN=qemu-system-mips64 + QEMU_CPU=MIPS64R2-generic + +Build for 64 bit, little endian: + +.. code-block:: bash + + make malta64el_defconfig + make + UBOOT_BIN=u-boot-swap.bin + QEMU_BIN=qemu-system-mips64el + QEMU_CPU=MIPS64R2-generic + +Generate NOR flash image with U-Boot binary: + +.. code-block:: bash + + dd if=/dev/zero bs=1M count=4 | tr '\000' '\377' > pflash.img + dd if=${UBOOT_BIN} of=pflash.img conv=notrunc + +Start Qemu: + +.. code-block:: bash + + mkdir tftproot + ${QEMU_BIN} -nographic -cpu ${QEMU_CPU} -m 256 -drive if=pflash,file="$(pwd)/pflash.img",format=raw -netdev user,id=net0,tftp="$(pwd)/tftproot" -device pcnet,netdev=net0 + +.. code-block:: bash + + U-Boot 2021.04-00963-g60279a2b1d (Apr 21 2021 - 19:54:32 +0200) + + Board: MIPS Malta CoreLV + DRAM: 256 MiB + Flash: 4 MiB + Loading Environment from Flash... *** Warning - bad CRC, using default environment + + In: serial@3f8 + Out: serial@3f8 + Err: serial@3f8 + Net: pcnet#0 + IDE: Bus 0: not available + maltael # + +How to debug U-Boot +------------------- + +In order to debug U-Boot you need to start qemu with gdb server support (-s) +and waiting the connection to start the CPU (-S). Start Qemu in the first console: + +.. code-block:: bash + + mkdir tftproot + ${QEMU_BIN} -s -S -nographic -cpu ${QEMU_CPU} -m 256 -drive if=pflash,file="$(pwd)/pflash.img",format=raw -netdev user,id=net0,tftp="$(pwd)/tftproot" -device pcnet,netdev=net0 + +In the second console start gdb: + +.. code-block:: bash + + gdb-multiarch --eval-command "target remote :1234" u-boot + +.. code-block:: bash + + GNU gdb (Ubuntu 9.2-0ubuntu1~20.04) 9.2 + Copyright (C) 2020 Free Software Foundation, Inc. + License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html> + This is free software: you are free to change and redistribute it. + There is NO WARRANTY, to the extent permitted by law. + Type "show copying" and "show warranty" for details. + This GDB was configured as "x86_64-linux-gnu". + Type "show configuration" for configuration details. + For bug reporting instructions, please see: + <http://www.gnu.org/software/gdb/bugs/>. + Find the GDB manual and other documentation resources online at: + <http://www.gnu.org/software/gdb/documentation/>. + + For help, type "help". + Type "apropos word" to search for commands related to "word"... + Reading symbols from u-boot... + Remote debugging using :1234 + 0xbfc00000 in ?? () + (gdb) c + Continuing. diff --git a/roms/u-boot/doc/board/emulation/qemu-ppce500.rst b/roms/u-boot/doc/board/emulation/qemu-ppce500.rst new file mode 100644 index 000000000..5de0aaf55 --- /dev/null +++ b/roms/u-boot/doc/board/emulation/qemu-ppce500.rst @@ -0,0 +1,93 @@ +.. SPDX-License-Identifier: GPL-2.0+ +.. Copyright (C) 2021, Bin Meng <bmeng.cn@gmail.com> + +QEMU PPC E500 +============= + +QEMU for PPC supports a special 'ppce500' machine designed for emulation and +virtualization purposes. This document describes how to run U-Boot under it. + +The QEMU ppce500 machine models a generic PowerPC E500 virtual machine with +support for the VirtIO standard networking device connected to the built-in +PCI host controller. Some common devices in the CCSBAR space are modeled, +including MPIC, 16550A UART devices, GPIO, I2C and PCI host controller with +MSI delivery to MPIC. It uses device-tree to pass configuration information +to guest software. + +Building U-Boot +--------------- +Set the CROSS_COMPILE environment variable as usual, and run:: + + $ make qemu-ppce500_defconfig + $ make + +Running U-Boot +-------------- +The minimal QEMU command line to get U-Boot up and running is:: + + $ qemu-system-ppc -nographic -machine ppce500 -bios u-boot + +You can also run U-Boot using 'qemu-system-ppc64':: + + $ qemu-system-ppc64 -nographic -machine ppce500 -bios u-boot + +The commands above create a target with 128 MiB memory by default. A freely +configurable amount of RAM can be created via the '-m' parameter. For example, +'-m 2G' creates 2 GiB memory for the target, and the memory node in the +embedded DTB created by QEMU reflects the new setting. + +Both qemu-system-ppc and qemu-system-ppc64 provide emulation for the following +32-bit PowerPC CPUs: + +* e500v2 +* e500mc + +Additionally qemu-system-ppc64 provides support for the following 64-bit CPUs: + +* e5500 +* e6500 + +The CPU type can be specified via the '-cpu' command line. If not specified, +it creates a machine with e500v2 core. The following example shows an e6500 +based machine creation:: + + $ qemu-system-ppc64 -nographic -machine ppce500 -cpu e6500 -bios u-boot + +When U-Boot boots, you will notice the following:: + + CPU: Unknown, Version: 0.0, (0x00000000) + Core: e6500, Version: 2.0, (0x80400020) + +This is because we only specified a core name to QEMU and it does not have a +meaningful SVR value which represents an actual SoC that integrates such core. +You can specify a real world SoC device that QEMU has built-in support but all +these SoCs are e500v2 based MPC85xx series, hence you cannot test anything +built for P4080 (e500mc), P5020 (e5500) and T2080 (e6500). + +By default a VirtIO standard PCI networking device is connected as an ethernet +interface at PCI address 0.1.0, but we can switch that to an e1000 NIC by:: + + $ qemu-system-ppc -nographic -machine ppce500 -bios u-boot \ + -nic tap,ifname=tap0,script=no,downscript=no,model=e1000 + +The QEMU ppce500 machine can also dynamically instantiate an eTSEC device if +"-device eTSEC" is given to QEMU:: + + -netdev tap,ifname=tap0,script=no,downscript=no,id=net0 -device eTSEC,netdev=net0 + +VirtIO BLK driver is also enabled to support booting from a disk image where +a kernel image is stored. Append the following to QEMU:: + + -drive file=disk.img,format=raw,id=disk0 -device virtio-blk-pci,drive=disk0 + +Pericom pt7c4338 RTC is supported so we can use the 'date' command:: + + => date + Date: 2021-02-18 (Thursday) Time: 15:33:20 + +Additionally, 'poweroff' command is supported to shut down the QEMU session:: + + => poweroff + poweroff ... + +These have been tested in QEMU 5.2.0. diff --git a/roms/u-boot/doc/board/emulation/qemu-riscv.rst b/roms/u-boot/doc/board/emulation/qemu-riscv.rst new file mode 100644 index 000000000..4b8e104a2 --- /dev/null +++ b/roms/u-boot/doc/board/emulation/qemu-riscv.rst @@ -0,0 +1,115 @@ +.. SPDX-License-Identifier: GPL-2.0+ +.. Copyright (C) 2018, Bin Meng <bmeng.cn@gmail.com> + +QEMU RISC-V +=========== + +QEMU for RISC-V supports a special 'virt' machine designed for emulation and +virtualization purposes. This document describes how to run U-Boot under it. +Both 32-bit and 64-bit targets are supported, running in either machine or +supervisor mode. + +The QEMU virt machine models a generic RISC-V virtual machine with support for +the VirtIO standard networking and block storage devices. It has CLINT, PLIC, +16550A UART devices in addition to VirtIO and it also uses device-tree to pass +configuration information to guest software. It implements RISC-V privileged +architecture spec v1.10. + +Building U-Boot +--------------- +Set the CROSS_COMPILE environment variable as usual, and run: + +- For 32-bit RISC-V:: + + make qemu-riscv32_defconfig + make + +- For 64-bit RISC-V:: + + make qemu-riscv64_defconfig + make + +This will compile U-Boot for machine mode. To build supervisor mode binaries, +use the configurations qemu-riscv32_smode_defconfig and +qemu-riscv64_smode_defconfig instead. Note that U-Boot running in supervisor +mode requires a supervisor binary interface (SBI), such as RISC-V OpenSBI. + +Running U-Boot +-------------- +The minimal QEMU command line to get U-Boot up and running is: + +- For 32-bit RISC-V:: + + qemu-system-riscv32 -nographic -machine virt -bios u-boot + +- For 64-bit RISC-V:: + + qemu-system-riscv64 -nographic -machine virt -bios u-boot + +The commands above create targets with 128MiB memory by default. +A freely configurable amount of RAM can be created via the '-m' +parameter. For example, '-m 2G' creates 2GiB memory for the target, +and the memory node in the embedded DTB created by QEMU reflects +the new setting. + +For instructions on how to run U-Boot in supervisor mode on QEMU +with OpenSBI, see the documentation available with OpenSBI: +https://github.com/riscv/opensbi/blob/master/docs/platform/qemu_virt.md + +These have been tested in QEMU 5.0.0. + +Running U-Boot SPL +------------------ +In the default SPL configuration, U-Boot SPL starts in machine mode. U-Boot +proper and OpenSBI (FW_DYNAMIC firmware) are bundled as FIT image and made +available to U-Boot SPL. Both are then loaded by U-Boot SPL and the location +of U-Boot proper is passed to OpenSBI. After initialization, U-Boot proper is +started in supervisor mode by OpenSBI. + +OpenSBI must be compiled before compiling U-Boot. Version 0.4 and higher is +supported by U-Boot. Clone the OpenSBI repository and run the following command. + +.. code-block:: console + + git clone https://github.com/riscv/opensbi.git + cd opensbi + make PLATFORM=generic + +See the OpenSBI documentation for full details: +https://github.com/riscv/opensbi/blob/master/docs/platform/qemu_virt.md + +To make the FW_DYNAMIC binary (build/platform/qemu/virt/firmware/fw_dynamic.bin) +available to U-Boot, either copy it into the U-Boot root directory or specify +its location with the OPENSBI environment variable. Afterwards, compile U-Boot +with the following commands. + +- For 32-bit RISC-V:: + + make qemu-riscv32_spl_defconfig + make + +- For 64-bit RISC-V:: + + make qemu-riscv64_spl_defconfig + make + +The minimal QEMU commands to run U-Boot SPL in both 32-bit and 64-bit +configurations are: + +- For 32-bit RISC-V:: + + qemu-system-riscv32 -nographic -machine virt -bios spl/u-boot-spl \ + -device loader,file=u-boot.itb,addr=0x80200000 + +- For 64-bit RISC-V:: + + qemu-system-riscv64 -nographic -machine virt -bios spl/u-boot-spl \ + -device loader,file=u-boot.itb,addr=0x80200000 + +An attached disk can be emulated by adding:: + + -device ich9-ahci,id=ahci \ + -drive if=none,file=riscv64.img,format=raw,id=mydisk \ + -device ide-hd,drive=mydisk,bus=ahci.0 + +You will have to run 'scsi scan' to use it. diff --git a/roms/u-boot/doc/board/emulation/qemu-x86.rst b/roms/u-boot/doc/board/emulation/qemu-x86.rst new file mode 100644 index 000000000..db842f2ec --- /dev/null +++ b/roms/u-boot/doc/board/emulation/qemu-x86.rst @@ -0,0 +1,118 @@ +.. SPDX-License-Identifier: GPL-2.0+ +.. sectionauthor:: Bin Meng <bmeng.cn@gmail.com> + +QEMU x86 +======== + +Build instructions for bare mode +-------------------------------- + +To build u-boot.rom for QEMU x86 targets, just simply run:: + + $ make qemu-x86_defconfig (for 32-bit) + $ make qemu-x86_64_defconfig (for 64-bit) + $ make all + +Note this default configuration will build a U-Boot for the QEMU x86 i440FX +board. To build a U-Boot against QEMU x86 Q35 board, you can change the build +configuration during the 'make menuconfig' process like below:: + + Device Tree Control ---> + ... + (qemu-x86_q35) Default Device Tree for DT control + +Test with QEMU for bare mode +---------------------------- + +QEMU is a fancy emulator that can enable us to test U-Boot without access to +a real x86 board. Please make sure your QEMU version is 2.3.0 or above test +U-Boot. To launch QEMU with u-boot.rom, call QEMU as follows:: + + $ qemu-system-i386 -nographic -bios path/to/u-boot.rom + +This will instantiate an emulated x86 board with i440FX and PIIX chipset. QEMU +also supports emulating an x86 board with Q35 and ICH9 based chipset, which is +also supported by U-Boot. To instantiate such a machine, call QEMU with:: + + $ qemu-system-i386 -nographic -bios path/to/u-boot.rom -M q35 + +Note by default QEMU instantiated boards only have 128 MiB system memory. But +it is enough to have U-Boot boot and function correctly. You can increase the +system memory by pass '-m' parameter to QEMU if you want more memory:: + + $ qemu-system-i386 -nographic -bios path/to/u-boot.rom -m 1024 + +This creates a board with 1 GiB system memory. Currently U-Boot for QEMU only +supports 3 GiB maximum system memory and reserves the last 1 GiB address space +for PCI device memory-mapped I/O and other stuff, so the maximum value of '-m' +would be 3072. + +QEMU emulates a graphic card which U-Boot supports. Removing '-nographic' will +show QEMU's VGA console window. Note this will disable QEMU's serial output. +If you want to check both consoles, use '-serial stdio'. + +Multicore is also supported by QEMU via '-smp n' where n is the number of cores +to instantiate. Note, the maximum supported CPU number in QEMU is 255. + +U-Boot uses 'distro_bootcmd' by default when booting on x86 QEMU. This tries to +load a boot script, kernel, and ramdisk from several different interfaces. For +the default boot order, see 'qemu-x86.h'. For more information, see +'README.distro'. Most Linux distros can be booted by writing a uboot script. +For example, Debian (stretch) can be booted by creating a script file named +'boot.txt' with the contents:: + + setenv bootargs root=/dev/sda1 ro + load ${devtype} ${devnum}:${distro_bootpart} ${kernel_addr_r} /vmlinuz + load ${devtype} ${devnum}:${distro_bootpart} ${ramdisk_addr_r} /initrd.img + zboot ${kernel_addr_r} - ${ramdisk_addr_r} ${filesize} + +Then compile and install it with:: + + $ apt install u-boot-tools && \ + mkimage -T script -C none -n "Boot script" -d boot.txt /boot/boot.scr + +The fw_cfg interface in QEMU also provides information about kernel data, +initrd, command-line arguments and more. U-Boot supports directly accessing +these informtion from fw_cfg interface, which saves the time of loading them +from hard disk or network again, through emulated devices. To use it , simply +providing them in QEMU command line:: + + $ qemu-system-i386 -nographic -bios path/to/u-boot.rom -m 1024 \ + -kernel /path/to/bzImage -append 'root=/dev/ram console=ttyS0' \ + -initrd /path/to/initrd -smp 8 + +Note: -initrd and -smp are both optional + +Then start QEMU, in U-Boot command line use the following U-Boot command to +setup kernel:: + + => qfw + qfw - QEMU firmware interface + + Usage: + qfw <command> + - list : print firmware(s) currently loaded + - cpus : print online cpu number + - load <kernel addr> <initrd addr> : load kernel and initrd (if any) and setup for zboot + + => qfw load + loading kernel to address 01000000 size 5d9d30 initrd 04000000 size 1b1ab50 + +Here the kernel (bzImage) is loaded to 01000000 and initrd is to 04000000. Then, +'zboot' can be used to boot the kernel:: + + => zboot 01000000 - 04000000 1b1ab50 + +To run 64-bit U-Boot, qemu-system-x86_64 should be used instead, e.g.:: + + $ qemu-system-x86_64 -nographic -bios path/to/u-boot.rom + +A specific CPU can be specified via the '-cpu' parameter but please make +sure the specified CPU supports 64-bit like '-cpu core2duo'. Conversely +'-cpu pentium' won't work for obvious reasons that the processor only +supports 32-bit. + +Note 64-bit support is very preliminary at this point. Lots of features +are missing in the 64-bit world. One notable feature is the VGA console +support which is currently missing, so that you must specify '-nographic' +to get 64-bit U-Boot up and running. diff --git a/roms/u-boot/doc/board/emulation/qemu_capsule_update.rst b/roms/u-boot/doc/board/emulation/qemu_capsule_update.rst new file mode 100644 index 000000000..33ce4bcd3 --- /dev/null +++ b/roms/u-boot/doc/board/emulation/qemu_capsule_update.rst @@ -0,0 +1,210 @@ +.. SPDX-License-Identifier: GPL-2.0+ +.. Copyright (C) 2020, Linaro Limited + +Enabling UEFI Capsule Update feature +------------------------------------ + +Support has been added for the UEFI capsule update feature which +enables updating the U-Boot image using the UEFI firmware management +protocol (fmp). The capsules are not passed to the firmware through +the UpdateCapsule runtime service. Instead, capsule-on-disk +functionality is used for fetching the capsule from the EFI System +Partition (ESP) by placing the capsule file under the +\EFI\UpdateCapsule directory. + +Currently, support has been added on the QEMU ARM64 virt platform for +updating the U-Boot binary as a raw image when the platform is booted +in non-secure mode, i.e. with CONFIG_TFABOOT disabled. For this +configuration, the QEMU platform needs to be booted with +'secure=off'. The U-Boot binary placed on the first bank of the NOR +flash at offset 0x0. The U-Boot environment is placed on the second +NOR flash bank at offset 0x4000000. + +The capsule update feature is enabled with the following configuration +settings:: + + CONFIG_MTD=y + CONFIG_FLASH_CFI_MTD=y + CONFIG_CMD_MTDPARTS=y + CONFIG_CMD_DFU=y + CONFIG_DFU_MTD=y + CONFIG_PCI_INIT_R=y + CONFIG_EFI_CAPSULE_ON_DISK=y + CONFIG_EFI_CAPSULE_FIRMWARE_MANAGEMENT=y + CONFIG_EFI_CAPSULE_FIRMWARE=y + CONFIG_EFI_CAPSULE_FIRMWARE_RAW=y + CONFIG_EFI_CAPSULE_FMP_HEADER=y + +In addition, the following config needs to be disabled(QEMU ARM specific):: + + CONFIG_TFABOOT + +The capsule file can be generated by using the GenerateCapsule.py +script in EDKII:: + + $ ./BaseTools/BinWrappers/PosixLike/GenerateCapsule -e -o \ + <capsule_file_name> --fw-version <val> --lsv <val> --guid \ + e2bb9c06-70e9-4b14-97a3-5a7913176e3f --verbose --update-image-index \ + <val> --verbose <u-boot.bin> + +The above is a wrapper script(GenerateCapsule) which eventually calls +the actual GenerateCapsule.py script. + +As per the UEFI specification, the capsule file needs to be placed on +the EFI System Partition, under the \EFI\UpdateCapsule directory. The +EFI System Partition can be a virtio-blk-device. + +Before initiating the firmware update, the efi variables BootNext, +BootXXXX and OsIndications need to be set. The BootXXXX variable needs +to be pointing to the EFI System Partition which contains the capsule +file. The BootNext, BootXXXX and OsIndications variables can be set +using the following commands:: + + => efidebug boot add -b 0 Boot0000 virtio 0:1 <capsule_file_name> + => efidebug boot next 0 + => setenv -e -nv -bs -rt -v OsIndications =0x04 + => saveenv + +Finally, the capsule update can be initiated with the following +command:: + + => efidebug capsule disk-update + +The updated U-Boot image will be booted on subsequent boot. + +Enabling Capsule Authentication +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The UEFI specification defines a way of authenticating the capsule to +be updated by verifying the capsule signature. The capsule signature +is computed and prepended to the capsule payload at the time of +capsule generation. This signature is then verified by using the +public key stored as part of the X509 certificate. This certificate is +in the form of an efi signature list (esl) file, which is embedded as +part of the platform's device tree blob using the mkeficapsule +utility. + +On the QEMU virt platforms, the device-tree is generated on the fly +based on the devices configured. This device tree is then passed on to +the various software components booting on the platform, including +U-Boot. Therefore, on the QEMU virt platform, the signatute is +embedded on an overlay. This overlay is then applied at runtime to the +base platform device-tree. Steps needed for embedding the esl file in +the overlay are highlighted below. + +The capsule authentication feature can be enabled through the +following config, in addition to the configs listed above for capsule +update:: + + CONFIG_EFI_CAPSULE_AUTHENTICATE=y + +The public and private keys used for the signing process are generated +and used by the steps highlighted below:: + + 1. Install utility commands on your host + * OPENSSL + * efitools + + 2. Create signing keys and certificate files on your host + + $ openssl req -x509 -sha256 -newkey rsa:2048 -subj /CN=CRT/ \ + -keyout CRT.key -out CRT.crt -nodes -days 365 + $ cert-to-efi-sig-list CRT.crt CRT.esl + + $ openssl x509 -in CRT.crt -out CRT.cer -outform DER + $ openssl x509 -inform DER -in CRT.cer -outform PEM -out CRT.pub.pem + + $ openssl pkcs12 -export -out CRT.pfx -inkey CRT.key -in CRT.crt + $ openssl pkcs12 -in CRT.pfx -nodes -out CRT.pem + +The capsule file can be generated by using the GenerateCapsule.py +script in EDKII:: + + $ ./BaseTools/BinWrappers/PosixLike/GenerateCapsule -e -o \ + <capsule_file_name> --monotonic-count <val> --fw-version \ + <val> --lsv <val> --guid \ + e2bb9c06-70e9-4b14-97a3-5a7913176e3f --verbose \ + --update-image-index <val> --signer-private-cert \ + /path/to/CRT.pem --trusted-public-cert \ + /path/to/CRT.pub.pem --other-public-cert /path/to/CRT.pub.pem \ + <u-boot.bin> + +Place the capsule generated in the above step on the EFI System +Partition under the EFI/UpdateCapsule directory + +For embedding the public key certificate, the following steps need to +be followed:: + + 1. Generate a skeleton overlay dts file, with a single fragment + node and an empty __overlay__ node + + A typical skeleton overlay file will look like this + + /dts-v1/; + /plugin/; + + / { + fragment@0 { + target-path = "/"; + __overlay__ { + }; + }; + }; + + + 2. Convert the dts to a corresponding dtb with the following + command + ./scripts/dtc/dtc -@ -I dts -O dtb -o <ov_dtb_file_name> \ + <dts_file> + + 3. Run the dtb file generated above through the mkeficapsule tool + in U-Boot + ./tools/mkeficapsule -O <pub_key.esl> -D <ov_dtb> + +Running the above command results in the creation of a 'signature' +node in the dtb, under which the public key is stored as a +'capsule-key' property. The '-O' option is to be used since the +public key certificate(esl) file is being embedded in an overlay. + +The dtb file embedded with the certificate is now to be placed on an +EFI System Partition. This would then be loaded and "merged" with the +base platform flattened device-tree(dtb) at runtime. + +Build U-Boot with the following steps(QEMU ARM64):: + + $ make qemu_arm64_defconfig + $ make menuconfig + Disable CONFIG_TFABOOT + Enable CONFIG_EFI_CAPSULE_AUTHENTICATE + Enable all configs needed for capsule update(listed above) + $ make all + +Boot the platform and perform the following steps on the U-Boot +command line:: + + 1. Enable capsule authentication by setting the following env + variable + + => setenv capsule_authentication_enabled 1 + => saveenv + + 2. Load the overlay dtb to memory and merge it with the base fdt + + => fatload virtio 0:1 <$fdtovaddr> EFI/<ov_dtb_file> + => fdt addr $fdtcontroladdr + => fdt resize <size_of_ov_dtb_file> + => fdt apply <$fdtovaddr> + + 3. Set the following environment and UEFI boot variables + + => setenv -e -nv -bs -rt -v OsIndications =0x04 + => efidebug boot add -b 0 Boot0000 virtio 0:1 <capsule_file_name> + => efidebug boot next 0 + => saveenv + + 4. Finally, the capsule update can be initiated with the following + command + + => efidebug capsule disk-update + +On subsequent reboot, the platform should boot the updated U-Boot binary. diff --git a/roms/u-boot/doc/board/freescale/b4860qds.rst b/roms/u-boot/doc/board/freescale/b4860qds.rst new file mode 100644 index 000000000..de14d857b --- /dev/null +++ b/roms/u-boot/doc/board/freescale/b4860qds.rst @@ -0,0 +1,453 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +B4860QDS +======== + +The B4860QDS is a Freescale reference board that hosts the B4860 SoC +(and variants). + +B4860 Overview +-------------- +The B4860 QorIQ Qonverge device is a Freescale high-end, multicore SoC based on +StarCore and Power Architecture® cores. It targets the broadband wireless +infrastructure and builds upon the proven success of the existing multicore +DSPs and Power CPUs. It is designed to bolster the rapidly changing and +expanding wireless markets, such as 3GLTE (FDD and TDD), LTE-Advanced, and UMTS. + +The B4860 is a highly-integrated StarCore and Power Architecture processor that +contains: + +* Six fully-programmable StarCore SC3900 FVP subsystems, divided into three + clusters-each core runs up to 1.2 GHz, with an architecture highly optimized + for wireless base station applications +* Four dual-thread e6500 Power Architecture processors organized in one + cluster-each core runs up to 1.8 GHz +* Two DDR3/3L controllers for high-speed, industry-standard memory interface + each runs at up to 1866.67 MHz +* MAPLE-B3 hardware acceleration-for forward error correction schemes including + Turbo or Viterbi decoding, Turbo encoding and rate matching, MIMO MMSE + equalization scheme, matrix operations, CRC insertion and check, DFT/iDFT and + FFT/iFFT calculations, PUSCH/PDSCH acceleration, and UMTS chip rate + acceleration +* CoreNet fabric that fully supports coherency using MESI protocol between the + e6500 cores, SC3900 FVP cores, memories and external interfaces. + CoreNet fabric interconnect runs at 667 MHz and supports coherent and + non-coherent out of order transactions with prioritization and bandwidth + allocation amongst CoreNet endpoints. +* Data Path Acceleration Architecture, which includes the following: + + * Frame Manager (FMan), which supports in-line packet parsing and general + classification to enable policing and QoS-based packet distribution + * Queue Manager (QMan) and Buffer Manager (BMan), which allow offloading + of queue management, task management, load distribution, flow ordering, + buffer management, and allocation tasks from the cores + * Security engine (SEC 5.3)-crypto-acceleration for protocols such as + IPsec, SSL, and 802.16 + * RapidIO manager (RMAN) - Support SRIO types 8, 9, 10, and 11 (inbound + and outbound). Supports types 5, 6 (outbound only) + +* Large internal cache memory with snooping and stashing capabilities for + bandwidth saving and high utilization of processor elements. The 9856-Kbyte + internal memory space includes the following: + + * 32 Kbyte L1 ICache per e6500/SC3900 core + * 32 Kbyte L1 DCache per e6500/SC3900 core + * 2048 Kbyte unified L2 cache for each SC3900 FVP cluster + * 2048 Kbyte unified L2 cache for the e6500 cluster + * Two 512 Kbyte shared L3 CoreNet platform caches (CPC) + +* Sixteen 10-GHz SerDes lanes serving: + + * Two Serial RapidIO interfaces + * Each supports up to 4 lanes and a total of up to 8 lanes + +* Up to 8-lanes Common Public Radio Interface (CPRI) controller for + glue-less antenna connection +* Two 10-Gbit Ethernet controllers (10GEC) +* Six 1G/2.5-Gbit Ethernet controllers for network communications +* PCI Express controller +* Debug (Aurora) +* Two OCeaN DMAs +* Various system peripherals +* 182 32-bit timers + +B4860QDS Overview +----------------- +- DDRC1: Ten separate DDR3 parts of 16-bit to support 72-bit (ECC) at 1866MT/s, + ECC, 4 GB of memory in two ranks of 2 GB. +- DDRC2: Five separate DDR3 parts of 16-bit to support 72-bit (ECC) at 1866MT/s, + ECC, 2 GB of memory. Single rank. +- SerDes 1 multiplexing: Two Vitesse (transmit and receive path) cross-point + 16x16 switch VSC3316 +- SerDes 2 multiplexing: Two Vitesse (transmit and receive path) cross-point + 8x8 switch VSC3308 +- USB 2.0 ULPI PHY USB3315 by SMSC supports USB port in host mode. + B4860 UART port is available over USB-to-UART translator USB2SER or over + RS232 flat cable. +- A Vitesse dual SGMII phy VSC8662 links the B4860 SGMII lines to 2xRJ-45 + copper connectors for Stand-alone mode and to the 1000Base-X over AMC + MicroTCA connector ports 0 and 2 for AMC mode. +- The B4860 configuration may be loaded from nine bits coded reset configuration + reset source. The RCW source is set by appropriate DIP-switches. +- 16-bit NOR Flash / PROMJet +- QIXIS 8-bit NOR Flash Emulator +- 8-bit NAND Flash +- 24-bit SPI Flash +- Long address I2C EEPROM +- Available debug interfaces are: + + - On-board eCWTAP controller with ETH and USB I/F + - JTAG/COP 16-pin header for any external TAP controller + - External JTAG source over AMC to support B2B configuration + - 70-pin Aurora debug connector + +- QIXIS (FPGA) logic: + - 2 KB internal memory space including + +- IDT840NT4 clock synthesizer provides B4860 essential clocks : SYSCLK, + DDRCLK1,2 and RTCCLK. +- Two 8T49N222A SerDes ref clock devices support two SerDes port clock + frequency - total four refclk, including CPRI clock scheme. + + +B4420 Personality +----------------- + +B4420 is a reduced personality of B4860 with less core/clusters(both SC3900 +and e6500), less DDR controllers, less serdes lanes, less SGMII interfaces +and reduced target frequencies. + +Key differences between B4860 and B4420 +--------------------------------------- + +B4420 has: + +1. Less e6500 cores: 1 cluster with 2 e6500 cores +2. Less SC3900 cores/clusters: 1 cluster with 2 SC3900 cores per cluster +3. Single DDRC +4. 2X 4 lane serdes +5. 3 SGMII interfaces +6. no sRIO +7. no 10G + +B4860QDS Default Settings +------------------------- + +Switch Settings +^^^^^^^^^^^^^^^ + +.. code-block:: none + + SW1 OFF [0] OFF [0] OFF [0] OFF [0] OFF [0] OFF [0] OFF [0] OFF [0] + SW2 ON ON ON ON ON ON OFF OFF + SW3 OFF OFF OFF ON OFF OFF ON OFF + SW5 OFF OFF OFF OFF OFF OFF ON ON + +Note: + +- PCIe slots modes: All the PCIe devices work as Root Complex. +- Boot location: NOR flash. + +SysClk/Core(e6500)/CCB/DDR/FMan/DDRCLK/StarCore/CPRI-Maple/eTVPE-Maple/ULB-Maple +66MHz/1.6GHz/667MHz/1.6GHz data rate/667MHz/133MHz/1200MHz/500MHz/800MHz/667MHz + +NAND boot:: + + SW1 [1.1] = 0 + SW2 [1.1] = 1 + SW3 [1:4] = 0001 + +NOR boot:: + + SW1 [1.1] = 1 + SW2 [1.1] = 0 + SW3 [1:4] = 1000 + +B4420QDS Default Settings +------------------------- + +Switch Settings +^^^^^^^^^^^^^^^ + +.. code-block:: none + + SW1 OFF[0] OFF [0] OFF [0] OFF [0] OFF [0] OFF [0] OFF [0] OFF [0] + SW2 ON OFF ON OFF ON ON OFF OFF + SW3 OFF OFF OFF ON OFF OFF ON OFF + SW5 OFF OFF OFF OFF OFF OFF ON ON + +Note: + +- PCIe slots modes: All the PCIe devices work as Root Complex. +- Boot location: NOR flash. + +SysClk/Core(e6500)/CCB/DDR/FMan/DDRCLK/StarCore/CPRI-Maple/eTVPE-Maple/ULB-Maple +66MHz/1.6GHz/667MHz/1.6GHz data rate/667MHz/133MHz/1200MHz/500MHz/800MHz/667MHz + +NAND boot:: + + SW1 [1.1] = 0 + SW2 [1.1] = 1 + SW3 [1:4] = 0001 + +NOR boot:: + + SW1 [1.1] = 1 + SW2 [1.1] = 0 + SW3 [1:4] = 1000 + +Memory map on B4860QDS +---------------------- +The addresses in brackets are physical addresses. + +============= ============= =============== ======= +Start Address End Address Description Size +============= ============= =============== ======= +0xF_FFDF_1000 0xF_FFFF_FFFF Free 2 MB +0xF_FFDF_0000 0xF_FFDF_0FFF IFC - FPGA 4 KB +0xF_FF81_0000 0xF_FFDE_FFFF Free 5 MB +0xF_FF80_0000 0xF_FF80_FFFF IFC NAND Flash 64 KB +0xF_FF00_0000 0xF_FF7F_FFFF Free 8 MB +0xF_FE00_0000 0xF_FEFF_FFFF CCSRBAR 16 MB +0xF_F801_0000 0xF_FDFF_FFFF Free 95 MB +0xF_F800_0000 0xF_F800_FFFF PCIe I/O Space 64 KB +0xF_F600_0000 0xF_F7FF_FFFF QMAN s/w portal 32 MB +0xF_F400_0000 0xF_F5FF_FFFF BMAN s/w portal 32 MB +0xF_F000_0000 0xF_F3FF_FFFF Free 64 MB +0xF_E800_0000 0xF_EFFF_FFFF IFC NOR Flash 128 MB +0xF_E000_0000 0xF_E7FF_FFFF Promjet 128 MB +0xF_A0C0_0000 0xF_DFFF_FFFF Free 1012 MB +0xF_A000_0000 0xF_A0BF_FFFF MAPLE0/1/2 12 MB +0xF_0040_0000 0xF_9FFF_FFFF Free 12 GB +0xF_0000_0000 0xF_01FF_FFFF DCSR 32 MB +0xC_4000_0000 0xE_FFFF_FFFF Free 11 GB +0xC_3000_0000 0xC_3FFF_FFFF sRIO-2 I/O 256 MB +0xC_2000_0000 0xC_2FFF_FFFF sRIO-1 I/O 256 MB +0xC_0000_0000 0xC_1FFF_FFFF PCIe Mem Space 512 MB +0x1_0000_0000 0xB_FFFF_FFFF Free 44 GB +0x0_8000_0000 0x0_FFFF_FFFF DDRC1 2 GB +0x0_0000_0000 0x0_7FFF_FFFF DDRC2 2 GB +============= ============= =============== ======= + +Memory map on B4420QDS +---------------------- +The addresses in brackets are physical addresses. + +============= ============= =============== ======= +Start Address End Address Description Size +============= ============= =============== ======= +0xF_FFDF_1000 0xF_FFFF_FFFF Free 2 MB +0xF_FFDF_0000 0xF_FFDF_0FFF IFC - FPGA 4 KB +0xF_FF81_0000 0xF_FFDE_FFFF Free 5 MB +0xF_FF80_0000 0xF_FF80_FFFF IFC NAND Flash 64 KB +0xF_FF00_0000 0xF_FF7F_FFFF Free 8 MB +0xF_FE00_0000 0xF_FEFF_FFFF CCSRBAR 16 MB +0xF_F801_0000 0xF_FDFF_FFFF Free 95 MB +0xF_F800_0000 0xF_F800_FFFF PCIe I/O Space 64 KB +0xF_F600_0000 0xF_F7FF_FFFF QMAN s/w portal 32 MB +0xF_F400_0000 0xF_F5FF_FFFF BMAN s/w portal 32 MB +0xF_F000_0000 0xF_F3FF_FFFF Free 64 MB +0xF_E800_0000 0xF_EFFF_FFFF IFC NOR Flash 128 MB +0xF_E000_0000 0xF_E7FF_FFFF Promjet 128 MB +0xF_A0C0_0000 0xF_DFFF_FFFF Free 1012 MB +0xF_A000_0000 0xF_A0BF_FFFF MAPLE0/1/2 12 MB +0xF_0040_0000 0xF_9FFF_FFFF Free 12 GB +0xF_0000_0000 0xF_01FF_FFFF DCSR 32 MB +0xC_4000_0000 0xE_FFFF_FFFF Free 11 GB +0xC_3000_0000 0xC_3FFF_FFFF sRIO-2 I/O 256 MB +0xC_2000_0000 0xC_2FFF_FFFF sRIO-1 I/O 256 MB +0xC_0000_0000 0xC_1FFF_FFFF PCIe Mem Space 512 MB +0x1_0000_0000 0xB_FFFF_FFFF Free 44 GB +0x0_0000_0000 0x0_FFFF_FFFF DDRC1 4 GB +============= ============= =============== ======= + +NOR Flash memory Map on B4860 and B4420QDS +------------------------------------------ + +============= ============= ============================== ========= + Start End Definition Size +============= ============= ============================== ========= +0xEFF40000 0xEFFFFFFF U-Boot (current bank) 768KB +0xEFF20000 0xEFF3FFFF U-Boot env (current bank) 128KB +0xEFF00000 0xEFF1FFFF FMAN Ucode (current bank) 128KB +0xEF300000 0xEFEFFFFF rootfs (alternate bank) 12MB +0xEE800000 0xEE8FFFFF device tree (alternate bank) 1MB +0xEE020000 0xEE6FFFFF Linux.uImage (alternate bank) 6MB+896KB +0xEE000000 0xEE01FFFF RCW (alternate bank) 128KB +0xEDF40000 0xEDFFFFFF U-Boot (alternate bank) 768KB +0xEDF20000 0xEDF3FFFF U-Boot env (alternate bank) 128KB +0xEDF00000 0xEDF1FFFF FMAN ucode (alternate bank) 128KB +0xED300000 0xEDEFFFFF rootfs (current bank) 12MB +0xEC800000 0xEC8FFFFF device tree (current bank) 1MB +0xEC020000 0xEC6FFFFF Linux.uImage (current bank) 6MB+896KB +0xEC000000 0xEC01FFFF RCW (current bank) 128KB +============= ============= ============================== ========= + +Various Software configurations/environment variables/commands +-------------------------------------------------------------- +The below commands apply to both B4860QDS and B4420QDS. + +U-Boot environment variable hwconfig +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The default hwconfig is: + +.. code-block:: none + + hwconfig=fsl_ddr:ctlr_intlv=null,bank_intlv=cs0_cs1;usb1:dr_mode=host,phy_type=ulpi + +Note: For USB gadget set "dr_mode=peripheral" + +FMAN Ucode versions +^^^^^^^^^^^^^^^^^^^ + +fsl_fman_ucode_B4860_106_3_6.bin + +Switching to alternate bank +^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Commands for switching to alternate bank. + +1. To change from vbank0 to vbank2 + +.. code-block:: none + + => qixis_reset altbank (it will boot using vbank2) + +2. To change from vbank2 to vbank0 + +.. code-block:: none + + => qixis reset (it will boot using vbank0) + +To change personality of board +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +For changing personality from B4860 to B4420 + +1. Boot from vbank0 +2. Flash vbank2 with b4420 rcw and U-Boot +3. Give following commands to uboot prompt + +.. code-block:: none + + => mw.b ffdf0040 0x30; + => mw.b ffdf0010 0x00; + => mw.b ffdf0062 0x02; + => mw.b ffdf0050 0x02; + => mw.b ffdf0010 0x30; + => reset + +Note: + +- Power off cycle will lead to default switch settings. +- 0xffdf0000 is the address of the QIXIS FPGA. + +Switching between NOR and NAND boot(RCW src changed from NOR <-> NAND) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +To change from NOR to NAND boot give following command on uboot prompt + +.. code-block:: none + + => mw.b ffdf0040 0x30 + => mw.b ffdf0010 0x00 + => mw.b 0xffdf0050 0x08 + => mw.b 0xffdf0060 0x82 + => mw.b ffdf0061 0x00 + => mw.b ffdf0010 0x30 + => reset + +To change from NAND to NOR boot give following command on uboot prompt: + +.. code-block:: none + + => mw.b ffdf0040 0x30 + => mw.b ffdf0010 0x00 + => mw.b 0xffdf0050 0x00(for vbank0) or (mw.b 0xffdf0050 0x02 for vbank2) + => mw.b 0xffdf0060 0x12 + => mw.b ffdf0061 0x01 + => mw.b ffdf0010 0x30 + => reset + +Note: + +- Power off cycle will lead to default switch settings. +- 0xffdf0000 is the address of the QIXIS FPGA. + +Ethernet interfaces for B4860QDS +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Serdes protocosl tested: +* 0x2a, 0x8d (serdes1, serdes2) [DEFAULT] +* 0x2a, 0xb2 (serdes1, serdes2) + +When using [DEFAULT] RCW, which including 2 * 1G SGMII on board and 2 * 1G +SGMII on SGMII riser card. + +Under U-Boot these network interfaces are recognized as:: + + FM1@DTSEC3, FM1@DTSEC4, FM1@DTSEC5 and FM1@DTSEC6. + +On Linux the interfaces are renamed as:: + + eth2 -> fm1-gb2 + eth3 -> fm1-gb3 + eth4 -> fm1-gb4 + eth5 -> fm1-gb5 + +RCW and Ethernet interfaces for B4420QDS +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Serdes protocosl tested: +* 0x18, 0x9e (serdes1, serdes2) + +Under U-Boot these network interfaces are recognized as:: + + FM1@DTSEC3, FM1@DTSEC4 and e1000#0. + +On Linux the interfaces are renamed as:: + + eth2 -> fm1-gb2 + eth3 -> fm1-gb3 + +NAND boot with 2 Stage boot loader +---------------------------------- +PBL initialise the internal SRAM and copy SPL(160KB) in SRAM. +SPL further initialise DDR using SPD and environment variables and copy +U-Boot(768 KB) from flash to DDR. +Finally SPL transer control to U-Boot for futher booting. + +SPL has following features: + - Executes within 256K + - No relocation required + +Run time view of SPL framework during boot: + ++----------------------------------------------+ +|Area | Address | ++----------------------------------------------+ +|Secure boot | 0xFFFC0000 (32KB) | +|headers | | ++----------------------------------------------+ +|GD, BD | 0xFFFC8000 (4KB) | ++----------------------------------------------+ +|ENV | 0xFFFC9000 (8KB) | ++----------------------------------------------+ +|HEAP | 0xFFFCB000 (30KB) | ++----------------------------------------------+ +|STACK | 0xFFFD8000 (22KB) | ++----------------------------------------------+ +|U-Boot SPL | 0xFFFD8000 (160KB) | ++----------------------------------------------+ + +NAND Flash memory Map on B4860 and B4420QDS +------------------------------------------- + +============= ============= ============================= ===== +Start End Definition Size +============= ============= ============================= ===== +0x000000 0x0FFFFF U-Boot 1MB +0x140000 0x15FFFF U-Boot env 128KB +0x1A0000 0x1BFFFF FMAN Ucode 128KB +============= ============= ============================= ===== diff --git a/roms/u-boot/doc/board/freescale/imx8mm_evk.rst b/roms/u-boot/doc/board/freescale/imx8mm_evk.rst new file mode 100644 index 000000000..7fd3d7256 --- /dev/null +++ b/roms/u-boot/doc/board/freescale/imx8mm_evk.rst @@ -0,0 +1,57 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +imx8mm_evk +========== + +U-Boot for the NXP i.MX8MM EVK board + +Quick Start +----------- + +- Build the ARM Trusted firmware binary +- Get ddr firmware +- Build U-Boot +- Boot + +Get and Build the ARM Trusted firmware +-------------------------------------- + +Note: builddir is U-Boot build directory (source directory for in-tree builds) +Get ATF from: https://source.codeaurora.org/external/imx/imx-atf +branch: imx_5.4.47_2.2.0 + +.. code-block:: bash + + $ make PLAT=imx8mm bl31 + $ cp build/imx8mm/release/bl31.bin $(builddir) + +Get the ddr firmware +-------------------- + +.. code-block:: bash + + $ wget https://www.nxp.com/lgfiles/NMG/MAD/YOCTO/firmware-imx-8.9.bin + $ chmod +x firmware-imx-8.9.bin + $ ./firmware-imx-8.9 + $ cp firmware-imx-8.9/firmware/ddr/synopsys/lpddr4*.bin $(builddir) + +Build U-Boot +------------ + +.. code-block:: bash + + $ export CROSS_COMPILE=aarch64-poky-linux- + $ make imx8mm_evk_defconfig + $ export ATF_LOAD_ADDR=0x920000 + $ make + +Burn the flash.bin to MicroSD card offset 33KB: + +.. code-block:: bash + + $sudo dd if=flash.bin of=/dev/sd[x] bs=1024 seek=33 conv=notrunc + $sudo dd if=u-boot.itb of=/dev/sdc bs=1024 seek=384 conv=sync + +Boot +---- +Set Boot switch to SD boot diff --git a/roms/u-boot/doc/board/freescale/imx8mn_evk.rst b/roms/u-boot/doc/board/freescale/imx8mn_evk.rst new file mode 100644 index 000000000..9fbb94703 --- /dev/null +++ b/roms/u-boot/doc/board/freescale/imx8mn_evk.rst @@ -0,0 +1,58 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +imx8mn_evk +========== + +U-Boot for the NXP i.MX8MN EVK board + +Quick Start +----------- + +- Build the ARM Trusted firmware binary +- Get firmware-imx package +- Build U-Boot +- Boot + +Get and Build the ARM Trusted firmware +-------------------------------------- + +Note: srctree is U-Boot source directory +Get ATF from: https://source.codeaurora.org/external/imx/imx-atf +branch: imx_5.4.47_2.2.0 + +.. code-block:: bash + + $ make PLAT=imx8mn bl31 + $ cp build/imx8mn/release/bl31.bin $(srctree) + +Get the ddr firmware +-------------------- + +.. code-block:: bash + + $ wget https://www.nxp.com/lgfiles/NMG/MAD/YOCTO/firmware-imx-8.9.bin + $ chmod +x firmware-imx-8.9.bin + $ ./firmware-imx-8.9 + $ cp firmware-imx-8.9/firmware/ddr/synopsys/ddr4*.bin $(srctree) + +Build U-Boot +------------ + +.. code-block:: bash + + $ export CROSS_COMPILE=aarch64-poky-linux- + $ make imx8mn_ddr4_evk_defconfig + $ export ATF_LOAD_ADDR=0x960000 + $ make + +Burn the flash.bin to MicroSD card offset 32KB: + +.. code-block:: bash + + $sudo dd if=flash.bin of=/dev/sd[x] bs=1024 seek=32 conv=notrunc + $sudo dd if=u-boot.itb of=/dev/sd[x] bs=1024 seek=384 conv=notrunc + +Boot +---- + +Set Boot switch to SD boot diff --git a/roms/u-boot/doc/board/freescale/imx8mp_evk.rst b/roms/u-boot/doc/board/freescale/imx8mp_evk.rst new file mode 100644 index 000000000..609a29f3e --- /dev/null +++ b/roms/u-boot/doc/board/freescale/imx8mp_evk.rst @@ -0,0 +1,61 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +imx8mp_evk +========== + +U-Boot for the NXP i.MX8MP EVK board + +Quick Start +----------- + +- Build the ARM Trusted firmware binary +- Get the firmware-imx package +- Build U-Boot +- Boot + +Get and Build the ARM Trusted firmware +-------------------------------------- + +Get ATF from: https://source.codeaurora.org/external/imx/imx-atf +branch: imx_5.4.70_2.3.0 + +.. code-block:: bash + + $ make PLAT=imx8mp bl31 + +Get the ddr firmware +-------------------- + +.. code-block:: bash + + $ wget https://www.nxp.com/lgfiles/NMG/MAD/YOCTO/firmware-imx-8.10.bin + $ chmod +x firmware-imx-8.10.bin + $ ./firmware-imx-8.10.bin + +Build U-Boot +------------ + +.. code-block:: bash + + $ export CROSS_COMPILE=aarch64-poky-linux- + $ make O=build imx8mp_evk_defconfig + $ cp ../imx-atf/build/imx8mp/release/bl31.bin ./build/bl31.bin + $ cp ../firmware-imx-8.10/firmware/ddr/synopsys/lpddr4_pmu_train_1d_dmem_202006.bin ./build/ + $ cp ../firmware-imx-8.10/firmware/ddr/synopsys/lpddr4_pmu_train_1d_imem_202006.bin ./build/ + $ cp ../firmware-imx-8.10/firmware/ddr/synopsys/lpddr4_pmu_train_2d_dmem_202006.bin ./build/ + $ cp ../firmware-imx-8.10/firmware/ddr/synopsys/lpddr4_pmu_train_2d_imem_202006.bin ./build/ + $ export ATF_LOAD_ADDR=0x970000 + $ make O=build + +Burn the flash.bin to the MicroSD card at offset 32KB: + +.. code-block:: bash + + $sudo dd if=build/flash.bin of=/dev/sd[x] bs=1K seek=32 conv=notrunc; sync + $sudo dd if=build/u-boot.itb of=/dev/sd[x] bs=1K seek=384 conv=notrunc; sync + +Boot +---- + +Set Boot switch to SD boot +Use /dev/ttyUSB2 for U-Boot console diff --git a/roms/u-boot/doc/board/freescale/imx8mq_evk.rst b/roms/u-boot/doc/board/freescale/imx8mq_evk.rst new file mode 100644 index 000000000..c269fdebe --- /dev/null +++ b/roms/u-boot/doc/board/freescale/imx8mq_evk.rst @@ -0,0 +1,56 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +imx8mq_evk +========== + +U-Boot for the NXP i.MX8MQ EVK board + +Quick Start +----------- + +- Build the ARM Trusted firmware binary +- Get ddr and hdmi fimware +- Build U-Boot +- Boot + +Get and Build the ARM Trusted firmware +-------------------------------------- + +Note: srctree is U-Boot source directory +Get ATF from: https://source.codeaurora.org/external/imx/imx-atf +branch: imx_5.4.47_2.2.0 + +.. code-block:: bash + + $ make PLAT=imx8mq bl31 + $ cp build/imx8mq/release/bl31.bin $(builddir) + +Get the ddr and hdmi firmware +----------------------------- + +.. code-block:: bash + + $ wget https://www.nxp.com/lgfiles/NMG/MAD/YOCTO/firmware-imx-8.9.bin + $ chmod +x firmware-imx-8.9.bin + $ ./firmware-imx-8.9.bin + $ cp firmware-imx-8.9/firmware/hdmi/cadence/signed_hdmi_imx8m.bin $(builddir) + $ cp firmware-imx-8.9/firmware/ddr/synopsys/lpddr4*.bin $(builddir) + +Build U-Boot +------------ + +.. code-block:: bash + + $ export CROSS_COMPILE=aarch64-poky-linux- + $ make imx8mq_evk_defconfig + $ make flash.bin + +Burn the flash.bin to MicroSD card offset 33KB: + +.. code-block:: bash + + $sudo dd if=flash.bin of=/dev/sd[x] bs=1024 seek=33 conv=notrunc + +Boot +---- +Set Boot switch SW801: 1100 and Bmode: 10 to boot from Micro SD. diff --git a/roms/u-boot/doc/board/freescale/imx8qxp_mek.rst b/roms/u-boot/doc/board/freescale/imx8qxp_mek.rst new file mode 100644 index 000000000..215627cfa --- /dev/null +++ b/roms/u-boot/doc/board/freescale/imx8qxp_mek.rst @@ -0,0 +1,66 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +imx8qxp_mek +=========== + +U-Boot for the NXP i.MX8QXP EVK board + +Quick Start +----------- + +- Build the ARM Trusted firmware binary +- Get scfw_tcm.bin and ahab-container.img +- Build U-Boot +- Flash the binary into the SD card +- Boot + +Get and Build the ARM Trusted firmware +-------------------------------------- + +.. code-block:: bash + + $ git clone https://source.codeaurora.org/external/imx/imx-atf + $ cd imx-atf/ + $ git checkout origin/imx_4.19.35_1.1.0 -b imx_4.19.35_1.1.0 + $ make PLAT=imx8qx bl31 + +Get scfw_tcm.bin and ahab-container.img +--------------------------------------- + +.. code-block:: bash + + $ wget https://www.nxp.com/lgfiles/NMG/MAD/YOCTO/imx-sc-firmware-1.2.7.1.bin + $ chmod +x imx-sc-firmware-1.2.7.1.bin + $ ./imx-sc-firmware-1.2.7.1.bin + $ wget https://www.nxp.com/lgfiles/NMG/MAD/YOCTO/imx-seco-2.3.1.bin + $ chmod +x imx-seco-2.3.1.bin + $ ./imx-seco-2.3.1.bin + +Copy the following binaries to U-Boot folder: + +.. code-block:: bash + + $ cp imx-atf/build/imx8qx/release/bl31.bin . + $ cp imx-seco-2.3.1/firmware/seco/mx8qx-ahab-container.img ./ahab-container.img + $ cp imx-sc-firmware-1.2.7.1/mx8qx-mek-scfw-tcm.bin . + +Build U-Boot +------------ + +.. code-block:: bash + + $ make imx8qxp_mek_defconfig + $ make flash.bin + +Flash the binary into the SD card +--------------------------------- + +Burn the flash.bin binary to SD card offset 32KB: + +.. code-block:: bash + + $ sudo dd if=flash.bin of=/dev/sd[x] bs=1024 seek=32 conv=notrunc + +Boot +---- +Set Boot switch SW2: 1100. diff --git a/roms/u-boot/doc/board/freescale/imxrt1020-evk.rst b/roms/u-boot/doc/board/freescale/imxrt1020-evk.rst new file mode 100644 index 000000000..267f80c51 --- /dev/null +++ b/roms/u-boot/doc/board/freescale/imxrt1020-evk.rst @@ -0,0 +1,41 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +imxrt1020-evk +============= + +How to use U-Boot on NXP i.MXRT1020 EVK +--------------------------------------- + +- Build U-Boot for i.MXRT1020 EVK: + +.. code-block:: bash + + $ make mrproper + $ make imxrt1020-evk_defconfig + $ make + +This will generate the SPL image called SPL and the u-boot.img. + +- Flash the SPL image into the micro SD card: + +.. code-block:: bash + + $sudo dd if=SPL of=/dev/sdX bs=1k seek=1 conv=notrunc; sync + +- Flash the u-boot.img image into the micro SD card: + +.. code-block:: bash + + $sudo dd if=u-boot.img of=/dev/sdX bs=1k seek=128 conv=notrunc; sync + +- Jumper settings:: + + SW8: 0 1 1 0 + +where 0 means bottom position and 1 means top position (from the +switch label numbers reference). + +- Connect the USB cable between the EVK and the PC for the console. + The USB console connector is the one close the ethernet connector + +- Insert the micro SD card in the board, power it up and U-Boot messages should come up. diff --git a/roms/u-boot/doc/board/freescale/imxrt1050-evk.rst b/roms/u-boot/doc/board/freescale/imxrt1050-evk.rst new file mode 100644 index 000000000..c1fb48f0c --- /dev/null +++ b/roms/u-boot/doc/board/freescale/imxrt1050-evk.rst @@ -0,0 +1,41 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +imxrt1050-evk +============= + +How to use U-Boot on NXP i.MXRT1050 EVK +--------------------------------------- + +- Build U-Boot for i.MXRT1050 EVK: + +.. code-block:: bash + + $ make mrproper + $ make imxrt1050-evk_defconfig + $ make + +This will generate the SPL image called SPL and the u-boot.img. + +- Flash the SPL image into the micro SD card: + +.. code-block:: bash + + $sudo dd if=SPL of=/dev/sdX bs=1k seek=1 conv=notrunc; sync + +- Flash the u-boot.img image into the micro SD card: + +.. code-block:: bash + + $sudo dd if=u-boot.img of=/dev/sdX bs=1k seek=128 conv=notrunc; sync + +- Jumper settings:: + + SW7: 1 0 1 0 + +where 0 means bottom position and 1 means top position (from the +switch label numbers reference). + +- Connect the USB cable between the EVK and the PC for the console. + The USB console connector is the one close the ethernet connector + +- Insert the micro SD card in the board, power it up and U-Boot messages should come up. diff --git a/roms/u-boot/doc/board/freescale/index.rst b/roms/u-boot/doc/board/freescale/index.rst new file mode 100644 index 000000000..313cf409a --- /dev/null +++ b/roms/u-boot/doc/board/freescale/index.rst @@ -0,0 +1,20 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +Freescale +========= + +.. toctree:: + :maxdepth: 2 + + b4860qds + imx8mm_evk + imx8mn_evk + imx8mp_evk + imx8mq_evk + imx8qxp_mek + imxrt1020-evk + imxrt1050-evk + mx6sabreauto + mx6sabresd + mx6ul_14x14_evk + mx6ullevk diff --git a/roms/u-boot/doc/board/freescale/mx6sabreauto.rst b/roms/u-boot/doc/board/freescale/mx6sabreauto.rst new file mode 100644 index 000000000..fe4cd9d21 --- /dev/null +++ b/roms/u-boot/doc/board/freescale/mx6sabreauto.rst @@ -0,0 +1,100 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +mx6sabreauto +============ + +How to use and build U-Boot on mx6sabreauto +------------------------------------------- + +mx6sabreauto_defconfig target supports mx6q/mx6dl/mx6qp sabreauto variants. + +In order to build it: + +.. code-block:: bash + + $ make mx6sabreauto_defconfig + $ make + +This will generate the SPL and u-boot-dtb.img binaries. + +- Flash the SPL binary into the SD card: + +.. code-block:: bash + + $ sudo dd if=SPL of=/dev/sdX bs=1K seek=1 conv=notrunc && sync + +- Flash the u-boot-dtb.img binary into the SD card: + +.. code-block:: bash + + $ sudo dd if=u-boot-dtb.img of=/dev/sdX bs=1K seek=69 conv=notrunc && sync + +Booting via Falcon mode +----------------------- + +Write in mx6sabreauto_defconfig the following define below: + +CONFIG_SPL_OS_BOOT=y + +In order to build it: + +.. code-block:: bash + + $ make mx6sabreauto_defconfig + $ make + +This will generate the SPL image called SPL and the u-boot-dtb.img. + +- Flash the SPL image into the SD card: + +.. code-block:: bash + + $ sudo dd if=SPL of=/dev/sdb bs=1K seek=1 conv=notrunc && sync + +- Flash the u-boot-dtb.img image into the SD card: + +.. code-block:: bash + + $ sudo dd if=u-boot-dtb.img of=/dev/sdb bs=1K seek=69 conv=notrunc && sync + +Create a FAT16 boot partition to store uImage and the dtb file, then copy the files there: + +.. code-block:: bash + + $ sudo cp uImage /media/boot + $ sudo cp imx6dl-sabreauto.dtb /media/boot + +Create a partition for root file system and extract it there: + +.. code-block:: bash + + $ sudo tar xvf rootfs.tar.gz -C /media/root + +The SD card must have enough space for raw "args" and "kernel". +To configure Falcon mode for the first time, on U-Boot do the following commands: + +- Load dtb file from boot partition:: + + # load mmc 0:1 ${fdt_addr} imx6dl-sabreauto.dtb + +- Load kernel image from boot partition:: + + # load mmc 0:1 ${loadaddr} uImage + +- Write kernel at 2MB offset:: + + # mmc write ${loadaddr} 0x1000 0x4000 + +- Setup kernel bootargs:: + + # setenv bootargs "console=ttymxc3,115200 root=/dev/mmcblk0p1 rootfstype=ext4 rootwait quiet rw" + +- Prepare args:: + + # spl export fdt ${loadaddr} - ${fdt_addr} + +- Write args 1MB data (0x800 sectors) to 1MB offset (0x800 sectors):: + + # mmc write 18000000 0x800 0x800 + +- Restart the board and then SPL binary will launch the kernel directly. diff --git a/roms/u-boot/doc/board/freescale/mx6sabresd.rst b/roms/u-boot/doc/board/freescale/mx6sabresd.rst new file mode 100644 index 000000000..fe15ba7b7 --- /dev/null +++ b/roms/u-boot/doc/board/freescale/mx6sabresd.rst @@ -0,0 +1,132 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +mx6sabresd +========== + +How to use and build U-Boot on mx6sabresd +----------------------------------------- + +The following methods can be used for booting mx6sabresd boards: + +1. Booting from SD card + +2. Booting from eMMC + +3. Booting via Falcon mode (SPL launches the kernel directly) + + +1. Booting from SD card via SPL +------------------------------- + +mx6sabresd_defconfig target supports mx6q/mx6dl/mx6qp sabresd variants. + +In order to build it: + +.. code-block:: bash + + $ make mx6sabresd_defconfig + $ make + +This will generate the SPL and u-boot-dtb.img binaries. + +- Flash the SPL binary into the SD card: + +.. code-block:: bash + + $ sudo dd if=SPL of=/dev/sdX bs=1K seek=1 conv=notrunc && sync + +- Flash the u-boot-dtb.img binary into the SD card: + +.. code-block:: bash + + $ sudo dd if=u-boot-dtb.img of=/dev/sdX bs=1K seek=69 conv=notrunc && sync + +2. Booting from eMMC +-------------------- + +.. code-block:: bash + + $ make mx6sabresd_defconfig + $ make + +This will generate the SPL and u-boot-dtb.img binaries. + +- Boot first from SD card as shown in the previous section + +In U-boot change the eMMC partition config:: + + => mmc partconf 2 1 0 0 + +Mount the eMMC in the host PC:: + + => ums 0 mmc 2 + +- Flash SPL and u-boot-dtb.img binaries into the eMMC: + +.. code-block:: bash + + $ sudo dd if=SPL of=/dev/sdX bs=1K seek=1 conv=notrunc && sync + $ sudo dd if=u-boot-dtb.img of=/dev/sdX bs=1K seek=69 conv=notrunc && sync + +Set SW6 to eMMC 8-bit boot: 11010110 + +3. Booting via Falcon mode +-------------------------- + +.. code-block:: bash + + $ make mx6sabresd_defconfig + $ make + +This will generate the SPL image called SPL and the u-boot-dtb.img. + +- Flash the SPL image into the SD card + +.. code-block:: bash + + $ sudo dd if=SPL of=/dev/sdX bs=1K seek=1 oflag=sync status=none conv=notrunc && sync + +- Flash the u-boot-dtb.img image into the SD card + +.. code-block:: bash + + $ sudo dd if=u-boot-dtb.img of=/dev/sdX bs=1K seek=69 oflag=sync status=none conv=notrunc && sync + +Create a partition for root file system and extract it there + +.. code-block:: bash + + $ sudo tar xvf rootfs.tar.gz -C /media/root + +The SD card must have enough space for raw "args" and "kernel". +To configure Falcon mode for the first time, on U-Boot do the following commands: + +- Setup the IP server:: + + # setenv serverip <server_ip_address> + +- Download dtb file:: + + # dhcp ${fdt_addr} imx6q-sabresd.dtb + +- Download kernel image:: + + # dhcp ${loadaddr} uImage + +- Write kernel at 2MB offset:: + + # mmc write ${loadaddr} 0x1000 0x4000 + +- Setup kernel bootargs:: + + # setenv bootargs "console=ttymxc0,115200 root=/dev/mmcblk1p1 rootfstype=ext4 rootwait quiet rw" + +- Prepare args:: + + # spl export fdt ${loadaddr} - ${fdt_addr} + +- Write args 1MB data (0x800 sectors) to 1MB offset (0x800 sectors):: + + # mmc write 18000000 0x800 0x800 + +- Press KEY_VOL_UP key, power up the board and then SPL binary will launch the kernel directly. diff --git a/roms/u-boot/doc/board/freescale/mx6ul_14x14_evk.rst b/roms/u-boot/doc/board/freescale/mx6ul_14x14_evk.rst new file mode 100644 index 000000000..8298bf8e1 --- /dev/null +++ b/roms/u-boot/doc/board/freescale/mx6ul_14x14_evk.rst @@ -0,0 +1,98 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +mx6ul_14x14_evk +=============== + +How to use U-Boot on Freescale MX6UL 14x14 EVK +----------------------------------------------- + +- Build U-Boot for MX6UL 14x14 EVK: + +.. code-block:: bash + + $ make mrproper + $ make mx6ul_14x14_evk_defconfig + $ make + +This will generate the SPL image called SPL and the u-boot.img. + +1. Booting via SDCard +--------------------- + +- Flash the SPL image into the micro SD card: + +.. code-block:: bash + + sudo dd if=SPL of=/dev/mmcblk0 bs=1k seek=1 conv=notrunc; sync + +- Flash the u-boot.img image into the micro SD card: + +.. code-block:: bash + + sudo dd if=u-boot.img of=/dev/mmcblk0 bs=1k seek=69 conv=notrunc; sync + +- Jumper settings:: + + SW601: 0 0 1 0 + Sw602: 1 0 + +where 0 means bottom position and 1 means top position (from the +switch label numbers reference). + +- Connect the USB cable between the EVK and the PC for the console. + The USB console connector is the one close the push buttons + +- Insert the micro SD card in the board, power it up and U-Boot messages should come up. + +2. Booting via Serial Download Protocol (SDP) +--------------------------------------------- + +The mx6ulevk board can boot from USB OTG port using the SDP, target will +enter in SDP mode in case an SD Card is not connect or boot switches are +set as below:: + + Sw602: 0 1 + SW601: x x x x + +The following tools can be used to boot via SDP, for both tools you must +connect an USB cable in USB OTG port. + +- Method 1: Universal Update Utility (uuu) + +The UUU binary can be downloaded in release tab from link below: +https://github.com/NXPmicro/mfgtools + +The following script should be created to boot SPL + u-boot-dtb.img binaries: + +.. code-block:: bash + + $ cat uuu_script + uuu_version 1.1.4 + + SDP: boot -f SPL + SDPU: write -f u-boot-dtb.img -addr 0x877fffc0 + SDPU: jump -addr 0x877fffc0 + SDPU: done + +Please note that the address above is calculated based on SYS_TEXT_BASE address: + +0x877fffc0 = 0x87800000 (SYS_TEXT_BASE) - 0x40 (U-Boot proper Header size) + +Power on the target and run the following command from U-Boot root directory: + +.. code-block:: bash + + $ sudo ./uuu uuu_script + +- Method 2: imx usb loader tool (imx_usb): + +The imx_usb_loader tool can be downloaded in link below: +https://github.com/boundarydevices/imx_usb_loader + +Build the source code and run the following commands from U-Boot root +directory: + +.. code-block:: bash + + $ sudo ./imx_usb SPL + $ sudo ./imx_usb u-boot-dtb.img diff --git a/roms/u-boot/doc/board/freescale/mx6ullevk.rst b/roms/u-boot/doc/board/freescale/mx6ullevk.rst new file mode 100644 index 000000000..a26248a1e --- /dev/null +++ b/roms/u-boot/doc/board/freescale/mx6ullevk.rst @@ -0,0 +1,47 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +mx6ullevk +========= + +How to use U-Boot on Freescale MX6ULL 14x14 EVK +----------------------------------------------- + +- First make sure you have installed the dtc package (device tree compiler): + +.. code-block:: bash + + $ sudo apt-get install device-tree-compiler + +- Build U-Boot for MX6ULL 14x14 EVK: + +.. code-block:: bash + + $ make mrproper + $ make mx6ull_14x14_evk_defconfig + $ make + +This generates the u-boot-dtb.imx image in the current directory. + +- Flash the u-boot-dtb.imx image into the micro SD card: + +.. code-block:: bash + + $ sudo dd if=u-boot-dtb.imx of=/dev/sdb bs=1K seek=1 conv=notrunc && sync + +- Jumper settings:: + + SW601: 0 0 1 0 + Sw602: 1 0 + +Where 0 means bottom position and 1 means top position (from the switch label +numbers reference). + +Connect the USB cable between the EVK and the PC for the console. +(The USB console connector is the one close the push buttons) + +Insert the micro SD card in the board, power it up and U-Boot messages should +come up. + +The link for the board: http://www.nxp.com/products/microcontrollers-and- \ +processors/arm-processors/i.mx-applications-processors/i.mx-6-processors/ \ +i.mx6qp/evaluation-kit-for-the-i.mx-6ull-applications-processor:MCIMX6ULL-EVK diff --git a/roms/u-boot/doc/board/google/chromebook_coral.rst b/roms/u-boot/doc/board/google/chromebook_coral.rst new file mode 100644 index 000000000..4b585678d --- /dev/null +++ b/roms/u-boot/doc/board/google/chromebook_coral.rst @@ -0,0 +1,442 @@ +.. SPDX-License-Identifier: GPL-2.0+ +.. sectionauthor:: Simon Glass <sjg@chromium.org> + +Chromebook Coral +================ + +Coral is a Chromebook (or really about 20 different Chromebooks) which use the +Intel Apollo Lake platform (APL). The 'reef' Chromebooks use the same APL SoC so +should also work. Some later ones based on Glacier Lake (GLK) need various +changes in GPIOs, etc. but are very similar. + +It is hoped that this port can enable ports to embedded APL boards which are +starting to appear. + +Note that booting U-Boot on APL is already supported by coreboot and +Slim Bootloader. This documentation refers to a 'bare metal' port. + + +Building +-------- + +First, you need the following binary blobs: + + * descriptor.bin - Intel flash descriptor + * fitimage.bin - Base flash image structure + * fsp_m.bin - FSP-M, for setting up SDRAM + * fsp_s.bin - FSP-S, for setting up Silicon + * vbt.bin - for setting up display + +These binaries do not seem to be available publicly. If you have a ROM image, +such as santa.bin then you can do this:: + + cbfstool santa.bin extract -n fspm.bin -f fsp-m.bin + cbfstool santa.bin extract -n fsps.bin -f fsp-s.bin + cbfstool santa.bin extract -n vbt-santa.bin -f vbt.bin + mkdir tmp + cd tmp + dump_fmap -x ../santa.bin + mv SI_DESC ../descriptor.bin + mv IFWI ../fitimage.bin + +Put all of these files in `board/google/chromebook_coral` so they can be found +by the build. + +To build:: + + make O=/tmp/b/chromebook_coral chromebook_coral_defconfig + make O=/tmp/b/chromebook_coral -s -j30 all + +That should produce `/tmp/b/chrombook_coral/u-boot.rom` which you can use with +a Dediprog em100:: + + em100 -s -c w25q128fw -d /tmp/b/chromebook_coral/u-boot.rom -r + +or you can use flashrom to write it to the board. If you do that, make sure you +have a way to restore the old ROM without booting the board. Otherwise you may +brick it. Having said that, you may find these instructions useful if you want +to unbrick your device: + + https://chromium.googlesource.com/chromiumos/platform/ec/+/cr50_stab/docs/case_closed_debugging.md + +You can buy Suzy-Q from Sparkfun: + + https://chromium.googlesource.com/chromiumos/third_party/hdctools/+/main/docs/ccd.md#suzyq-suzyqable + +Note that it will hang at the SPL prompt for 21 seconds. When booting into +Chrome OS it will always select developer mode, so will wipe anything you have +on the device if you let it proceed. You have two seconds in U-Boot to stop the +auto-boot prompt and several seconds at the 'developer wipe' screen to stop it +wiping the disk. + +Here is the console output:: + + U-Boot TPL 2021.04-rc1-00128-g344eefcdfec-dirty (Feb 11 2021 - 20:13:08 -0700) + Trying to boot from Mapped SPI + + U-Boot SPL 2021.04-rc1-00128-g344eefcdfec-dirty (Feb 11 2021 - 20:13:08 -0700) + Trying to boot from Mapped SPI + + + U-Boot 2021.04-rc1-00128-g344eefcdfec-dirty (Feb 11 2021 - 20:13:08 -0700) + + CPU: Intel(R) Celeron(R) CPU N3450 @ 1.10GHz + DRAM: 3.9 GiB + MMC: sdmmc@1b,0: 1, emmc@1c,0: 2 + Video: 1024x768x32 @ b0000000 + Model: Google Coral + Net: No ethernet found. + SF: Detected w25q128fw with page size 256 Bytes, erase size 4 KiB, total 16 MiB + Hit any key to stop autoboot: 0 + cmdline=console= loglevel=7 init=/sbin/init cros_secure oops=panic panic=-1 root=PARTUUID=${uuid}/PARTNROFF=1 rootwait rw dm_verity.error_behavior=3 dm_verity.max_bios=-1 dm_verity.dev_wait=0 dm="1 vroot none rw 1,0 3788800 verity payload=ROOT_DEV hashtree=HASH_DEV hashstart=3788800 alg=sha1 root_hexdigest=55052b629d3ac889f25a9583ea12cdcd3ea15ff8 salt=a2d4d9e574069f4fed5e3961b99054b7a4905414b60a25d89974a7334021165c" noinitrd vt.global_cursor_default=0 kern_guid=${uuid} add_efi_memmap boot=local noresume noswap i915.modeset=1 Kernel command line: "console= loglevel=7 init=/sbin/init cros_secure oops=panic panic=-1 root=PARTUUID=35c775e7-3735-d745-93e5-d9e0238f7ed0/PARTNROFF=1 rootwait rw dm_verity.error_behavior=3 dm_verity.max_bios=-1 dm_verity.dev_wait=0 dm="1 vroot none rw 1,0 3788800 verity payload=ROOT_DEV hashtree=HASH_DEV hashstart=3788800 alg=sha1 root_hexdigest=55052b629d3ac889f25a9583ea12cdcd3ea15ff8 salt=a2d4d9e574069f4fed5e3961b99054b7a4905414b60a25d89974a7334021165c" noinitrd vt.global_cursor_default=0 kern_guid=35c775e7-3735-d745-93e5-d9e0238f7ed0 add_efi_memmap boot=local noresume noswap i915.modeset=1 tpm_tis.force=1 tpm_tis.interrupts=0 nmi_watchdog=panic,lapic disablevmx=off " + Setup located at 00090000: + + ACPI RSDP addr : 7991f000 + E820: 14 entries + Addr Size Type + d0000000 1000000 <NULL> + 0 a0000 RAM + a0000 60000 Reserved + 7b000000 800000 Reserved + 7b800000 4800000 Reserved + 7ac00000 400000 Reserved + 100000 ff00000 RAM + 10000000 2151000 Reserved + 12151000 68aaf000 RAM + 100000000 80000000 RAM + e0000000 10000000 Reserved + 7991bfd0 12e4030 Reserved + d0000000 10000000 Reserved + fed10000 8000 Reserved + Setup sectors : 1e + Root flags : 1 + Sys size : 63420 + RAM size : 0 + Video mode : ffff + Root dev : 0 + Boot flag : 0 + Jump : 66eb + Header : 53726448 + Kernel V2 + Version : 20d + Real mode switch : 0 + Start sys : 1000 + Kernel version : 38cc + @00003acc: + Type of loader : 80 + U-Boot, version 0 + Load flags : 81 + : loaded-high can-use-heap + Setup move size : 8000 + Code32 start : 100000 + Ramdisk image : 0 + Ramdisk size : 0 + Bootsect kludge : 0 + Heap end ptr : 8e00 + Ext loader ver : 0 + Ext loader type : 0 + Command line ptr : 99000 + console= loglevel=7 init=/sbin/init cros_secure oops=panic panic=-1 root=PARTUUID=35c775e7-3735-d745-93e5-d9e0238f7ed0/PARTNROFF=1 rootwait rw dm_verity.error_behavior=3 dm_verity.max_bios=-1 dm_verity.dev_wait=0 dm="1 vroot none rw 1,0 3788800 verity payload=ROOT_DEV hashtree=HASH_DEV hashstart=3788800 alg=sha1 root_hexdigest=55052b629d3ac889f25a9583ea12cdcd3ea15ff8 salt=a2d4d9e574069f4fed5e3961b99054b7a4905414b60a25d89974a7334021165c" noinitrd vt.global_cursor_default=0 kern_guid=35c775e7-3735-d745-93e5-d9e0238f7ed0 add_efi_memmap boot=local noresume noswap i915.modeset=1 tpm_tis.force=1 tpm_tis.interrupts=0 nmi_watchdog=panic,lapic disablevmx=off + Initrd addr max : 7fffffff + Kernel alignment : 200000 + Relocatable kernel : 1 + Min alignment : 15 + : 200000 + Xload flags : 3 + : 64-bit-entry can-load-above-4gb + Cmdline size : 7ff + Hardware subarch : 0 + HW subarch data : 0 + Payload offset : 26e + Payload length : 612045 + Setup data : 0 + Pref address : 1000000 + Init size : 1383000 + Handover offset : 0 + + Starting kernel ... + + Timer summary in microseconds (17 records): + Mark Elapsed Stage + 0 0 reset + 155,279 155,279 TPL + 237,088 81,809 end phase + 237,533 445 SPL + 816,456 578,923 end phase + 817,357 901 board_init_f + 1,061,751 244,394 board_init_r + 1,402,435 340,684 id=64 + 1,430,071 27,636 main_loop + 5,532,057 4,101,986 start_kernel + + Accumulated time: + 685 dm_r + 2,817 fast_spi + 33,095 dm_spl + 52,468 dm_f + 208,242 fsp-m + 242,221 fsp-s + 332,710 mmap_spi + + +Boot flow - TPL +--------------- + +Apollo Lake boots via an IFWI (Integrated Firmware Image). TPL is placed in +this, in the IBBL entry. + +On boot, an on-chip microcontroller called the CSE (Converged Security Engine) +sets up some SDRAM at ffff8000 and loads the TPL image to that address. The +SRAM extends up to the top of 32-bit address space, but the last 2KB is the +start16 region, so the TPL image must be 30KB at most, and CONFIG_TPL_TEXT_BASE +must be ffff8000. Actually the start16 region is small and it could probably +move from f800 to fe00, providing another 1.5KB, but TPL is only about 19KB so +there is no need to change it at present. The size limit is enforced by +CONFIG_TPL_SIZE_LIMIT to avoid producing images that won't boot. + +TPL (running from start.S) first sets up CAR (Cache-as-RAM) which provides +larger area of RAM for use while booting. CAR is mapped at CONFIG_SYS_CAR_ADDR +(fef00000) and is 768KB in size. It then sets up the stack in the botttom 64KB +of this space (i.e. below fef10000). This means that the stack and early +malloc() region in TPL can be 64KB at most. + +TPL operates without CONFIG_TPL_PCI enabled so PCI config access must use the +x86-specific functions pci_x86_write_config(), etc. SPL creates a simple-bus +device so that PCI devices are bound by driver model. Then arch_cpu_init_tpl() +is called to early init on various devices. This includes placing PCI devices +at hard-coded addresses in the memory map. PCI auto-config is not used. + +Most of the 16KB ROM is mapped into the very top of memory, except for the +Intel descriptor (first 4KB) and the space for SRAM as above. + +TPL does not set up a bloblist since at present it does not have anything to +pass to SPL. + +Once TPL is done it loads SPL from ROM using either the memory-mapped SPI or by +using the Intel fast SPI driver. SPL is loaded into CAR, at the address given +by CONFIG_SPL_TEXT_BASE, which is normally fef10000. + +Note that booting using the SPI driver results in an TPL image that is about +26KB in size instead of 19KB. Also boot speed is worse by about 340ms. If you +really want to use the driver, enable CONFIG_APL_SPI_FLASH_BOOT and set +BOOT_FROM_FAST_SPI_FLASH to true[2]. + + +Boot flow - SPL +--------------- + +SPL (running from start_from_tpl.S) continues to use the same stack as TPL. +It calls arch_cpu_init_spl() to set up a few devices, then init_dram() loads +the FSP-M binary into CAR and runs to, to set up SDRAM. The address of the +output 'HOB' list (Hand-off-block) is stored into gd->arch.hob_list for parsing. +There is a 2GB chunk of SDRAM starting at 0 and the rest is at 4GB. + +PCI auto-config is not used in SPL either, but CONFIG_SPL_PCI is defined, so +proper PCI access is available and normal dm_pci_read_config() calls can be +used. However PCI auto-config is not used so the same static memory mapping set +up by TPL is still active. + +SPL on x86 always runs with CONFIG_SPL_SEPARATE_BSS=y and BSS is at 120000 +(see u-boot-spl.lds). This works because SPL doesn't access BSS until after +board_init_r(), as per the rules, and DRAM is available then. + +SPL sets up a bloblist and passes the SPL hand-off information to U-Boot proper. +This includes a pointer to the HOB list as well as DRAM information. See +struct arch_spl_handoff. The bloblist address is set by CONFIG_BLOBLIST_ADDR, +normally 100000. + +SPL uses SPI flash to update the MRC caches in ROM. This speeds up subsequent +boots. Be warned that SPL can take 30 seconds without this cache! This is a +known issue with Intel SoCs with modern DRAM and apparently cannot be improved. +The MRC caches are used to work around this. + +Once SPL is finished it loads U-Boot into SDRAM at CONFIG_SYS_TEXT_BASE, which +is normally 1110000. Note that CAR is still active. + + +Boot flow - U-Boot pre-relocation +--------------------------------- + +U-Boot (running from start_from_spl.S) starts running in RAM and uses the same +stack as SPL. It does various init activities before relocation. Notably +arch_cpu_init_dm() sets up the pin muxing for the chip using a very large table +in the device tree. + +PCI auto-config is not used before relocation, but CONFIG_PCI of course is +defined, so proper PCI access is available. The same static memory mapping set +up by TPL is still active until relocation. + +As per usual, U-Boot allocates memory at the top of available RAM (a bit below +2GB in this case) and copies things there ready to relocate itself. Notably +reserve_arch() does not reserve space for the HOB list returned by FSP-M since +this is already located in RAM. + +U-Boot then shuts down CAR and jumps to its relocated version. + + +Boot flow - U-Boot post-relocation +---------------------------------- + +U-Boot starts up normally, running near the top of RAM. After driver model is +running, arch_fsp_init_r() is called which loads and runs the FSP-S binary. +This updates the HOB list to include graphics information, used by the fsp_video +driver. + +PCI autoconfig is done and a few devices are probed to complete init. Most +others are started only when they are used. + +Note that FSP-S is supposed to run after CAR has been shut down, which happens +immediately before U-Boot starts up in its relocated position. Therefore we +cannot run FSP-S before relocation. On the other hand we must run it before +PCI auto-config is done, since FSP-S may show or hide devices. The first device +that probes PCI after relocation is the serial port, in initr_serial(), so FSP-S +must run before that. A corollary is that loading FSP-S must be done without +using the SPI driver, to avoid probing PCI and causing an autoconfig, so +memory-mapped reading is always used for FSP-S. + +It would be possible to tear down CAR in SPL instead of U-Boot. The SPL handoff +information could make sure it does not include any pointers into CAR (in fact +it doesn't). But tearing down CAR in U-Boot allows the initial state used by TPL +and SPL to be read by U-Boot, which seems useful. It also matches how older +platforms start up (those that don't use SPL). + + +Performance +----------- + +Bootstage is used through all phases of U-Boot to keep accurate timimgs for +boot. Use 'bootstage report' in U-Boot to see the report, e.g.:: + + Timer summary in microseconds (16 records): + Mark Elapsed Stage + 0 0 reset + 155,325 155,325 TPL + 204,014 48,689 end TPL + 204,385 371 SPL + 738,633 534,248 end SPL + 739,161 528 board_init_f + 842,764 103,603 board_init_r + 1,166,233 323,469 main_loop + 1,166,283 50 id=175 + + Accumulated time: + 62 fast_spi + 202 dm_r + 7,779 dm_spl + 15,555 dm_f + 208,357 fsp-m + 239,847 fsp-s + 292,143 mmap_spi + +CPU performance is about 3500 DMIPS:: + + => dhry + 1000000 iterations in 161 ms: 6211180/s, 3535 DMIPS + + +Partial memory map +------------------ + +:: + + ffffffff Top of ROM (and last byte of 32-bit address space) + ffff8000 TPL loaded here (from IFWI) + ff000000 Bottom of ROM + fefc0000 Top of CAR region + fef96000 Stack for FSP-M + fef40000 59000 FSP-M (also VPL loads here) + fef11000 SPL loaded here + fef10000 CONFIG_BLOBLIST_ADDR + fef10000 Stack top in TPL, SPL and U-Boot before relocation + fef00000 1000 CONFIG_BOOTSTAGE_STASH_ADDR + fef00000 Base of CAR region + + 30000 AP_DEFAULT_BASE (used to start up additional CPUs) + f0000 CONFIG_ROM_TABLE_ADDR + 120000 BSS (defined in u-boot-spl.lds) + 200000 FSP-S (which is run after U-Boot is relocated) + 1110000 CONFIG_SYS_TEXT_BASE + + +Speeding up SPL for development +------------------------------- + +The 21-second wait for memory training is annoying during development, since +every new image incurs this cost when booting. There is no cache to fall back on +since that area of the image is empty on start-up. + +You can add suitable cache contents to the image to fix this, for development +purposes only, like this:: + + # Read the image back after booting through SPL + em100 -s -c w25q128fw -u image.bin + + # Extract the two cache regions + binman extract -i image.bin extra *cache + + # Move them into the source directory + mv *cache board/google/chromebook_coral + +Then add something like this to the devicetree:: + + #if IS_ENABLED(CONFIG_HAVE_MRC) || IS_ENABLED(CONFIG_FSP_VERSION2) + /* Provide initial contents of the MRC data for faster development */ + rw-mrc-cache { + type = "blob"; + /* Mirror the offset in spi-flash@0 */ + offset = <0xff8e0000>; + size = <0x10000>; + filename = "board/google/chromebook_coral/rw-mrc-cache"; + }; + rw-var-mrc-cache { + type = "blob"; + size = <0x1000>; + filename = "board/google/chromebook_coral/rw-var-mrc-cache"; + }; + #endif + +This tells binman to put the cache contents in the same place as the +`rw-mrc-cache` and `rw-var-mrc-cache` regions defined by the SPI-flash driver. + + +Supported peripherals +--------------------- + +The following have U-Boot drivers: + + - UART + - SPI flash + - Video + - MMC (dev 0) and micro-SD (dev 1) + - Chrome OS EC + - Cr50 (security chip) + - Keyboard + - USB + + +To do +----- + +- Finish peripherals + - Sound (Intel I2S support exists, but need da7219 driver) +- Use FSP-T binary instead of our own CAR implementation +- Use the official FSP package instead of the coreboot one +- Suspend / resume +- Fix MMC which seems to try to read even though the card is empty +- Fix USB3 crash "WARN halted endpoint, queueing URB anyway." + + +Credits +------- + +This is a spare-time project conducted slowly over a long period of time. + +Much of the code for this port came from Coreboot, an open-source firmware +project similar to U-Boot's SPL in terms of features. + +Also see [2] for information about the boot flow used by coreboot. It is +similar, but has an extra postcar stage. U-Boot doesn't need this since it +supports relocating itself in memory. + + +[2] Intel PDF https://www.coreboot.org/images/2/23/Apollolake_SoC.pdf diff --git a/roms/u-boot/doc/board/google/chromebook_link.rst b/roms/u-boot/doc/board/google/chromebook_link.rst new file mode 100644 index 000000000..16080304d --- /dev/null +++ b/roms/u-boot/doc/board/google/chromebook_link.rst @@ -0,0 +1,34 @@ +.. SPDX-License-Identifier: GPL-2.0+ +.. sectionauthor:: Simon Glass <sjg@chromium.org> + +Chromebook Link +=============== + +First, you need the following binary blobs: + + * descriptor.bin - Intel flash descriptor + * me.bin - Intel Management Engine + * mrc.bin - Memory Reference Code, which sets up SDRAM + * video ROM - sets up the display + +You can get these binary blobs by:: + + $ git clone http://review.coreboot.org/p/blobs.git + $ cd blobs + +Find the following files: + + * ./mainboard/google/link/descriptor.bin + * ./mainboard/google/link/me.bin + * ./northbridge/intel/sandybridge/systemagent-r6.bin + +The 3rd one should be renamed to mrc.bin. +As for the video ROM, you can get it `here`_ and rename it to vga.bin. +Make sure all these binary blobs are put in the board directory. + +Now you can build U-Boot and obtain u-boot.rom:: + + $ make chromebook_link_defconfig + $ make all + +.. _here: http://www.coreboot.org/~stepan/pci8086,0166.rom diff --git a/roms/u-boot/doc/board/google/chromebook_samus.rst b/roms/u-boot/doc/board/google/chromebook_samus.rst new file mode 100644 index 000000000..eab1128e4 --- /dev/null +++ b/roms/u-boot/doc/board/google/chromebook_samus.rst @@ -0,0 +1,101 @@ +.. SPDX-License-Identifier: GPL-2.0+ +.. sectionauthor:: Simon Glass <sjg@chromium.org> + +Chromebook Samus +================ + +First, you need the following binary blobs: + + * descriptor.bin - Intel flash descriptor + * me.bin - Intel Management Engine + * mrc.bin - Memory Reference Code, which sets up SDRAM + * refcode.elf - Additional Reference code + * vga.bin - video ROM, which sets up the display + +If you have a samus you can obtain them from your flash, for example, in +developer mode on the Chromebook (use Ctrl-Alt-F2 to obtain a terminal and +log in as 'root'):: + + cd /tmp + flashrom -w samus.bin + scp samus.bin username@ip_address:/path/to/somewhere + +If not see the coreboot tree where you can use:: + + bash crosfirmware.sh samus + +to get the image. There is also an 'extract_blobs.sh' scripts that you can use +on the 'coreboot-Google_Samus.*' file to short-circuit some of the below. + +Then 'ifdtool -x samus.bin' on your development machine will produce:: + + flashregion_0_flashdescriptor.bin + flashregion_1_bios.bin + flashregion_2_intel_me.bin + +Rename flashregion_0_flashdescriptor.bin to descriptor.bin +Rename flashregion_2_intel_me.bin to me.bin +You can ignore flashregion_1_bios.bin - it is not used. + +To get the rest, use 'cbfstool samus.bin print':: + + samus.bin: 8192 kB, bootblocksize 2864, romsize 8388608, offset 0x700000 + alignment: 64 bytes, architecture: x86 + +============================ ======== =========== ====== +Name Offset Type Size +============================ ======== =========== ====== +cmos_layout.bin 0x700000 cmos_layout 1164 +pci8086,0406.rom 0x7004c0 optionrom 65536 +spd.bin 0x710500 (unknown) 4096 +cpu_microcode_blob.bin 0x711540 microcode 70720 +fallback/romstage 0x722a00 stage 54210 +fallback/ramstage 0x72fe00 stage 96382 +config 0x7476c0 raw 6075 +fallback/vboot 0x748ec0 stage 15980 +fallback/refcode 0x74cd80 stage 75578 +fallback/payload 0x75f500 payload 62878 +u-boot.dtb 0x76eb00 (unknown) 5318 +(empty) 0x770000 null 196504 +mrc.bin 0x79ffc0 (unknown) 222876 +(empty) 0x7d66c0 null 167320 +============================ ======== =========== ====== + +You can extract what you need:: + + cbfstool samus.bin extract -n pci8086,0406.rom -f vga.bin + cbfstool samus.bin extract -n fallback/refcode -f refcode.rmod + cbfstool samus.bin extract -n mrc.bin -f mrc.bin + cbfstool samus.bin extract -n fallback/refcode -f refcode.bin -U + +Note that the -U flag is only supported by the latest cbfstool. It unpacks +and decompresses the stage to produce a coreboot rmodule. This is a simple +representation of an ELF file. You need the patch "Support decoding a stage +with compression". + +Put all 5 files into board/google/chromebook_samus. + +Now you can build U-Boot and obtain u-boot.rom:: + + $ make chromebook_samus_defconfig + $ make all + +If you are using em100, then this command will flash write -Boot:: + + em100 -s -d filename.rom -c W25Q64CV -r + +Flash map for samus / broadwell: + + :fffff800: SYS_X86_START16 + :ffff0000: RESET_SEG_START + :fffd8000: TPL_TEXT_BASE + :fffa0000: X86_MRC_ADDR + :fff90000: VGA_BIOS_ADDR + :ffed0000: SYS_TEXT_BASE + :ffea0000: X86_REFCODE_ADDR + :ffe70000: SPL_TEXT_BASE + :ffbf8000: CONFIG_ENV_OFFSET (environemnt offset) + :ffbe0000: rw-mrc-cache (Memory-reference-code cache) + :ffa00000: <spare> + :ff801000: intel-me (address set by descriptor.bin) + :ff800000: intel-descriptor diff --git a/roms/u-boot/doc/board/google/index.rst b/roms/u-boot/doc/board/google/index.rst new file mode 100644 index 000000000..061c79771 --- /dev/null +++ b/roms/u-boot/doc/board/google/index.rst @@ -0,0 +1,11 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +Google +====== + +.. toctree:: + :maxdepth: 2 + + chromebook_coral + chromebook_link + chromebook_samus diff --git a/roms/u-boot/doc/board/index.rst b/roms/u-boot/doc/board/index.rst new file mode 100644 index 000000000..747511f7d --- /dev/null +++ b/roms/u-boot/doc/board/index.rst @@ -0,0 +1,29 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +Board-specific doc +================== + +.. toctree:: + :maxdepth: 2 + + actions/index + advantech/index + AndesTech/index + amlogic/index + atmel/index + congatec/index + coreboot/index + emulation/index + freescale/index + google/index + intel/index + kontron/index + microchip/index + rockchip/index + sifive/index + sipeed/index + st/index + tbs/index + toradex/index + xen/index + xilinx/index diff --git a/roms/u-boot/doc/board/intel/bayleybay.rst b/roms/u-boot/doc/board/intel/bayleybay.rst new file mode 100644 index 000000000..db97f645f --- /dev/null +++ b/roms/u-boot/doc/board/intel/bayleybay.rst @@ -0,0 +1,29 @@ +.. SPDX-License-Identifier: GPL-2.0+ +.. sectionauthor:: Bin Meng <bmeng.cn@gmail.com> + +Bayley Bay CRB +============== + +This uses as FSP as with Crown Bay, except it is for the Atom E3800 series. +Download this and get the .fd file (BAYTRAIL_FSP_GOLD_003_16-SEP-2014.fd at +the time of writing). Put it in the corresponding board directory and rename +it to fsp.bin. + +Obtain the VGA RAM (Vga.dat at the time of writing) and put it into the same +board directory as vga.bin. + +You still need two more binary blobs. For Bayley Bay, they can be extracted +from the sample SPI image provided in the FSP (SPI.bin at the time of writing):: + + $ ./tools/ifdtool -x BayleyBay/SPI.bin + $ cp flashregion_0_flashdescriptor.bin board/intel/bayleybay/descriptor.bin + $ cp flashregion_2_intel_me.bin board/intel/bayleybay/me.bin + +Now you can build U-Boot and obtain u-boot.rom:: + + $ make bayleybay_defconfig + $ make all + +Note that the debug version of the FSP is bigger in size. If this version +is used, CONFIG_FSP_ADDR needs to be configured to 0xfffb0000 instead of +the default value 0xfffc0000. diff --git a/roms/u-boot/doc/board/intel/cherryhill.rst b/roms/u-boot/doc/board/intel/cherryhill.rst new file mode 100644 index 000000000..151f0613f --- /dev/null +++ b/roms/u-boot/doc/board/intel/cherryhill.rst @@ -0,0 +1,30 @@ +.. SPDX-License-Identifier: GPL-2.0+ +.. sectionauthor:: Bin Meng <bmeng.cn@gmail.com> + +Cherry Hill CRB +=============== + +This uses Intel FSP for Braswell platform. Download it from Intel FSP website, +put the .fd file to the board directory and rename it to fsp.bin. + +Extract descriptor.bin and me.bin from the original BIOS on the board using +ifdtool and put them to the board directory as well. + +Note the FSP package for Braswell does not ship a traditional legacy VGA BIOS +image for the integrated graphics device. Instead a new binary called Video +BIOS Table (VBT) is shipped. Put it to the board directory and rename it to +vbt.bin if you want graphics support in U-Boot. + +Now you can build U-Boot and obtain u-boot.rom:: + + $ make cherryhill_defconfig + $ make all + +An important note for programming u-boot.rom to the on-board SPI flash is that +you need make sure the SPI flash's 'quad enable' bit in its status register +matches the settings in the descriptor.bin, otherwise the board won't boot. + +For the on-board SPI flash MX25U6435F, this can be done by writing 0x40 to the +status register by DediProg in: Config > Modify Status Register > Write Status +Register(s) > Register1 Value(Hex). This is is a one-time change. Once set, it +persists in SPI flash part regardless of the u-boot.rom image burned. diff --git a/roms/u-boot/doc/board/intel/cougarcanyon2.rst b/roms/u-boot/doc/board/intel/cougarcanyon2.rst new file mode 100644 index 000000000..5e3e7a182 --- /dev/null +++ b/roms/u-boot/doc/board/intel/cougarcanyon2.rst @@ -0,0 +1,24 @@ +.. SPDX-License-Identifier: GPL-2.0+ +.. sectionauthor:: Bin Meng <bmeng.cn@gmail.com> + +Cougar Canyon 2 CRB +=================== + +This uses Intel FSP for 3rd generation Intel Core and Intel Celeron processors +with mobile Intel HM76 and QM77 chipsets platform. Download it from Intel FSP +website and put the .fd file (CHIEFRIVER_FSP_GOLD_001_09-OCTOBER-2013.fd at the +time of writing) in the board directory and rename it to fsp.bin. + +Now build U-Boot and obtain u-boot.rom:: + + $ make cougarcanyon2_defconfig + $ make all + +The board has two 8MB SPI flashes mounted, which are called SPI-0 and SPI-1 in +the board manual. The SPI-0 flash should have flash descriptor plus ME firmware +and SPI-1 flash is used to store U-Boot. For convenience, the complete 8MB SPI-0 +flash image is included in the FSP package (named Rom00_8M_MB_PPT.bin). Program +this image to the SPI-0 flash according to the board manual just once and we are +all set. For programming U-Boot we just need to program SPI-1 flash. Since the +default u-boot.rom image for this board is set to 2MB, it should be programmed +to the last 2MB of the 8MB chip, address range [600000, 7FFFFF]. diff --git a/roms/u-boot/doc/board/intel/crownbay.rst b/roms/u-boot/doc/board/intel/crownbay.rst new file mode 100644 index 000000000..4fcf9811c --- /dev/null +++ b/roms/u-boot/doc/board/intel/crownbay.rst @@ -0,0 +1,43 @@ +.. SPDX-License-Identifier: GPL-2.0+ +.. sectionauthor:: Bin Meng <bmeng.cn@gmail.com> + +Crown Bay CRB +============= + +U-Boot support of Intel `Crown Bay`_ board relies on a binary blob called +Firmware Support Package (`FSP`_) to perform all the necessary initialization +steps as documented in the BIOS Writer Guide, including initialization of the +CPU, memory controller, chipset and certain bus interfaces. + +Download the Intel FSP for Atom E6xx series and Platform Controller Hub EG20T, +install it on your host and locate the FSP binary blob. Note this platform +also requires a Chipset Micro Code (CMC) state machine binary to be present in +the SPI flash where u-boot.rom resides, and this CMC binary blob can be found +in this FSP package too. + + * ./FSP/QUEENSBAY_FSP_GOLD_001_20-DECEMBER-2013.fd + * ./Microcode/C0_22211.BIN + +Rename the first one to fsp.bin and second one to cmc.bin and put them in the +board directory. + +Note the FSP release version 001 has a bug which could cause random endless +loop during the FspInit call. This bug was published by Intel although Intel +did not describe any details. We need manually apply the patch to the FSP +binary using any hex editor (eg: bvi). Go to the offset 0x1fcd8 of the FSP +binary, change the following five bytes values from orginally E8 42 FF FF FF +to B8 00 80 0B 00. + +As for the video ROM, you need manually extract it from the Intel provided +BIOS for Crown Bay `here`_, using the AMI `MMTool`_. Check PCI option +ROM ID 8086:4108, extract and save it as vga.bin in the board directory. + +Now you can build U-Boot and obtain u-boot.rom:: + + $ make crownbay_defconfig + $ make all + +.. _`Crown Bay`: http://www.intel.com/content/www/us/en/embedded/design-tools/evaluation-platforms/atom-e660-eg20t-development-kit.html +.. _`FSP`: http://www.intel.com/fsp +.. _`here`: http://www.intel.com/content/www/us/en/secure/intelligent-systems/privileged/e6xx-35-b1-cmc22211.html +.. _`MMTool`: http://www.ami.com/products/bios-uefi-tools-and-utilities/bios-uefi-utilities/ diff --git a/roms/u-boot/doc/board/intel/edison.rst b/roms/u-boot/doc/board/intel/edison.rst new file mode 100644 index 000000000..5a65673d1 --- /dev/null +++ b/roms/u-boot/doc/board/intel/edison.rst @@ -0,0 +1,170 @@ +.. SPDX-License-Identifier: GPL-2.0+ +.. sectionauthor:: Andy Shevchenko <andriy.shevchenko@linux.intel.com> + +Edison +====== + +Build Instructions for U-Boot as main bootloader +------------------------------------------------ + +Simple you can build U-Boot and obtain u-boot.bin:: + + $ make edison_defconfig + $ make all + +Updating U-Boot on Edison +------------------------- + +By default Intel Edison boards are shipped with preinstalled heavily +patched U-Boot v2014.04. Though it supports DFU which we may be able to +use. + +1. Prepare u-boot.bin as described in chapter above. You still need one + more step (if and only if you have original U-Boot), i.e. run the + following command:: + + $ truncate -s %4096 u-boot.bin + +2. Run your board and interrupt booting to U-Boot console. In the console + call:: + + => run do_force_flash_os + +3. Wait for few seconds, it will prepare environment variable and runs + DFU. Run DFU command from the host system:: + + $ dfu-util -v -d 8087:0a99 --alt u-boot0 -D u-boot.bin + +4. Return to U-Boot console and following hint. i.e. push Ctrl+C, and + reset the board:: + + => reset + +Updating U-Boot using xFSTK +--------------------------- + +You can also update U-Boot using the xfstk-dldr-solo tool if you can build it. +One way to do that is to follow the `xFSTK`_ instructions. In short, after you +install all necessary dependencies and clone repository, it will look like this: + +.. code-block:: sh + + cd xFSTK + export DISTRIBUTION_NAME=ubuntu20.04 + export BUILD_VERSION=1.8.5 + git checkout v$BUILD_VERSION + ... + +Once you have built it, you can copy xfstk-dldr-solo to /usr/local/bin and +libboost_program_options.so.1.54.0 to /usr/lib/i386-linux-gnu/ and with luck +it will work. You might find this `drive`_ helpful. + +If it does, then you can download and unpack the Edison recovery image, +install dfu-util, reset your board and flash U-Boot like this: + +.. code-block:: sh + + xfstk-dldr-solo --gpflags 0x80000007 \ + --osimage u-boot-edison.img \ + --fwdnx recover/edison_dnx_fwr.bin \ + --fwimage recover/edison_ifwi-dbg-00.bin \ + --osdnx recover/edison_dnx_osr.bin + +This should show the following + +.. code-block:: none + + XFSTK Downloader Solo 1.8.5 + Copyright (c) 2015 Intel Corporation + Build date and time: Aug 15 2020 15:07:13 + + .Intel SoC Device Detection Found + Parsing Commandline.... + Registering Status Callback.... + .Initiating Download Process.... + .......(lots of dots)........XFSTK-STATUS--Reconnecting to device - Attempt #1 + .......(even more dots)...................... + +You have about 10 seconds after resetting the board to type the above command. +If you want to check if the board is ready, type: + +.. code-block:: none + + lsusb | egrep "8087|8086" + Bus 001 Device 004: ID 8086:e005 Intel Corp. + +If you see a device with the same ID as above, the board is waiting for your +command. + +After about 5 seconds you should see some console output from the board: + +.. code-block:: none + + ****************************** + PSH KERNEL VERSION: b0182b2b + WR: 20104000 + ****************************** + + SCU IPC: 0x800000d0 0xfffce92c + + PSH miaHOB version: TNG.B0.VVBD.0000000c + + microkernel built 11:24:08 Feb 5 2015 + + ******* PSH loader ******* + PCM page cache size = 192 KB + Cache Constraint = 0 Pages + Arming IPC driver .. + Adding page store pool .. + PagestoreAddr(IMR Start Address) = 0x04899000 + pageStoreSize(IMR Size) = 0x00080000 + + *** Ready to receive application *** + +After another 10 seconds the xFSTK tool completes and the board resets. About +10 seconds after that should see the above message again and then within a few +seconds U-Boot should start on your board: + +.. code-block:: none + + U-Boot 2020.10-rc3 (Sep 03 2020 - 18:44:28 -0600) + + CPU: Genuine Intel(R) CPU 4000 @ 500MHz + DRAM: 980.6 MiB + WDT: Started with servicing (60s timeout) + MMC: mmc@ff3fc000: 0, mmc@ff3fa000: 1 + Loading Environment from MMC... OK + In: serial + Out: serial + Err: serial + Saving Environment to MMC... Writing to redundant MMC(0)... OK + Saving Environment to MMC... Writing to MMC(0)... OK + Net: No ethernet found. + Hit any key to stop autoboot: 0 + Target:blank + Partitioning using GPT + Writing GPT: success! + Saving Environment to MMC... Writing to redundant MMC(0)... OK + Flashing already done... + 5442816 bytes read in 238 ms (21.8 MiB/s) + Valid Boot Flag + Setup Size = 0x00003c00 + Magic signature found + Using boot protocol version 2.0c + Linux kernel version 3.10.17-poky-edison+ (ferry@kalamata) #1 SMP PREEMPT Mon Jan 11 14:54:18 CET 2016 + Building boot_params at 0x00090000 + Loading bzImage at address 100000 (5427456 bytes) + Magic signature found + Kernel command line: "rootwait ..." + Magic signature found + + Starting kernel ... + + ... + + Poky (Yocto Project Reference Distro) 1.7.2 edison ttyMFD2 + + edison login: + +.. _xFSTK: https://github.com/edison-fw/xFSTK +.. _drive: https://drive.google.com/drive/u/0/folders/1URPHrOk9-UBsh8hjv-7WwC0W6Fy61uAJ diff --git a/roms/u-boot/doc/board/intel/galileo.rst b/roms/u-boot/doc/board/intel/galileo.rst new file mode 100644 index 000000000..f51a06bb9 --- /dev/null +++ b/roms/u-boot/doc/board/intel/galileo.rst @@ -0,0 +1,22 @@ +.. SPDX-License-Identifier: GPL-2.0+ +.. sectionauthor:: Bin Meng <bmeng.cn@gmail.com> + +Galileo +======= + +Only one binary blob is needed for Remote Management Unit (RMU) within Intel +Quark SoC. Not like FSP, U-Boot does not call into the binary. The binary is +needed by the Quark SoC itself. + +You can get the binary blob from Quark Board Support Package from Intel website: + + * ./QuarkSocPkg/QuarkNorthCluster/Binary/QuarkMicrocode/RMU.bin + +Rename the file and put it to the board directory by:: + + $ cp RMU.bin board/intel/galileo/rmu.bin + +Now you can build U-Boot and obtain u-boot.rom:: + + $ make galileo_defconfig + $ make all diff --git a/roms/u-boot/doc/board/intel/index.rst b/roms/u-boot/doc/board/intel/index.rst new file mode 100644 index 000000000..f545dee87 --- /dev/null +++ b/roms/u-boot/doc/board/intel/index.rst @@ -0,0 +1,16 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +Intel +===== + +.. toctree:: + :maxdepth: 2 + + bayleybay + cherryhill + cougarcanyon2 + crownbay + edison + galileo + minnowmax + slimbootloader diff --git a/roms/u-boot/doc/board/intel/minnowmax.rst b/roms/u-boot/doc/board/intel/minnowmax.rst new file mode 100644 index 000000000..028121735 --- /dev/null +++ b/roms/u-boot/doc/board/intel/minnowmax.rst @@ -0,0 +1,70 @@ +.. SPDX-License-Identifier: GPL-2.0+ +.. sectionauthor:: Simon Glass <sjg@chromium.org> + +Minnowboard MAX +=============== + +This uses as FSP as with Crown Bay, except it is for the Atom E3800 series. +Download this and get the .fd file (BAYTRAIL_FSP_GOLD_003_16-SEP-2014.fd at +the time of writing). Put it in the corresponding board directory and rename +it to fsp.bin. + +Obtain the VGA RAM (Vga.dat at the time of writing) and put it into the same +board directory as vga.bin. + +You still need two more binary blobs. For Minnowboard MAX, we can reuse the +same ME firmware above, but for flash descriptor, we need get that somewhere +else, as the one above does not seem to work, probably because it is not +designed for the Minnowboard MAX. Now download the original firmware image +for this board from: + + * http://firmware.intel.com/sites/default/files/2014-WW42.4-MinnowBoardMax.73-64-bit.bin_Release.zip + +Unzip it:: + + $ unzip 2014-WW42.4-MinnowBoardMax.73-64-bit.bin_Release.zip + +Use ifdtool in the U-Boot tools directory to extract the images from that +file, for example:: + + $ ./tools/ifdtool -x MNW2MAX1.X64.0073.R02.1409160934.bin + +This will provide the descriptor file - copy this into the correct place:: + + $ cp flashregion_0_flashdescriptor.bin board/intel/minnowmax/descriptor.bin + +Now you can build U-Boot and obtain u-boot.rom:: + + $ make minnowmax_defconfig + $ make all + +Checksums are as follows (but note that newer versions will invalidate this):: + + $ md5sum -b board/intel/minnowmax/*.bin + ffda9a3b94df5b74323afb328d51e6b4 board/intel/minnowmax/descriptor.bin + 69f65b9a580246291d20d08cbef9d7c5 board/intel/minnowmax/fsp.bin + 894a97d371544ec21de9c3e8e1716c4b board/intel/minnowmax/me.bin + a2588537da387da592a27219d56e9962 board/intel/minnowmax/vga.bin + +The ROM image is broken up into these parts: + +====== ================== ============================ +Offset Description Controlling config +====== ================== ============================ +000000 descriptor.bin Hard-coded to 0 in ifdtool +001000 me.bin Set by the descriptor +500000 <spare> +6ef000 Environment CONFIG_ENV_OFFSET +6f0000 MRC cache CONFIG_ENABLE_MRC_CACHE +700000 u-boot-dtb.bin CONFIG_SYS_TEXT_BASE +7b0000 vga.bin CONFIG_VGA_BIOS_ADDR +7c0000 fsp.bin CONFIG_FSP_ADDR +7f8000 <spare> (depends on size of fsp.bin) +7ff800 U-Boot 16-bit boot CONFIG_SYS_X86_START16 +====== ================== ============================ + +Overall ROM image size is controlled by CONFIG_ROM_SIZE. + +Note that the debug version of the FSP is bigger in size. If this version +is used, CONFIG_FSP_ADDR needs to be configured to 0xfffb0000 instead of +the default value 0xfffc0000. diff --git a/roms/u-boot/doc/board/intel/slimbootloader.rst b/roms/u-boot/doc/board/intel/slimbootloader.rst new file mode 100644 index 000000000..18f1cc056 --- /dev/null +++ b/roms/u-boot/doc/board/intel/slimbootloader.rst @@ -0,0 +1,177 @@ +.. SPDX-License-Identifier: GPL-2.0+ +.. sectionauthor:: Aiden Park <aiden.park@intel.com> + +Slim Bootloader +=============== + +Introduction +------------ + +This target is to enable U-Boot_ as a payload of `Slim Bootloader`_ (a.k.a SBL) +boot firmware which currently supports QEMU, Apollolake, Whiskeylake, +Coffeelake-R platforms. + +The `Slim Bootloader`_ is designed with multi-stages (Stage1A/B, Stage2, Payload) +architecture to cover from reset vector to OS booting and it consumes +`Intel FSP`_ for silicon initialization. + +* Stage1A: Reset vector, CAR init with FSP-T +* Stage1B: Memory init with FSP-M, CAR teardown, Continue execution in memory +* Stage2 : Rest of Silicon init with FSP-S, Create HOB, Hand-off to Payload +* Payload: Payload init with HOB, Load OS from media, Booting OS + +The Slim Bootloader stages (Stage1A/B, Stage2) focus on chipset, hardware and +platform specific initialization, and it provides useful information to a +payload in a HOB (Hand-Off Block) which has serial port, memory map, performance +data info and so on. This is Slim Bootloader architectural design to make a +payload light-weight, platform independent and more generic across different +boot solutions or payloads, and to minimize hardware re-initialization in a +payload. + +Build Instruction for U-Boot as a Slim Bootloader payload +--------------------------------------------------------- + +Build U-Boot and obtain u-boot-dtb.bin:: + + $ make distclean + $ make slimbootloader_defconfig + $ make all + +Prepare Slim Bootloader +----------------------- + +1. Setup Build Environment for Slim Bootloader. + + Refer to `Getting Started`_ page in `Slim Bootloader`_ document site. + +2. Get source code. Let's simply clone the repo:: + + $ git clone https://github.com/slimbootloader/slimbootloader.git + +3. Copy u-boot-dtb.bin to Slim Bootloader. + Slim Bootloader looks for a payload from the specific location. + Copy the build u-boot-dtb.bin to the expected location:: + + $ mkdir -p <Slim Bootloader Dir>/PayloadPkg/PayloadBins/ + $ cp <U-Boot Dir>/u-boot-dtb.bin <Slim Bootloader Dir>/PayloadPkg/PayloadBins/u-boot-dtb.bin + +Build Instruction for Slim Bootloader for QEMU target +----------------------------------------------------- + +Slim Bootloader supports multiple payloads, and a board of Slim Bootloader +detects its target payload by PayloadId in board configuration. +The PayloadId can be any 4 Bytes value. + +1. Update PayloadId. Let's use 'U-BT' as an example:: + + $ vi Platform/QemuBoardPkg/CfgData/CfgDataExt_Brd1.dlt + -GEN_CFG_DATA.PayloadId | 'AUTO' + +GEN_CFG_DATA.PayloadId | 'U-BT' + +2. Update payload text base. PAYLOAD_EXE_BASE must be the same as U-Boot + CONFIG_SYS_TEXT_BASE in board/intel/slimbootloader/Kconfig. + PAYLOAD_LOAD_HIGH must be 0:: + + $ vi Platform/QemuBoardPkg/BoardConfig.py + + self.PAYLOAD_LOAD_HIGH = 0 + + self.PAYLOAD_EXE_BASE = 0x00100000 + +3. Build QEMU target. Make sure u-boot-dtb.bin and U-BT PayloadId + in build command. The output is Outputs/qemu/SlimBootloader.bin:: + + $ python BuildLoader.py build qemu -p "OsLoader.efi:LLDR:Lz4;u-boot-dtb.bin:U-BT:Lzma" + +4. Launch Slim Bootloader on QEMU. + You should reach at U-Boot serial console:: + + $ qemu-system-x86_64 -machine q35 -nographic -serial mon:stdio -pflash Outputs/qemu/SlimBootloader.bin + +Test Linux booting on QEMU target +--------------------------------- + +Let's use LeafHill (APL) Yocto image for testing. +Download it from http://downloads.yoctoproject.org/releases/yocto/yocto-2.0/machines/leafhill/. + +1. Prepare Yocto hard disk image:: + + $ wget http://downloads.yoctoproject.org/releases/yocto/yocto-2.0/machines/leafhill/leafhill-4.0-jethro-2.0.tar.bz2 + $ tar -xvf leafhill-4.0-jethro-2.0.tar.bz2 + $ ls -l leafhill-4.0-jethro-2.0/binary/core-image-sato-intel-corei7-64.hddimg + +2. Launch Slim Bootloader on QEMU with disk image:: + + $ qemu-system-x86_64 -machine q35 -nographic -serial mon:stdio -pflash Outputs/qemu/SlimBootloader.bin -drive id=mydrive,if=none,file=/path/to/core-image-sato-intel-corei7-64.hddimg,format=raw -device ide-hd,drive=mydrive + +3. Update boot environment values on shell:: + + => setenv bootfile vmlinuz + => setenv bootdev scsi + => boot + +Build Instruction for Slim Bootloader for LeafHill (APL) target +--------------------------------------------------------------- + +Prepare U-Boot and Slim Bootloader as described at the beginning of this page. +Also, the PayloadId needs to be set for APL board. + +1. Update PayloadId. Let's use 'U-BT' as an example:: + + $ vi Platform/ApollolakeBoardPkg/CfgData/CfgData_Int_LeafHill.dlt + -GEN_CFG_DATA.PayloadId | 'AUTO + +GEN_CFG_DATA.PayloadId | 'U-BT' + +2. Update payload text base. + +* PAYLOAD_EXE_BASE must be the same as U-Boot CONFIG_SYS_TEXT_BASE + in board/intel/slimbootloader/Kconfig. +* PAYLOAD_LOAD_HIGH must be 0:: + + $ vi Platform/ApollolakeBoardPkg/BoardConfig.py + + self.PAYLOAD_LOAD_HIGH = 0 + + self.PAYLOAD_EXE_BASE = 0x00100000 + +3. Build APL target. Make sure u-boot-dtb.bin and U-BT PayloadId + in build command. The output is Outputs/apl/Stitch_Components.zip:: + + $ python BuildLoader.py build apl -p "OsLoader.efi:LLDR:Lz4;u-boot-dtb.bin:U-BT:Lzma" + +4. Stitch IFWI. + + Refer to Apollolake_ page in Slim Bootloader document site:: + + $ python Platform/ApollolakeBoardPkg/Script/StitchLoader.py -i <Existing IFWI> -s Outputs/apl/Stitch_Components.zip -o <Output IFWI> + +5. Flash IFWI. + + Use DediProg to flash IFWI. You should reach at U-Boot serial console. + + +Build Instruction to use ELF U-Boot +----------------------------------- + +1. Enable CONFIG_OF_EMBED:: + + $ vi configs/slimbootloader_defconfig + +CONFIG_OF_EMBED=y + +2. Build U-Boot:: + + $ make distclean + $ make slimbootloader_defconfig + $ make all + $ strip u-boot (removing symbol for reduced size) + +3. Do same steps as above + +* Copy u-boot (ELF) to PayloadBins directory +* Update PayloadId 'U-BT' as above. +* No need to set PAYLOAD_LOAD_HIGH and PAYLOAD_EXE_BASE. +* Build Slim Bootloader. Use u-boot instead of u-boot-dtb.bin:: + + $ python BuildLoader.py build <qemu or apl> -p "OsLoader.efi:LLDR:Lz4;u-boot:U-BT:Lzma" + +.. _U-Boot: https://source.denx.de/ +.. _`Slim Bootloader`: https://github.com/slimbootloader/ +.. _`Intel FSP`: https://github.com/IntelFsp/ +.. _`Getting Started`: https://slimbootloader.github.io/getting-started/ +.. _Apollolake: https://slimbootloader.github.io/supported-hardware/apollo-lake-crb.html#stitching diff --git a/roms/u-boot/doc/board/kontron/index.rst b/roms/u-boot/doc/board/kontron/index.rst new file mode 100644 index 000000000..543b22e2f --- /dev/null +++ b/roms/u-boot/doc/board/kontron/index.rst @@ -0,0 +1,9 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +Kontron +======= + +.. toctree:: + :maxdepth: 2 + + sl28 diff --git a/roms/u-boot/doc/board/kontron/sl28.rst b/roms/u-boot/doc/board/kontron/sl28.rst new file mode 100644 index 000000000..e458fbc60 --- /dev/null +++ b/roms/u-boot/doc/board/kontron/sl28.rst @@ -0,0 +1,160 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +Summary +======= + +The Kontron SMARC-sAL28 board is a TSN-enabled dual-core ARM A72 +processor module with an on-chip 6-port TSN switch and a 3D GPU. + + +Quickstart +========== + +Compile U-Boot +-------------- + +Configure and compile the binary:: + + $ make kontron_sl28_defconfig + $ CROSS_COMPILE=aarch64-linux-gnu make + +Copy u-boot.rom to a TFTP server. + +Install the bootloader on the board +----------------------------------- + +Please note, this bootloader doesn't support the builtin watchdog (yet), +therefore you have to disable it, see below. Otherwise you'll end up in +the failsafe bootloader on every reset:: + + > tftp path/to/u-boot.rom + > sf probe 0 + > sf update $fileaddr 0x210000 $filesize + +The board is fully failsafe, you can't break anything. But because you've +disabled the builtin watchdog you might have to manually enter failsafe +mode by asserting the ``FORCE_RECOV#`` line during board reset. + +Disable the builtin watchdog +---------------------------- + +- boot into the failsafe bootloader, either by asserting the + ``FORCE_RECOV#`` line or if you still have the original bootloader + installed you can use the command:: + + > wdt dev cpld_watchdog@4a; wdt expire 1 + +- in the failsafe bootloader use the "sl28 nvm" command to disable + the automatic start of the builtin watchdog:: + + > sl28 nvm 0008 + +- power-cycle the board + + +Useful I2C tricks +================= + +The board has a board management controller which is not supported in +u-boot (yet). But you can use the i2c command to access it. + +- reset into failsafe bootloader:: + + > i2c mw 4a 5.1 0; i2c mw 4a 6.1 6b; i2c mw 4a 4.1 42 + +- read board management controller version:: + + > i2c md 4a 3.1 1 + + +Non-volatile Board Configuration Bits +===================================== + +The board has 16 configuration bits which are stored in the CPLD and are +non-volatile. These can be changed by the `sl28 nvm` command. + +=== =============================================================== +Bit Description +=== =============================================================== + 0 Power-on inhibit + 1 Enable eMMC boot + 2 Enable watchdog by default + 3 Disable failsafe watchdog by default + 4 Clock generator selection bit 0 + 5 Clock generator selection bit 1 + 6 Disable CPU SerDes clock #2 and PCIe-A clock output + 7 Disable PCIe-B and PCIe-C clock output + 8 Keep onboard PHYs in reset + 9 Keep USB hub in reset + 10 Keep eDP-to-LVDS converter in reset + 11 Enable I2C stuck recovery on I2C PM and I2C GP busses + 12 Enable automatic onboard PHY H/W reset + 13 reserved + 14 Used by the RCW to determine boot source + 15 Used by the RCW to determine boot source +=== =============================================================== + +Please note, that if the board is in failsafe mode, the bits will have the +factory defaults, ie. all bits are off. + +Power-On Inhibit +---------------- + +If this is set, the board doesn't automatically turn on when power is +applied. Instead, the user has to either toggle the ``PWR_BTN#`` line or +use any other wake-up source such as RTC alarm or Wake-on-LAN. + +eMMC Boot +--------- + +If this is set, the RCW will be fetched from the on-board eMMC at offset +1MiB. For further details, have a look at the `Reset Configuration Word +Documentation`_. + +Watchdog +-------- + +By default, the CPLD watchdog is enabled in failsafe mode. Using bits 2 and +3, the user can change its mode or disable it altogether. + +===== ===== =============================== +Bit 2 Bit 3 Description +===== ===== =============================== + 0 0 Watchdog enabled, failsafe mode + 0 1 Watchdog disabled + 1 0 Watchdog enabled, failsafe mode + 1 1 Watchdog enabled, normal mode +===== ===== =============================== + +Clock Generator Select +---------------------- + +The board is prepared to supply different SerDes clock speeds. But for now, +only setting 0 is supported, otherwise the CPU will hang because the PLL +will not lock. + +Clock Output Disable And Keep Devices In Reset +---------------------------------------------- + +To safe power, the user might disable different devices and clock output of +the board. It is not supported to disable the "CPU SerDes clock #2" for +now, otherwise the CPU will hang because the PLL will not lock. + +Automatic reset of the onboard PHYs +----------------------------------- + +By default, there is no hardware reset of the onboard PHY. This is because +for Wake-on-LAN, some registers have to retain their values. If you don't +use the WOL feature and a soft reset of the PHY is not enough you can +enable the hardware reset. The onboard PHY hardware reset follows the +power-on reset. + + +Further documentation +===================== + +- `Vendor Documentation`_ +- `Reset Configuration Word Documentation`_ + +.. _Reset Configuration Word Documentation: https://raw.githubusercontent.com/kontron/rcw-smarc-sal28/master/README.md +.. _Vendor Documentation: https://raw.githubusercontent.com/kontron/u-boot-smarc-sal28/master/board/kontron/sl28/README.md diff --git a/roms/u-boot/doc/board/microchip/index.rst b/roms/u-boot/doc/board/microchip/index.rst new file mode 100644 index 000000000..affc5a9e0 --- /dev/null +++ b/roms/u-boot/doc/board/microchip/index.rst @@ -0,0 +1,9 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +Microchip +========= + +.. toctree:: + :maxdepth: 2 + + mpfs_icicle diff --git a/roms/u-boot/doc/board/microchip/mpfs_icicle.rst b/roms/u-boot/doc/board/microchip/mpfs_icicle.rst new file mode 100644 index 000000000..c71c2f3ca --- /dev/null +++ b/roms/u-boot/doc/board/microchip/mpfs_icicle.rst @@ -0,0 +1,825 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +Microchip PolarFire SoC Icicle Kit +================================== + +RISC-V PolarFire SoC +-------------------- + +The PolarFire SoC is the 4+1 64-bit RISC-V SoC from Microchip. + +The Icicle Kit development platform is based on PolarFire SoC and capable +of running Linux. + +Mainline support +---------------- + +The support for following drivers are already enabled: + +1. NS16550 UART Driver. +2. Microchip Clock Driver. +3. Cadence MACB ethernet driver for networking support. +4. Cadence MMC Driver for eMMC/SD support. + +Booting from eMMC using HSS +--------------------------- + +Building U-Boot +~~~~~~~~~~~~~~~ + +1. Add the RISC-V toolchain to your PATH. +2. Setup ARCH & cross compilation environment variable: + +.. code-block:: none + + export CROSS_COMPILE=<riscv64 toolchain prefix> + +3. make microchip_mpfs_icicle_defconfig +4. make + +Flashing +~~~~~~~~ + +The current U-Boot port is supported in S-mode only and loaded from DRAM. + +A prior stage M-mode firmware/bootloader (e.g HSS with OpenSBI) is required to +boot the u-boot.bin in S-mode. + +Currently, the u-boot.bin is used as a payload of the HSS firmware (Microchip +boot-flow) and OpenSBI generic platform fw_payload.bin (with u-boot.bin embedded) +as HSS payload (Custom boot-flow) + +Microchip boot-flow +~~~~~~~~~~~~~~~~~~~ + +HSS with OpenSBI (M-Mode) -> U-Boot (S-Mode) -> Linux (S-Mode) + +Build the HSS (Hart Software Services) - Microchip boot-flow +'''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' + +(Note: HSS git repo is at https://github.com/polarfire-soc/hart-software-services) + +1. Configure + +.. code-block:: none + + make BOARD=icicle-kit-es config + +Alternatively, copy the default config for Microchip boot-flow. + +.. code-block:: none + + cp boards/icicle-kit-es/def_config .config + +2. make BOARD=icicle-kit-es +3. In the Default subdirectory, the standard build will create hss.elf and + various binary formats (hss.hex and hss.bin). + +The FPGA design will use the hss.hex or hss.bin. + +FPGA design with HSS programming file +''''''''''''''''''''''''''''''''''''' + +https://github.com/polarfire-soc/polarfire-soc-documentation/blob/master/boards/mpfs-icicle-kit-es/updating-icicle-kit/updating-icicle-kit-design-and-linux.md + +The HSS firmware runs from the PolarFire SoC eNVM on reset. + +Creating the HSS payload - Microchip boot-flow +'''''''''''''''''''''''''''''''''''''''''''''' + +1. You will be creating a payload from `u-boot-dtb.bin`. + Copy this file to the HSS/tools/hss-payload-generator/test directory. +2. Go to hss-payload-generator source directory. + +.. code-block:: none + + cd hart-software-services/tools/hss-payload-generator + +3. Edit test/uboot.yaml file for hart entry points and correct name of the binary file. + + hart-entry-points: {u54_1: '0x80200000', u54_2: '0x80200000', u54_3: '0x80200000', u54_4: '0x80200000'} + + payloads: + test/u-boot-dtb.bin: {exec-addr: '0x80200000', owner-hart: u54_1, secondary-hart: u54_2, secondary-hart: u54_3, secondary-hart: u54_4, priv-mode: prv_s} + +4. Generate payload + +.. code-block:: none + + ./hss-payload-generator -c test/uboot.yaml payload.bin + +Once the payload binary is generated, it should be copied to the eMMC. + +Please refer to HSS documenation to build the HSS firmware for payload. +(Note: HSS git repo is at https://github.com/polarfire-soc/hart-software-services/blob/master/tools/hss-payload-generator/README.md) + +Custom boot-flow +~~~~~~~~~~~~~~~~ + +HSS without OpenSBI (M-Mode) -> OpenSBI (M-Mode) -> U-Boot (S-Mode) -> Linux (S-Mode) + +Build OpenSBI +''''''''''''' + +1. Get the OpenSBI source + +.. code-block:: none + + git clone https://github.com/riscv/opensbi.git + cd opensbi + +2. Build + +.. code-block:: none + + make PLATFORM=generic FW_PAYLOAD_PATH=<u-boot-directory>/u-boot.bin + FW_FDT_PATH=<u-boot-directory>/arch/riscv/dts/microchip-mpfs-icicle-kit-.dtb + +3. Output "fw_payload.bin" file available at + "<opensbi-directory>/build/platform/generic/firmware/fw_payload.bin" + +Build the HSS (Hart Software Services)- Custom boot-flow +'''''''''''''''''''''''''''''''''''''''''''''''''''''''' + +(Note: HSS git repo is at https://github.com/polarfire-soc/hart-software-services) + +1. Configure + +.. code-block:: none + + make BOARD=icicle-kit-es config + +Alternatively, copy the default custom config for Custom boot-flow. + +.. code-block:: none + + cp boards/icicle-kit-es/def_config_custom .config + +2. make BOARD=icicle-kit-es +3. In the Default subdirectory, the standard build will create hss.elf and + various binary formats (hss.hex and hss.bin). + +The FPGA design will use the hss.hex or hss.bin. + +Creating the HSS payload - Custom boot-flow +''''''''''''''''''''''''''''''''''''''''''' + +1. You will be creating a payload from `fw_payload.bin`. + Copy this file to the HSS/tools/hss-payload-generator/test directory. +2. Go to hss-payload-generator source directory. + +.. code-block:: none + + cd hart-software-services/tools/hss-payload-generator + +3. Edit test/uboot.yaml file for hart entry points and correct name of the binary file. + + hart-entry-points: {u54_1: '0x80000000', u54_2: '0x80000000', u54_3: '0x80000000', u54_4: '0x80000000'} + + payloads: + test/fw_payload.bin: {exec-addr: '0x80000000', owner-hart: u54_1, secondary-hart: u54_2, secondary-hart: u54_3, secondary-hart: u54_4, priv-mode: prv_m} + +4. Generate payload + +.. code-block:: none + + ./hss-payload-generator -c test/uboot.yaml payload.bin + +Once the payload binary is generated, it should be copied to the eMMC. + +Please refer to HSS documenation to build the HSS firmware for payload. +(Note: HSS git repo is at https://github.com/polarfire-soc/hart-software-services/blob/master/tools/hss-payload-generator/README.md +and also refer the HSS payload generator at https://github.com/polarfire-soc/polarfire-soc-documentation/blob/master/software-development/hss-payloads.md) + +eMMC +~~~~ + +Program eMMC with payload binary is explained in the PolarFire SoC documentation. +(Note: PolarFire SoC Documentation git repo is at https://github.com/polarfire-soc/polarfire-soc-documentation/blob/master/boards/mpfs-icicle-kit-es/updating-icicle-kit/updating-icicle-kit-design-and-linux.md#eMMC) + +Once the payload image is copied to the eMMC, press CTRL+C in the HSS command +line interface, then type 'boot' and enter to boot the newly copied image. + +.. code-block:: none + + sudo dd if=<payload_binary> of=/dev/sdX bs=512 + +GUID type +~~~~~~~~~ + +The HSS always picks up HSS payload from a GPT partition with +GIUD type "21686148-6449-6E6F-744E-656564454649" or sector '0' of the eMMC if no +GPT partition. + +Booting +~~~~~~~ + +You should see the U-Boot prompt on UART0. + +Sample boot log from MPFS Icicle Kit +'''''''''''''''''''''''''''''''''''' + +.. code-block:: none + + U-Boot 2021.01-00314-g7303332537-dirty (Jan 14 2021 - 10:09:43 +0530) + + CPU: rv64imafdc + Model: Microchip MPFS Icicle Kit + DRAM: 1 GiB + MMC: sdhc@20008000: 0 + In: serial@20100000 + Out: serial@20100000 + Err: serial@20100000 + Net: eth0: ethernet@20112000 + Hit any key to stop autoboot: 0 + +Now you can configure your networking, tftp server and use tftp boot method to +load uImage (with initramfs). + +.. code-block:: none + + RISC-V # setenv kernel_addr_r 0x80200000 + RISC-V # setenv fdt_addr_r 0x82200000 + + RISC-V # setenv ipaddr 192.168.1.5 + RISC-V # setenv netmask 255.255.255.0 + RISC-V # setenv serverip 192.168.1.3 + RISC-V # setenv gateway 192.168.1.1 + + RISC-V # tftpboot ${kernel_addr_r} uImage + ethernet@20112000: PHY present at 9 + ethernet@20112000: Starting autonegotiation... + ethernet@20112000: Autonegotiation complete + ethernet@20112000: link up, 1000Mbps full-duplex (lpa: 0x7800) + Using ethernet@20112000 device + TFTP from server 192.168.1.3; our IP address is 192.168.1.5 + Filename 'uImage'. + Load address: 0x80200000 + Loading: ################################################################# + ################################################################# + ################################################################# + ################################################################# + ################################################################# + ################################################################# + ################################################################# + ################################################################# + ################################################################# + ################################################################# + ################################################################# + ################################################################# + ################################################################# + ################################################################# + ################################################################# + ############ + 6.4 MiB/s + done + Bytes transferred = 14482480 (dcfc30 hex) + + RISC-V # tftpboot ${fdt_addr_r} microchip-mpfs-icicle-kit.dtb + ethernet@20112000: PHY present at 9 + ethernet@20112000: Starting autonegotiation... + ethernet@20112000: Autonegotiation complete + ethernet@20112000: link up, 1000Mbps full-duplex (lpa: 0x7800) + Using ethernet@20112000 device + TFTP from server 192.168.1.3; our IP address is 192.168.1.5 + Filename 'microchip-mpfs-icicle-kit.dtb'. + Load address: 0x82200000 + Loading: # + 2.5 MiB/s + done + Bytes transferred = 10282 (282a hex) + + RISC-V # bootm ${kernel_addr_r} - ${fdt_addr_r} + ## Booting kernel from Legacy Image at 80200000 ... + Image Name: Linux + Image Type: RISC-V Linux Kernel Image (uncompressed) + Data Size: 14482416 Bytes = 13.8 MiB + Load Address: 80200000 + Entry Point: 80200000 + Verifying Checksum ... OK + ## Flattened Device Tree blob at 82200000 + Booting using the fdt blob at 0x82200000 + Loading Kernel Image + Using Device Tree in place at 000000008fffa000, end 000000008ffff829 ... OK + + Starting kernel ... + + [ 0.000000] OF: fdt: Ignoring memory range 0x80000000 - 0x80200000 + [ 0.000000] Linux version 5.6.17 (padmarao@padmarao-VirtualBox) (gcc version 7.2.0 (GCC)) #2 SMP Tue Jun 16 21:27:50 IST 2020 + [ 0.000000] initrd not found or empty - disabling initrd + [ 0.000000] Zone ranges: + [ 0.000000] DMA32 [mem 0x0000000080200000-0x00000000bfffffff] + [ 0.000000] Normal empty + [ 0.000000] Movable zone start for each node + [ 0.000000] Early memory node ranges + [ 0.000000] node 0: [mem 0x0000000080200000-0x00000000bfffffff] + [ 0.000000] Initmem setup node 0 [mem 0x0000000080200000-0x00000000bfffffff] + [ 0.000000] software IO TLB: mapped [mem 0xbb1f5000-0xbf1f5000] (64MB) + [ 0.000000] elf_hwcap is 0x112d + [ 0.000000] percpu: Embedded 14 pages/cpu s24856 r0 d32488 u57344 + [ 0.000000] Built 1 zonelists, mobility grouping on. Total pages: 258055 + [ 0.000000] Kernel command line: console=ttyS0,115200n8 + [ 0.000000] Dentry cache hash table entries: 131072 (order: 8, 1048576 bytes, linear) + [ 0.000000] Inode-cache hash table entries: 65536 (order: 7, 524288 bytes, linear) + [ 0.000000] Sorting __ex_table... + [ 0.000000] mem auto-init: stack:off, heap alloc:off, heap free:off + [ 0.000000] Memory: 950308K/1046528K available (3289K kernel code, 212K rwdata, 900K rodata, 9476K init, 250K bss, 96220K reserved, 0K cma-reserved) + [ 0.000000] SLUB: HWalign=64, Order=0-3, MinObjects=0, CPUs=4, Nodes=1 + [ 0.000000] rcu: Hierarchical RCU implementation. + [ 0.000000] rcu: RCU event tracing is enabled. + [ 0.000000] rcu: RCU restricting CPUs from NR_CPUS=8 to nr_cpu_ids=4. + [ 0.000000] rcu: RCU calculated value of scheduler-enlistment delay is 10 jiffies. + [ 0.000000] rcu: Adjusting geometry for rcu_fanout_leaf=16, nr_cpu_ids=4 + [ 0.000000] NR_IRQS: 0, nr_irqs: 0, preallocated irqs: 0 + [ 0.000000] plic: mapped 186 interrupts with 4 handlers for 9 contexts. + [ 0.000000] riscv_timer_init_dt: Registering clocksource cpuid [0] hartid [1] + [ 0.000000] clocksource: riscv_clocksource: mask: 0xffffffffffffffff max_cycles: 0x1d854df40, max_idle_ns: 3526361616960 ns + [ 0.000015] sched_clock: 64 bits at 1000kHz, resolution 1000ns, wraps every 2199023255500ns + [ 0.000311] Calibrating delay loop (skipped), value calculated using timer frequency.. 2.00 BogoMIPS (lpj=10000) + [ 0.000349] pid_max: default: 32768 minimum: 301 + [ 0.000846] Mount-cache hash table entries: 2048 (order: 2, 16384 bytes, linear) + [ 0.000964] Mountpoint-cache hash table entries: 2048 (order: 2, 16384 bytes, linear) + [ 0.005630] rcu: Hierarchical SRCU implementation. + [ 0.006901] smp: Bringing up secondary CPUs ... + [ 0.012545] smp: Brought up 1 node, 4 CPUs + [ 0.014431] devtmpfs: initialized + [ 0.020526] random: get_random_bytes called from setup_net+0x36/0x192 with crng_init=0 + [ 0.020928] clocksource: jiffies: mask: 0xffffffff max_cycles: 0xffffffff, max_idle_ns: 19112604462750000 ns + [ 0.020999] futex hash table entries: 1024 (order: 4, 65536 bytes, linear) + [ 0.022768] NET: Registered protocol family 16 + [ 0.035478] microchip-pfsoc-clkcfg 20002000.clkcfg: Registered PFSOC core clocks + [ 0.048429] SCSI subsystem initialized + [ 0.049694] pps_core: LinuxPPS API ver. 1 registered + [ 0.049719] pps_core: Software ver. 5.3.6 - Copyright 2005-2007 Rodolfo Giometti <giometti@linux.it> + [ 0.049780] PTP clock support registered + [ 0.051781] clocksource: Switched to clocksource riscv_clocksource + [ 0.055326] NET: Registered protocol family 2 + [ 0.056922] tcp_listen_portaddr_hash hash table entries: 512 (order: 1, 8192 bytes, linear) + [ 0.057053] TCP established hash table entries: 8192 (order: 4, 65536 bytes, linear) + [ 0.057648] TCP bind hash table entries: 8192 (order: 5, 131072 bytes, linear) + [ 0.058579] TCP: Hash tables configured (established 8192 bind 8192) + [ 0.059648] UDP hash table entries: 512 (order: 2, 16384 bytes, linear) + [ 0.059837] UDP-Lite hash table entries: 512 (order: 2, 16384 bytes, linear) + [ 0.060707] NET: Registered protocol family 1 + [ 0.266229] workingset: timestamp_bits=62 max_order=18 bucket_order=0 + [ 0.287107] io scheduler mq-deadline registered + [ 0.287140] io scheduler kyber registered + [ 0.429601] Serial: 8250/16550 driver, 4 ports, IRQ sharing disabled + [ 0.433979] printk: console [ttyS0] disabled + [ 0.434154] 20000000.serial: ttyS0 at MMIO 0x20000000 (irq = 18, base_baud = 9375000) is a 16550A + [ 0.928039] printk: console [ttyS0] enabled + [ 0.939804] libphy: Fixed MDIO Bus: probed + [ 0.948702] libphy: MACB_mii_bus: probed + [ 0.993698] macb 20112000.ethernet eth0: Cadence GEM rev 0x0107010c at 0x20112000 irq 21 (56:34:12:00:fc:00) + [ 1.006751] mousedev: PS/2 mouse device common for all mice + [ 1.013803] i2c /dev entries driver + [ 1.019451] sdhci: Secure Digital Host Controller Interface driver + [ 1.027242] sdhci: Copyright(c) Pierre Ossman + [ 1.032731] sdhci-pltfm: SDHCI platform and OF driver helper + [ 1.091826] mmc0: SDHCI controller on 20008000.sdhc [20008000.sdhc] using ADMA 64-bit + [ 1.102738] NET: Registered protocol family 17 + [ 1.170326] Freeing unused kernel memory: 9476K + [ 1.176067] This architecture does not have kernel memory protection. + [ 1.184157] Run /init as init process + Starting logging: OK + Starting mdev... + /etc/init.d/S10mdev: line 21: can't create /proc/sys/kernel/hotplug: nonexiste[ 1.331981] mmc0: mmc_select_hs200 failed, error -74 + nt directory + [ 1.355011] mmc0: new MMC card at address 0001 + [ 1.363981] mmcblk0: mmc0:0001 DG4008 7.28 GiB + [ 1.372248] mmcblk0boot0: mmc0:0001 DG4008 partition 1 4.00 MiB + [ 1.382292] mmcblk0boot1: mmc0:0001 DG4008 partition 2 4.00 MiB + [ 1.390265] mmcblk0rpmb: mmc0:0001 DG4008 partition 3 4.00 MiB, chardev (251:0) + [ 1.425234] GPT:Primary header thinks Alt. header is not at the end of the disk. + [ 1.434656] GPT:2255809 != 15273599 + [ 1.439038] GPT:Alternate GPT header not at the end of the disk. + [ 1.446671] GPT:2255809 != 15273599 + [ 1.451048] GPT: Use GNU Parted to correct GPT errors. + [ 1.457755] mmcblk0: p1 p2 p3 + sort: /sys/devices/platform/Fixed: No such file or directory + modprobe: can't change directory to '/lib/modules': No such file or directory + Initializing random number generator... [ 2.830198] random: dd: uninitialized urandom read (512 bytes read) + done. + Starting network... + [ 3.061867] macb 20112000.ethernet eth0: PHY [20112000.ethernet-ffffffff:09] driver [Vitesse VSC8662] (irq=POLL) + [ 3.074674] macb 20112000.ethernet eth0: configuring for phy/sgmii link mode + [ 3.084263] pps pps0: new PPS source ptp0 + [ 3.089710] macb 20112000.ethernet: gem-ptp-timer ptp clock registered. + udhcpc (v1.24.2) started + Sending discover... + Sending discover... + [ 6.380169] macb 20112000.ethernet eth0: Link is Up - 1Gbps/Full - flow control tx + Sending discover... + Sending select for 192.168.1.2... + Lease of 192.168.1.2 obtained, lease time 86400 + deleting routers + adding dns 192.168.1.1 + Starting dropbear sshd: [ 11.385619] random: dropbear: uninitialized urandom read (32 bytes read) + OK + + Welcome to Buildroot + buildroot login: root + Password: + # + +Booting U-Boot and Linux from eMMC +---------------------------------- + +FPGA design with HSS programming file and Linux Image +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +https://github.com/polarfire-soc/polarfire-soc-documentation/blob/master/boards/mpfs-icicle-kit-es/updating-icicle-kit/updating-icicle-kit-design-and-linux.md + +The HSS firmware runs from the PolarFire SoC eNVM on reset. + +eMMC +~~~~ + +Program eMMC with payload binary and Linux image is explained in the +PolarFire SoC documentation. +The payload binary should be copied to partition 2 of the eMMC. + +(Note: PolarFire SoC Documentation git repo is at https://github.com/polarfire-soc/polarfire-soc-documentation/blob/master/boards/mpfs-icicle-kit-es/updating-icicle-kit/updating-icicle-kit-design-and-linux.md#eMMC) + +Once the Linux image and payload binary is copied to the eMMC, press CTRL+C +in the HSS command line interface, then type 'boot' and enter to boot the newly +copied payload and Linux image. + +.. code-block:: none + + zcat <linux-image>.wic.gz | sudo dd of=/dev/sdX bs=4096 iflag=fullblock oflag=direct conv=fsync status=progress + + sudo dd if=<payload_binary> of=/dev/sdX2 bs=512 + +You should see the U-Boot prompt on UART0. + +GUID type +~~~~~~~~~ + +The HSS always picks up the HSS payload from a GPT partition with +GIUD type "21686148-6449-6E6F-744E-656564454649" or sector '0' of the eMMC if no +GPT partition. + +Sample boot log from MPFS Icicle Kit +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. code-block:: none + + U-Boot 2021.01-00314-g7303332537-dirty (Jan 14 2021 - 10:09:43 +0530) + + CPU: rv64imafdc + Model: Microchip MPFS Icicle Kit + DRAM: 1 GiB + MMC: sdhc@20008000: 0 + In: serial@20100000 + Out: serial@20100000 + Err: serial@20100000 + Net: eth0: ethernet@20112000 + Hit any key to stop autoboot: 0 + + RISC-V # mmc info + Device: sdhc@20008000 + Manufacturer ID: 45 + OEM: 100 + Name: DG400 + Bus Speed: 52000000 + Mode: MMC High Speed (52MHz) + Rd Block Len: 512 + MMC version 5.1 + High Capacity: Yes + Capacity: 7.3 GiB + Bus Width: 4-bit + Erase Group Size: 512 KiB + HC WP Group Size: 8 MiB + User Capacity: 7.3 GiB WRREL + Boot Capacity: 4 MiB ENH + RPMB Capacity: 4 MiB ENH + + RISC-V # mmc part + Partition Map for MMC device 0 -- Partition Type: EFI + + Part Start LBA End LBA Name + Attributes + Type GUID + Partition GUID + 1 0x00002000 0x0000b031 "boot" + attrs: 0x0000000000000004 + type: ebd0a0a2-b9e5-4433-87c0-68b6b72699c7 + guid: 99ff6a94-f2e7-44dd-a7df-f3a2da106ef9 + 2 0x0000b032 0x0000f031 "primary" + attrs: 0x0000000000000000 + type: 21686148-6449-6e6f-744e-656564454649 + guid: 12006052-e64b-4423-beb0-b956ea00f1ba + 3 0x00010000 0x00226b9f "root" + attrs: 0x0000000000000000 + type: 0fc63daf-8483-4772-8e79-3d69d8477de4 + guid: dd2c5619-2272-4c3c-8dc2-e21942e17ce6 + + RISC-V # load mmc 0 ${ramdisk_addr_r} fitimage + RISC-V # bootm ${ramdisk_addr_r} + ## Loading kernel from FIT Image at 88300000 ... + Using 'conf@microchip_icicle-kit-es-a000-microchip.dtb' configuration + Trying 'kernel@1' kernel subimage + Description: Linux kernel + Type: Kernel Image + Compression: gzip compressed + Data Start: 0x883000fc + Data Size: 3574555 Bytes = 3.4 MiB + Architecture: RISC-V + OS: Linux + Load Address: 0x80200000 + Entry Point: 0x80200000 + Hash algo: sha256 + Hash value: 21f18d72cf2f0a7192220abb577ad25c77c26960052d779aa02bf55dbf0a6403 + Verifying Hash Integrity ... sha256+ OK + ## Loading fdt from FIT Image at 88300000 ... + Using 'conf@microchip_icicle-kit-es-a000-microchip.dtb' configuration + Trying 'fdt@microchip_icicle-kit-es-a000-microchip.dtb' fdt subimage + Description: Flattened Device Tree blob + Type: Flat Device Tree + Compression: uncompressed + Data Start: 0x88668d44 + Data Size: 9760 Bytes = 9.5 KiB + Architecture: RISC-V + Load Address: 0x82200000 + Hash algo: sha256 + Hash value: 5c3a9f30d41b6b8e53b47916e1f339b3a4d454006554d1f7e1f552ed62409f4b + Verifying Hash Integrity ... sha256+ OK + Loading fdt from 0x88668d48 to 0x82200000 + Booting using the fdt blob at 0x82200000 + Uncompressing Kernel Image + Loading Device Tree to 000000008fffa000, end 000000008ffff61f ... OK + + Starting kernel ... + + [ 0.000000] OF: fdt: Ignoring memory range 0x80000000 - 0x80200000 + [ 0.000000] Linux version 5.6.16 (oe-user@oe-host) (gcc version 9.3.0 (GCC)) #1 SMP Fri Oct 9 11:49:47 UTC 2020 + [ 0.000000] earlycon: sbi0 at I/O port 0x0 (options '') + [ 0.000000] printk: bootconsole [sbi0] enabled + [ 0.000000] Zone ranges: + [ 0.000000] DMA32 [mem 0x0000000080200000-0x00000000bfffffff] + [ 0.000000] Normal empty + [ 0.000000] Movable zone start for each node + [ 0.000000] Early memory node ranges + [ 0.000000] node 0: [mem 0x0000000080200000-0x00000000bfffffff] + [ 0.000000] Zeroed struct page in unavailable ranges: 512 pages + [ 0.000000] Initmem setup node 0 [mem 0x0000000080200000-0x00000000bfffffff] + [ 0.000000] software IO TLB: mapped [mem 0xb9e00000-0xbde00000] (64MB) + [ 0.000000] CPU with hartid=0 is not available + [ 0.000000] CPU with hartid=0 is not available + [ 0.000000] elf_hwcap is 0x112d + [ 0.000000] percpu: Embedded 17 pages/cpu s29784 r8192 d31656 u69632 + [ 0.000000] Built 1 zonelists, mobility grouping on. Total pages: 258055 + [ 0.000000] Kernel command line: earlycon=sbi root=/dev/mmcblk0p3 rootwait console=ttyS0,115200n8 uio_pdrv_genirq.of_id=generic-uio + [ 0.000000] Dentry cache hash table entries: 131072 (order: 8, 1048576 bytes, linear) + [ 0.000000] Inode-cache hash table entries: 65536 (order: 7, 524288 bytes, linear) + [ 0.000000] Sorting __ex_table... + [ 0.000000] mem auto-init: stack:off, heap alloc:off, heap free:off + [ 0.000000] Memory: 941440K/1046528K available (4118K kernel code, 280K rwdata, 1687K rodata, 169K init, 273K bss, 105088K reserved, 0K cma-reserved) + [ 0.000000] SLUB: HWalign=64, Order=0-3, MinObjects=0, CPUs=4, Nodes=1 + [ 0.000000] rcu: Hierarchical RCU implementation. + [ 0.000000] rcu: RCU event tracing is enabled. + [ 0.000000] rcu: RCU restricting CPUs from NR_CPUS=5 to nr_cpu_ids=4. + [ 0.000000] rcu: RCU calculated value of scheduler-enlistment delay is 10 jiffies. + [ 0.000000] rcu: Adjusting geometry for rcu_fanout_leaf=16, nr_cpu_ids=4 + [ 0.000000] NR_IRQS: 0, nr_irqs: 0, preallocated irqs: 0 + [ 0.000000] plic: mapped 53 interrupts with 4 handlers for 9 contexts. + [ 0.000000] riscv_timer_init_dt: Registering clocksource cpuid [0] hartid [1] + [ 0.000000] clocksource: riscv_clocksource: mask: 0xffffffffffffffff max_cycles: 0x1d854df40, max_idle_ns: 3526361616960 ns + [ 0.000015] sched_clock: 64 bits at 1000kHz, resolution 1000ns, wraps every 2199023255500ns + [ 0.008679] Console: colour dummy device 80x25 + [ 0.013112] Calibrating delay loop (skipped), value calculated using timer frequency.. 2.00 BogoMIPS (lpj=10000) + [ 0.023368] pid_max: default: 32768 minimum: 301 + [ 0.028314] Mount-cache hash table entries: 2048 (order: 2, 16384 bytes, linear) + [ 0.035766] Mountpoint-cache hash table entries: 2048 (order: 2, 16384 bytes, linear) + [ 0.047099] rcu: Hierarchical SRCU implementation. + [ 0.052813] smp: Bringing up secondary CPUs ... + [ 0.061581] smp: Brought up 1 node, 4 CPUs + [ 0.067069] devtmpfs: initialized + [ 0.073621] random: get_random_u32 called from bucket_table_alloc.isra.0+0x4e/0x150 with crng_init=0 + [ 0.074409] clocksource: jiffies: mask: 0xffffffff max_cycles: 0xffffffff, max_idle_ns: 19112604462750000 ns + [ 0.093399] futex hash table entries: 1024 (order: 4, 65536 bytes, linear) + [ 0.101879] NET: Registered protocol family 16 + [ 0.110336] microchip-pfsoc-clkcfg 20002000.clkcfg: Registered PFSOC core clocks + [ 0.132717] usbcore: registered new interface driver usbfs + [ 0.138225] usbcore: registered new interface driver hub + [ 0.143813] usbcore: registered new device driver usb + [ 0.148939] pps_core: LinuxPPS API ver. 1 registered + [ 0.153929] pps_core: Software ver. 5.3.6 - Copyright 2005-2007 Rodolfo Giometti <giometti@linux.it> + [ 0.163071] PTP clock support registered + [ 0.168521] clocksource: Switched to clocksource riscv_clocksource + [ 0.174927] VFS: Disk quotas dquot_6.6.0 + [ 0.179016] VFS: Dquot-cache hash table entries: 512 (order 0, 4096 bytes) + [ 0.205536] NET: Registered protocol family 2 + [ 0.210944] tcp_listen_portaddr_hash hash table entries: 512 (order: 1, 8192 bytes, linear) + [ 0.219393] TCP established hash table entries: 8192 (order: 4, 65536 bytes, linear) + [ 0.227497] TCP bind hash table entries: 8192 (order: 5, 131072 bytes, linear) + [ 0.235440] TCP: Hash tables configured (established 8192 bind 8192) + [ 0.242537] UDP hash table entries: 512 (order: 2, 16384 bytes, linear) + [ 0.249285] UDP-Lite hash table entries: 512 (order: 2, 16384 bytes, linear) + [ 0.256690] NET: Registered protocol family 1 + [ 0.262585] workingset: timestamp_bits=62 max_order=18 bucket_order=0 + [ 0.281036] Block layer SCSI generic (bsg) driver version 0.4 loaded (major 249) + [ 0.288481] io scheduler mq-deadline registered + [ 0.292983] io scheduler kyber registered + [ 0.298895] microsemi,mss-gpio 20122000.gpio: Microsemi MSS GPIO registered 32 GPIOs + [ 0.453723] Serial: 8250/16550 driver, 4 ports, IRQ sharing disabled + [ 0.462911] printk: console [ttyS0] disabled + [ 0.467216] 20100000.serial: ttyS0 at MMIO 0x20100000 (irq = 12, base_baud = 9375000) is a 16550A + [ 0.476201] printk: console [ttyS0] enabled + [ 0.476201] printk: console [ttyS0] enabled + [ 0.484576] printk: bootconsole [sbi0] disabled + [ 0.484576] printk: bootconsole [sbi0] disabled + [ 0.494920] 20102000.serial: ttyS1 at MMIO 0x20102000 (irq = 13, base_baud = 9375000) is a 16550A + [ 0.505068] 20104000.serial: ttyS2 at MMIO 0x20104000 (irq = 14, base_baud = 9375000) is a 16550A + [ 0.533336] loop: module loaded + [ 0.572284] Rounding down aligned max_sectors from 4294967295 to 4294967288 + [ 0.580000] db_root: cannot open: /etc/target + [ 0.585413] libphy: Fixed MDIO Bus: probed + [ 0.591526] libphy: MACB_mii_bus: probed + [ 0.598060] macb 20112000.ethernet eth0: Cadence GEM rev 0x0107010c at 0x20112000 irq 17 (56:34:12:00:fc:00) + [ 0.608352] ehci_hcd: USB 2.0 'Enhanced' Host Controller (EHCI) Driver + [ 0.615001] ehci-platform: EHCI generic platform driver + [ 0.620446] ohci_hcd: USB 1.1 'Open' Host Controller (OHCI) Driver + [ 0.626632] ohci-platform: OHCI generic platform driver + [ 0.632326] usbcore: registered new interface driver cdc_acm + [ 0.637996] cdc_acm: USB Abstract Control Model driver for USB modems and ISDN adapters + [ 0.646459] i2c /dev entries driver + [ 0.650852] microsemi-mss-i2c 2010b000.i2c: Microsemi I2C Probe Complete + [ 0.658010] sdhci: Secure Digital Host Controller Interface driver + [ 0.664326] sdhci: Copyright(c) Pierre Ossman + [ 0.668754] sdhci-pltfm: SDHCI platform and OF driver helper + [ 0.706845] mmc0: SDHCI controller on 20008000.sdhc [20008000.sdhc] using ADMA 64-bit + [ 0.715052] usbcore: registered new interface driver usbhid + [ 0.720722] usbhid: USB HID core driver + [ 0.725174] pac193x 0-0010: Chip revision: 0x03 + [ 0.733339] pac193x 0-0010: :pac193x_prep_iio_channels: Channel 0 active + [ 0.740127] pac193x 0-0010: :pac193x_prep_iio_channels: Channel 1 active + [ 0.746881] pac193x 0-0010: :pac193x_prep_iio_channels: Channel 2 active + [ 0.753686] pac193x 0-0010: :pac193x_prep_iio_channels: Channel 3 active + [ 0.760495] pac193x 0-0010: :pac193x_prep_iio_channels: Active chip channels: 25 + [ 0.778006] NET: Registered protocol family 10 + [ 0.784929] Segment Routing with IPv6 + [ 0.788875] sit: IPv6, IPv4 and MPLS over IPv4 tunneling driver + [ 0.795743] NET: Registered protocol family 17 + [ 0.801191] hctosys: unable to open rtc device (rtc0) + [ 0.807774] Waiting for root device /dev/mmcblk0p3... + [ 0.858506] mmc0: mmc_select_hs200 failed, error -74 + [ 0.865764] mmc0: new MMC card at address 0001 + [ 0.872564] mmcblk0: mmc0:0001 DG4008 7.28 GiB + [ 0.878777] mmcblk0boot0: mmc0:0001 DG4008 partition 1 4.00 MiB + [ 0.886182] mmcblk0boot1: mmc0:0001 DG4008 partition 2 4.00 MiB + [ 0.892633] mmcblk0rpmb: mmc0:0001 DG4008 partition 3 4.00 MiB, chardev (247:0) + [ 0.919029] GPT:Primary header thinks Alt. header is not at the end of the disk. + [ 0.926448] GPT:2255841 != 15273599 + [ 0.930019] GPT:Alternate GPT header not at the end of the disk. + [ 0.936029] GPT:2255841 != 15273599 + [ 0.939583] GPT: Use GNU Parted to correct GPT errors. + [ 0.944800] mmcblk0: p1 p2 p3 + [ 0.966696] EXT4-fs (mmcblk0p3): INFO: recovery required on readonly filesystem + [ 0.974105] EXT4-fs (mmcblk0p3): write access will be enabled during recovery + [ 1.052362] random: fast init done + [ 1.057961] EXT4-fs (mmcblk0p3): recovery complete + [ 1.065734] EXT4-fs (mmcblk0p3): mounted filesystem with ordered data mode. Opts: (null) + [ 1.074002] VFS: Mounted root (ext4 filesystem) readonly on device 179:3. + [ 1.081654] Freeing unused kernel memory: 168K + [ 1.086108] This architecture does not have kernel memory protection. + [ 1.092629] Run /sbin/init as init process + [ 1.702217] systemd[1]: System time before build time, advancing clock. + [ 1.754192] systemd[1]: systemd 244.3+ running in system mode. (+PAM -AUDIT -SELINUX +IMA -APPARMOR -SMACK +SYSVINIT +UTMP -LIBCRYPTSETUP -GCRYPT -GNUTLS +ACL +XZ -LZ4 -SECCOMP +BLKID -ELFUTILS +KMOD -IDN2 -IDN -PCRE2 default-hierarchy=hybrid) + [ 1.776361] systemd[1]: Detected architecture riscv64. + + Welcome to OpenEmbedded nodistro.0! + + [ 1.829651] systemd[1]: Set hostname to <icicle-kit-es>. + [ 2.648597] random: systemd: uninitialized urandom read (16 bytes read) + [ 2.657485] systemd[1]: Created slice system-getty.slice. + [ OK ] Created slice system-getty.slice. + [ 2.698779] random: systemd: uninitialized urandom read (16 bytes read) + [ 2.706317] systemd[1]: Created slice system-serial\x2dgetty.slice. + [ OK ] Created slice system-serial\x2dgetty.slice. + [ 2.748716] random: systemd: uninitialized urandom read (16 bytes read) + [ 2.756098] systemd[1]: Created slice User and Session Slice. + [ OK ] Created slice User and Session Slice. + [ 2.789065] systemd[1]: Started Dispatch Password Requests to Console Directory Watch. + [ OK ] Started Dispatch Password …ts to Console Directory Watch. + [ 2.828974] systemd[1]: Started Forward Password Requests to Wall Directory Watch. + [ OK ] Started Forward Password R…uests to Wall Directory Watch. + [ 2.869009] systemd[1]: Reached target Paths. + [ OK ] Reached target Paths. + [ 2.898808] systemd[1]: Reached target Remote File Systems. + [ OK ] Reached target Remote File Systems. + [ 2.938771] systemd[1]: Reached target Slices. + [ OK ] Reached target Slices. + [ 2.968754] systemd[1]: Reached target Swap. + [ OK ] Reached target Swap. + [ 2.999283] systemd[1]: Listening on initctl Compatibility Named Pipe. + [ OK ] Listening on initctl Compatibility Named Pipe. + [ 3.060458] systemd[1]: Condition check resulted in Journal Audit Socket being skipped. + [ 3.069826] systemd[1]: Listening on Journal Socket (/dev/log). + [ OK ] Listening on Journal Socket (/dev/log). + [ 3.109601] systemd[1]: Listening on Journal Socket. + [ OK ] Listening on Journal Socket. + [ 3.149868] systemd[1]: Listening on Network Service Netlink Socket. + [ OK ] Listening on Network Service Netlink Socket. + [ 3.189419] systemd[1]: Listening on udev Control Socket. + [ OK ] Listening on udev Control Socket. + [ 3.229179] systemd[1]: Listening on udev Kernel Socket. + [ OK ] Listening on udev Kernel Socket. + [ 3.269520] systemd[1]: Condition check resulted in Huge Pages File System being skipped. + [ 3.278477] systemd[1]: Condition check resulted in POSIX Message Queue File System being skipped. + [ 3.288200] systemd[1]: Condition check resulted in Kernel Debug File System being skipped. + [ 3.302570] systemd[1]: Mounting Temporary Directory (/tmp)... + Mounting Temporary Directory (/tmp)... + [ 3.339226] systemd[1]: Condition check resulted in Create list of static device nodes for the current kernel being skipped. + [ 3.355883] systemd[1]: Starting File System Check on Root Device... + Starting File System Check on Root Device... + [ 3.407220] systemd[1]: Starting Journal Service... + Starting Journal Service... + [ 3.422441] systemd[1]: Condition check resulted in Load Kernel Modules being skipped. + [ 3.431770] systemd[1]: Condition check resulted in FUSE Control File System being skipped. + [ 3.446415] systemd[1]: Mounting Kernel Configuration File System... + Mounting Kernel Configuration File System... + [ 3.458983] systemd[1]: Starting Apply Kernel Variables... + Starting Apply Kernel Variables... + [ 3.471368] systemd[1]: Starting udev Coldplug all Devices... + Starting udev Coldplug all Devices... + [ 3.491071] systemd[1]: Mounted Temporary Directory (/tmp). + [ OK 3.498114] systemd[1]: Mounted Kernel Configuration File System. + 0m] Mounted Temporary Directory (/tmp). + [ OK ] Mounted Kernel Configuration File System. + [ 3.550853] systemd[1]: Started Apply Kernel Variables. + [ OK 3.557535] systemd[1]: Started Journal Service. + 0m] Started Apply Kernel Variables. + [ OK ] Started Journal Service. + [ OK ] Started udev Coldplug all Devices. + [ OK ] Started File System Check on Root Device. + Starting Remount Root and Kernel File Systems... + [ 8.133469] EXT4-fs (mmcblk0p3): re-mounted. Opts: (null) + [ OK ] Started Remount Root and Kernel File Systems. + Starting Flush Journal to Persistent Storage... + [ 8.215327] systemd-journald[77]: Received client request to flush runtime journal. + Starting Create Static Device Nodes in /dev... + [ OK ] Started Flush Journal to Persistent Storage. + [ OK ] Started Create Static Device Nodes in /dev. + [ OK ] Reached target Local File Systems (Pre). + Mounting /var/volatile... + Starting udev Kernel Device Manager... + [ OK ] Mounted /var/volatile. + Starting Load/Save Random Seed... + [ OK ] Reached target Local File Systems. + Starting Create Volatile Files and Directories... + [ OK ] Started udev Kernel Device Manager. + [ OK ] Started Create Volatile Files and Directories. + Starting Network Time Synchronization... + Starting Update UTMP about System Boot/Shutdown... + [ OK ] Started Update UTMP about System Boot/Shutdown. + [ OK ] Started Network Time Synchronization. + [ 11.618575] random: crng init done + [ 11.622007] random: 7 urandom warning(s) missed due to ratelimiting + [ OK ] Started Load/Save Random Seed. + [ OK ] Reached target System Initialization. + [ OK ] Started Daily Cleanup of Temporary Directories. + [ OK ] Reached target System Time Set. + [ OK ] Reached target System Time Synchronized. + [ OK ] Reached target Timers. + [ OK ] Listening on D-Bus System Message Bus Socket. + [ OK ] Listening on dropbear.socket. + [ OK ] Reached target Sockets. + [ OK ] Reached target Basic System. + [ OK ] Started D-Bus System Message Bus. + Starting IPv6 Packet Filtering Framework... + Starting IPv4 Packet Filtering Framework... + Starting Login Service... + [ OK ] Started IPv6 Packet Filtering Framework. + [ OK ] Started IPv4 Packet Filtering Framework. + [ OK ] Reached target Network (Pre). + Starting Network Service... + [ OK ] Started Login Service. + [ 12.602455] macb 20112000.ethernet eth0: PHY [20112000.ethernet-ffffffff:09] driver [Vitesse VSC8662] (irq=POLL) + [ 12.612795] macb 20112000.ethernet eth0: configuring for phy/sgmii link mode + [ 12.622153] pps pps0: new PPS source ptp0 + [ OK 12.626725] macb 20112000.ethernet: gem-ptp-timer ptp clock registered. + 0m] Started Network Service. + Starting Network Name Resolution... + [ OK ] Started Network Name Resolution. + [ OK ] Reached target Network. + [ OK ] Reached target Host and Network Name Lookups. + [ OK ] Started Collectd. + [ OK ] Started Collectd. + Starting Permit User Sessions... + [ OK ] Started Permit User Sessions. + [ OK ] Started Getty on tty1. + [ OK ] Started Serial Getty on ttyS0. + [ OK ] Reached target Login Prompts. + [ OK ] Reached target Multi-User System. + Starting Update UTMP about System Runlevel Changes... + [ OK ] Started Update UTMP about System Runlevel Changes. + + OpenEmbedded nodistro.0 icicle-kit-es ttyS0 + + icicle-kit-es login: [ 15.795564] macb 20112000.ethernet eth0: Link is Up - 1Gbps/Full - flow control tx + [ 15.803306] IPv6: ADDRCONF(NETDEV_CHANGE): eth0: link becomes ready + + icicle-kit-es login: root + root@icicle-kit-es:~# diff --git a/roms/u-boot/doc/board/rockchip/index.rst b/roms/u-boot/doc/board/rockchip/index.rst new file mode 100644 index 000000000..0c377e9bb --- /dev/null +++ b/roms/u-boot/doc/board/rockchip/index.rst @@ -0,0 +1,10 @@ +.. SPDX-License-Identifier: GPL-2.0+ +.. Copyright (C) 2019 Jagan Teki <jagan@amarulasolutions.com> + +Rockchip +======== + +.. toctree:: + :maxdepth: 2 + + rockchip diff --git a/roms/u-boot/doc/board/rockchip/rockchip.rst b/roms/u-boot/doc/board/rockchip/rockchip.rst new file mode 100644 index 000000000..fbb998398 --- /dev/null +++ b/roms/u-boot/doc/board/rockchip/rockchip.rst @@ -0,0 +1,238 @@ +.. SPDX-License-Identifier: GPL-2.0+ +.. Copyright (C) 2019 Jagan Teki <jagan@amarulasolutions.com> + +ROCKCHIP +======== + +About this +---------- + +This document describes the information about Rockchip supported boards +and it's usage steps. + +Rockchip boards +--------------- + +Rockchip is SoC solutions provider for tablets & PCs, streaming media +TV boxes, AI audio & vision, IoT hardware. + +A wide range of Rockchip SoCs with associated boardsare supported in +mainline U-Boot. + +List of mainline supported rockchip boards: + +* rk3036 + - Rockchip Evb-RK3036 (evb-rk3036) + - Kylin (kylin_rk3036) +* rk3128 + - Rockchip Evb-RK3128 (evb-rk3128) +* rk3229 + - Rockchip Evb-RK3229 (evb-rk3229) +* rk3288 + - Rockchip Evb-RK3288 (evb-rk3288) + - Firefly-RK3288 (firefly-rk3288) + - MQmaker MiQi (miqi-rk3288) + - Phytec RK3288 PCM-947 (phycore-rk3288) + - PopMetal-RK3288 (popmetal-rk3288) + - Radxa Rock 2 Square (rock2) + - Tinker-RK3288 (tinker-rk3288) + - Google Jerry (chromebook_jerry) + - Google Mickey (chromebook_mickey) + - Google Minnie (chromebook_minnie) + - Google Speedy (chromebook_speedy) + - Amarula Vyasa-RK3288 (vyasa-rk3288) +* rk3308 + - Rockchip Evb-RK3308 (evb-rk3308) + - Roc-cc-RK3308 (roc-cc-rk3308) +* rk3328 + - Rockchip Evb-RK3328 (evb-rk3328) + - Pine64 Rock64 (rock64-rk3328) + - Firefly-RK3328 (roc-cc-rk3328) + - Radxa Rockpi E (rock-pi-e-rk3328) +* rk3368 + - GeekBox (geekbox) + - PX5 EVB (evb-px5) + - Rockchip Sheep (sheep-rk3368) + - Theobroma Systems RK3368-uQ7 SoM - Lion (lion-rk3368) +* rk3399 + - 96boards RK3399 Ficus (ficus-rk3399) + - 96boards Rock960 (rock960-rk3399) + - Firefly-RK3399 (firefly_rk3399) + - Firefly ROC-RK3399-PC + - FriendlyElec NanoPC-T4 (nanopc-t4-rk3399) + - FriendlyElec NanoPi M4 (nanopi-m4-rk3399) + - FriendlyElec NanoPi M4B (nanopi-m4b-rk3399) + - FriendlyARM NanoPi NEO4 (nanopi-neo4-rk3399) + - Google Bob (chromebook_bob) + - Khadas Edge (khadas-edge-rk3399) + - Khadas Edge-Captain (khadas-edge-captain-rk3399) + - Khadas Edge-V (hadas-edge-v-rk3399) + - Orange Pi RK3399 (orangepi-rk3399) + - Pine64 RockPro64 (rockpro64-rk3399) + - Radxa ROCK Pi 4 (rock-pi-4-rk3399) + - Rockchip Evb-RK3399 (evb_rk3399) + - Theobroma Systems RK3399-Q7 SoM - Puma (puma_rk3399) +* rv1108 + - Rockchip Evb-rv1108 (evb-rv1108) + - Elgin-R1 (elgin-rv1108) +* rv3188 + - Radxa Rock (rock) + +Building +-------- + +TF-A +^^^^ + +TF-A would require to build for ARM64 Rockchip SoCs platforms. + +To build TF-A:: + + git clone https://github.com/ARM-software/arm-trusted-firmware.git + cd arm-trusted-firmware + make realclean + make CROSS_COMPILE=aarch64-linux-gnu- PLAT=rk3399 + +Specify the PLAT= with desired rockchip platform to build TF-A for. + +U-Boot +^^^^^^ + +To build rk3328 boards:: + + export BL31=/path/to/arm-trusted-firmware/to/bl31.elf + make evb-rk3328_defconfig + make + +To build rk3288 boards:: + + make evb-rk3288_defconfig + make + +To build rk3368 boards:: + + export BL31=/path/to/arm-trusted-firmware/to/bl31.elf + make evb-px5_defconfig + make + +To build rk3399 boards:: + + export BL31=/path/to/arm-trusted-firmware/to/bl31.elf + make evb-rk3399_defconfig + make + +Flashing +-------- + +1. Package the image with U-Boot TPL/SPL +----------------------------------------- + +SD Card +^^^^^^^ + +All rockchip platforms, except rk3128 (which doesn't use SPL) are now +supporting single boot image using binman and pad_cat. + +To write an image that boots from an SD card (assumed to be /dev/sda):: + + sudo dd if=u-boot-rockchip.bin of=/dev/sda seek=64 + sync + +eMMC +^^^^ + +eMMC flash would probe on mmc0 in most of the rockchip platforms. + +Create GPT partition layout as defined in configurations:: + + mmc dev 0 + gpt write mmc 0 $partitions + +Connect the USB-OTG cable between host and target device. + +Launch fastboot at target:: + + fastboot 0 + +Upon successful gadget connection,host show the USB device like:: + + lsusb + Bus 001 Device 020: ID 2207:330c Fuzhou Rockchip Electronics Company RK3399 in Mask ROM mode + +Program the flash:: + + sudo fastboot -i 0x2207 flash loader1 idbloader.img + sudo fastboot -i 0x2207 flash loader2 u-boot.itb + +Note: for rockchip 32-bit platforms the U-Boot proper image +is u-boot-dtb.img + +SPI +^^^ + +Generating idbloader for SPI boot would require to input a multi image +image format to mkimage tool instead of concerting (like for MMC boot). + +SPL-alone SPI boot image:: + + ./tools/mkimage -n rk3399 -T rkspi -d spl/u-boot-spl.bin idbloader.img + +TPL+SPL SPI boot image:: + + ./tools/mkimage -n rk3399 -T rkspi -d tpl/u-boot-tpl.bin:spl/u-boot-spl.bin idbloader.img + +Copy SPI boot images into SD card and boot from SD:: + + sf probe + load mmc 1:1 $kernel_addr_r idbloader.img + sf erase 0 +$filesize + sf write $kernel_addr_r 0 ${filesize} + load mmc 1:1 ${kernel_addr_r} u-boot.itb + sf erase 0x60000 +$filesize + sf write $kernel_addr_r 0x60000 ${filesize} + +2. Package the image with Rockchip miniloader +--------------------------------------------- + +Image package with Rockchip miniloader requires robin [1]. + +Create idbloader.img + +.. code-block:: none + + cd u-boot + ./tools/mkimage -n px30 -T rksd -d rkbin/bin/rk33/px30_ddr_333MHz_v1.15.bin idbloader.img + cat rkbin/bin/rk33/px30_miniloader_v1.22.bin >> idbloader.img + sudo dd if=idbloader.img of=/dev/sda seek=64 + +Create trust.img + +.. code-block:: none + + cd rkbin + ./tools/trust_merger RKTRUST/PX30TRUST.ini + sudo dd if=trust.img of=/dev/sda seek=24576 + +Create uboot.img + +.. code-block:: none + + rbink/tools/loaderimage --pack --uboot u-boot-dtb.bin uboot.img 0x200000 + sudo dd if=uboot.img of=/dev/sda seek=16384 + +Note: +1. 0x200000 is load address and it's an optional in some platforms. +2. rkbin binaries are kept on updating, so would recommend to use the latest versions. + +TODO +---- + +- Add rockchip idbloader image building +- Add rockchip TPL image building +- Document SPI flash boot +- Add missing SoC's with it boards list + +[1] https://github.com/rockchip-linux/rkbin + +.. Jagan Teki <jagan@amarulasolutions.com> +.. Wednesday 28 October 2020 06:47:26 PM IST diff --git a/roms/u-boot/doc/board/sifive/index.rst b/roms/u-boot/doc/board/sifive/index.rst new file mode 100644 index 000000000..a43937a3e --- /dev/null +++ b/roms/u-boot/doc/board/sifive/index.rst @@ -0,0 +1,10 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +SiFive +====== + +.. toctree:: + :maxdepth: 2 + + unleashed + unmatched diff --git a/roms/u-boot/doc/board/sifive/unleashed.rst b/roms/u-boot/doc/board/sifive/unleashed.rst new file mode 100644 index 000000000..4e4c852ff --- /dev/null +++ b/roms/u-boot/doc/board/sifive/unleashed.rst @@ -0,0 +1,579 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +HiFive Unleashed +================ + +FU540-C000 RISC-V SoC +--------------------- +The FU540-C000 is the world’s first 4+1 64-bit RISC-V SoC from SiFive. + +The HiFive Unleashed development platform is based on FU540-C000 and capable +of running Linux. + +Mainline support +---------------- + +The support for following drivers are already enabled: + +1. SiFive UART Driver. +2. SiFive PRCI Driver for clock. +3. Cadence MACB ethernet driver for networking support. +4. SiFive SPI Driver. +5. MMC SPI Driver for MMC/SD support. + +Booting from MMC using FSBL +--------------------------- + +Building +~~~~~~~~ + +1. Add the RISC-V toolchain to your PATH. +2. Setup ARCH & cross compilation environment variable: + +.. code-block:: none + + export CROSS_COMPILE=<riscv64 toolchain prefix> + +3. make sifive_fu540_defconfig +4. make + +Flashing +~~~~~~~~ + +The current U-Boot port is supported in S-mode only and loaded from DRAM. + +A prior stage M-mode firmware/bootloader (e.g OpenSBI) is required to +boot the u-boot.bin in S-mode and provide M-mode runtime services. + +Currently, the u-boot.bin is used as a payload of the OpenSBI FW_PAYLOAD +firmware. We need to compile OpenSBI with below command: + +.. code-block:: none + + make PLATFORM=generic FW_PAYLOAD_PATH=<path to u-boot-dtb.bin> + +More detailed description of steps required to build FW_PAYLOAD firmware +is beyond the scope of this document. Please refer OpenSBI documenation. +(Note: OpenSBI git repo is at https://github.com/riscv/opensbi.git) + +Once the prior stage firmware/bootloader binary is generated, it should be +copied to the first partition of the sdcard. + +.. code-block:: none + + sudo dd if=<prior_stage_firmware_binary> of=/dev/disk2s1 bs=1024 + +Booting +~~~~~~~ + +Once you plugin the sdcard and power up, you should see the U-Boot prompt. + +Sample boot log from HiFive Unleashed board +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. code-block:: none + + U-Boot 2019.07-00024-g350ff02f5b (Jul 22 2019 - 11:45:02 +0530) + + CPU: rv64imafdc + Model: SiFive HiFive Unleashed A00 + DRAM: 8 GiB + MMC: spi@10050000:mmc@0: 0 + In: serial@10010000 + Out: serial@10010000 + Err: serial@10010000 + Net: eth0: ethernet@10090000 + Hit any key to stop autoboot: 0 + => version + U-Boot 2019.07-00024-g350ff02f5b (Jul 22 2019 - 11:45:02 +0530) + + riscv64-linux-gcc.br_real (Buildroot 2018.11-rc2-00003-ga0787e9) 8.2.0 + GNU ld (GNU Binutils) 2.31.1 + => mmc info + Device: spi@10050000:mmc@0 + Manufacturer ID: 3 + OEM: 5344 + Name: SU08G + Bus Speed: 20000000 + Mode: SD Legacy + Rd Block Len: 512 + SD version 2.0 + High Capacity: Yes + Capacity: 7.4 GiB + Bus Width: 1-bit + Erase Group Size: 512 Bytes + => mmc part + + Partition Map for MMC device 0 -- Partition Type: EFI + + Part Start LBA End LBA Name + Attributes + Type GUID + Partition GUID + 1 0x00000800 0x000107ff "bootloader" + attrs: 0x0000000000000000 + type: 2e54b353-1271-4842-806f-e436d6af6985 + guid: 393bbd36-7111-491c-9869-ce24008f6403 + 2 0x00040800 0x00ecdfde "" + attrs: 0x0000000000000000 + type: 0fc63daf-8483-4772-8e79-3d69d8477de4 + guid: 7fc9a949-5480-48c7-b623-04923080757f + +Now you can configure your networking, tftp server and use tftp boot method to +load uImage. + +.. code-block:: none + + => setenv ipaddr 10.206.7.133 + => setenv netmask 255.255.252.0 + => setenv serverip 10.206.4.143 + => setenv gateway 10.206.4.1 + +If you want to use a flat kernel image such as Image file + +.. code-block:: none + + => tftpboot ${kernel_addr_r} /sifive/fu540/Image + ethernet@10090000: PHY present at 0 + ethernet@10090000: Starting autonegotiation... + ethernet@10090000: Autonegotiation complete + ethernet@10090000: link up, 1000Mbps full-duplex (lpa: 0x3c00) + Using ethernet@10090000 device + TFTP from server 10.206.4.143; our IP address is 10.206.7.133 + Filename '/sifive/fu540/Image'. + Load address: 0x84000000 + Loading: ################################################################# + ################################################################# + ################################################################# + ################################################################# + ################################################################# + ################################################################# + ################################################################# + ################################################################# + ################################################################# + ################################################################# + ################################################################# + ################################################################# + ################################################################# + ################################################################# + ################################################################# + ################################################################# + ################################################################# + ################################################################# + ################################################################# + ################################################################# + ################################################################# + ################################################################# + ################################################################# + ################################################################# + ################################################################# + ################################################################# + ########################################## + 1.2 MiB/s + done + Bytes transferred = 8867100 (874d1c hex) + +Or if you want to use a compressed kernel image file such as Image.gz + +.. code-block:: none + + => tftpboot ${kernel_addr_r} /sifive/fu540/Image.gz + ethernet@10090000: PHY present at 0 + ethernet@10090000: Starting autonegotiation... + ethernet@10090000: Autonegotiation complete + ethernet@10090000: link up, 1000Mbps full-duplex (lpa: 0x3c00) + Using ethernet@10090000 device + TFTP from server 10.206.4.143; our IP address is 10.206.7.133 + Filename '/sifive/fu540/Image.gz'. + Load address: 0x84000000 + Loading: ################################################################# + ################################################################# + ################################################################# + ################################################################# + ################################################################# + ################################################################# + ################################################################# + ################################################################# + ################################################################# + ################################################################# + ################################################################# + ################################################################# + ################################################################# + ################################################################# + ################################################################# + ################################################################# + ################################################################# + ################################################################# + ################################################################# + ################################################################# + ################################################################# + ################################################################# + ################################################################# + ################################################################# + ################################################################# + ################################################################# + ########################################## + 1.2 MiB/s + done + Bytes transferred = 4809458 (4962f2 hex) + =>setenv kernel_comp_addr_r 0x90000000 + =>setenv kernel_comp_size 0x500000 + +By this time, correct kernel image is loaded and required environment variables +are set. You can proceed to load the ramdisk and device tree from the tftp server +as well. + +.. code-block:: none + + => tftpboot ${ramdisk_addr_r} /sifive/fu540/uRamdisk + ethernet@10090000: PHY present at 0 + ethernet@10090000: Starting autonegotiation... + ethernet@10090000: Autonegotiation complete + ethernet@10090000: link up, 1000Mbps full-duplex (lpa: 0x3c00) + Using ethernet@10090000 device + TFTP from server 10.206.4.143; our IP address is 10.206.7.133 + Filename '/sifive/fu540/uRamdisk'. + Load address: 0x88300000 + Loading: ################################################################# + ################################################################# + ################################################################# + ################################################################# + ################################################################# + ################################################################# + ################################################################# + ############## + 418.9 KiB/s + done + Bytes transferred = 2398272 (249840 hex) + => tftpboot ${fdt_addr_r} /sifive/fu540/hifive-unleashed-a00.dtb + ethernet@10090000: PHY present at 0 + ethernet@10090000: Starting autonegotiation... + ethernet@10090000: Autonegotiation complete + ethernet@10090000: link up, 1000Mbps full-duplex (lpa: 0x7c00) + Using ethernet@10090000 device + TFTP from server 10.206.4.143; our IP address is 10.206.7.133 + Filename '/sifive/fu540/hifive-unleashed-a00.dtb'. + Load address: 0x88000000 + Loading: ## + 1000 Bytes/s + done + Bytes transferred = 5614 (15ee hex) + => setenv bootargs "root=/dev/ram rw console=ttySIF0 ip=dhcp earlycon=sbi" + => booti ${kernel_addr_r} ${ramdisk_addr_r} ${fdt_addr_r} + ## Loading init Ramdisk from Legacy Image at 88300000 ... + Image Name: Linux RootFS + Image Type: RISC-V Linux RAMDisk Image (uncompressed) + Data Size: 2398208 Bytes = 2.3 MiB + Load Address: 00000000 + Entry Point: 00000000 + Verifying Checksum ... OK + ## Flattened Device Tree blob at 88000000 + Booting using the fdt blob at 0x88000000 + Using Device Tree in place at 0000000088000000, end 00000000880045ed + + Starting kernel ... + + [ 0.000000] OF: fdt: Ignoring memory range 0x80000000 - 0x80200000 + [ 0.000000] Linux version 5.3.0-rc1-00003-g460ac558152f (anup@anup-lab-machine) (gcc version 8.2.0 (Buildroot 2018.11-rc2-00003-ga0787e9)) #6 SMP Mon Jul 22 10:01:01 IST 2019 + [ 0.000000] earlycon: sbi0 at I/O port 0x0 (options '') + [ 0.000000] printk: bootconsole [sbi0] enabled + [ 0.000000] Initial ramdisk at: 0x(____ptrval____) (2398208 bytes) + [ 0.000000] Zone ranges: + [ 0.000000] DMA32 [mem 0x0000000080200000-0x00000000ffffffff] + [ 0.000000] Normal [mem 0x0000000100000000-0x000000027fffffff] + [ 0.000000] Movable zone start for each node + [ 0.000000] Early memory node ranges + [ 0.000000] node 0: [mem 0x0000000080200000-0x000000027fffffff] + [ 0.000000] Initmem setup node 0 [mem 0x0000000080200000-0x000000027fffffff] + [ 0.000000] software IO TLB: mapped [mem 0xfbfff000-0xfffff000] (64MB) + [ 0.000000] CPU with hartid=0 is not available + [ 0.000000] CPU with hartid=0 is not available + [ 0.000000] elf_hwcap is 0x112d + [ 0.000000] percpu: Embedded 18 pages/cpu s34584 r8192 d30952 u73728 + [ 0.000000] Built 1 zonelists, mobility grouping on. Total pages: 2067975 + [ 0.000000] Kernel command line: root=/dev/ram rw console=ttySIF0 ip=dhcp earlycon=sbi + [ 0.000000] Dentry cache hash table entries: 1048576 (order: 11, 8388608 bytes, linear) + [ 0.000000] Inode-cache hash table entries: 524288 (order: 10, 4194304 bytes, linear) + [ 0.000000] Sorting __ex_table... + [ 0.000000] mem auto-init: stack:off, heap alloc:off, heap free:off + [ 0.000000] Memory: 8182308K/8386560K available (5916K kernel code, 368K rwdata, 1840K rodata, 213K init, 304K bss, 204252K reserved, 0K cma-reserved) + [ 0.000000] SLUB: HWalign=64, Order=0-3, MinObjects=0, CPUs=4, Nodes=1 + [ 0.000000] rcu: Hierarchical RCU implementation. + [ 0.000000] rcu: RCU restricting CPUs from NR_CPUS=8 to nr_cpu_ids=4. + [ 0.000000] rcu: RCU calculated value of scheduler-enlistment delay is 25 jiffies. + [ 0.000000] rcu: Adjusting geometry for rcu_fanout_leaf=16, nr_cpu_ids=4 + [ 0.000000] NR_IRQS: 0, nr_irqs: 0, preallocated irqs: 0 + [ 0.000000] plic: mapped 53 interrupts with 4 handlers for 9 contexts. + [ 0.000000] riscv_timer_init_dt: Registering clocksource cpuid [0] hartid [1] + [ 0.000000] clocksource: riscv_clocksource: mask: 0xffffffffffffffff max_cycles: 0x1d854df40, max_idle_ns: 3526361616960 ns + [ 0.000006] sched_clock: 64 bits at 1000kHz, resolution 1000ns, wraps every 2199023255500ns + [ 0.008559] Console: colour dummy device 80x25 + [ 0.012989] Calibrating delay loop (skipped), value calculated using timer frequency.. 2.00 BogoMIPS (lpj=4000) + [ 0.023104] pid_max: default: 32768 minimum: 301 + [ 0.028273] Mount-cache hash table entries: 16384 (order: 5, 131072 bytes, linear) + [ 0.035765] Mountpoint-cache hash table entries: 16384 (order: 5, 131072 bytes, linear) + [ 0.045307] rcu: Hierarchical SRCU implementation. + [ 0.049875] smp: Bringing up secondary CPUs ... + [ 0.055729] smp: Brought up 1 node, 4 CPUs + [ 0.060599] devtmpfs: initialized + [ 0.064819] random: get_random_u32 called from bucket_table_alloc.isra.10+0x4e/0x160 with crng_init=0 + [ 0.073720] clocksource: jiffies: mask: 0xffffffff max_cycles: 0xffffffff, max_idle_ns: 7645041785100000 ns + [ 0.083176] futex hash table entries: 1024 (order: 4, 65536 bytes, linear) + [ 0.090721] NET: Registered protocol family 16 + [ 0.106319] vgaarb: loaded + [ 0.108670] SCSI subsystem initialized + [ 0.112515] usbcore: registered new interface driver usbfs + [ 0.117758] usbcore: registered new interface driver hub + [ 0.123167] usbcore: registered new device driver usb + [ 0.128905] clocksource: Switched to clocksource riscv_clocksource + [ 0.141239] NET: Registered protocol family 2 + [ 0.145506] tcp_listen_portaddr_hash hash table entries: 4096 (order: 4, 65536 bytes, linear) + [ 0.153754] TCP established hash table entries: 65536 (order: 7, 524288 bytes, linear) + [ 0.163466] TCP bind hash table entries: 65536 (order: 8, 1048576 bytes, linear) + [ 0.173468] TCP: Hash tables configured (established 65536 bind 65536) + [ 0.179739] UDP hash table entries: 4096 (order: 5, 131072 bytes, linear) + [ 0.186627] UDP-Lite hash table entries: 4096 (order: 5, 131072 bytes, linear) + [ 0.194117] NET: Registered protocol family 1 + [ 0.198417] RPC: Registered named UNIX socket transport module. + [ 0.203887] RPC: Registered udp transport module. + [ 0.208664] RPC: Registered tcp transport module. + [ 0.213429] RPC: Registered tcp NFSv4.1 backchannel transport module. + [ 0.219944] PCI: CLS 0 bytes, default 64 + [ 0.224170] Unpacking initramfs... + [ 0.262347] Freeing initrd memory: 2336K + [ 0.266531] workingset: timestamp_bits=62 max_order=21 bucket_order=0 + [ 0.280406] NFS: Registering the id_resolver key type + [ 0.284798] Key type id_resolver registered + [ 0.289048] Key type id_legacy registered + [ 0.293114] nfs4filelayout_init: NFSv4 File Layout Driver Registering... + [ 0.300262] NET: Registered protocol family 38 + [ 0.304432] Block layer SCSI generic (bsg) driver version 0.4 loaded (major 254) + [ 0.311862] io scheduler mq-deadline registered + [ 0.316461] io scheduler kyber registered + [ 0.356421] Serial: 8250/16550 driver, 4 ports, IRQ sharing disabled + [ 0.363004] 10010000.serial: ttySIF0 at MMIO 0x10010000 (irq = 4, base_baud = 0) is a SiFive UART v0 + [ 0.371468] printk: console [ttySIF0] enabled + [ 0.371468] printk: console [ttySIF0] enabled + [ 0.380223] printk: bootconsole [sbi0] disabled + [ 0.380223] printk: bootconsole [sbi0] disabled + [ 0.389589] 10011000.serial: ttySIF1 at MMIO 0x10011000 (irq = 1, base_baud = 0) is a SiFive UART v0 + [ 0.398680] [drm] radeon kernel modesetting enabled. + [ 0.412395] loop: module loaded + [ 0.415214] sifive_spi 10040000.spi: mapped; irq=3, cs=1 + [ 0.420628] sifive_spi 10050000.spi: mapped; irq=5, cs=1 + [ 0.425897] libphy: Fixed MDIO Bus: probed + [ 0.429964] macb 10090000.ethernet: Registered clk switch 'sifive-gemgxl-mgmt' + [ 0.436743] macb: GEM doesn't support hardware ptp. + [ 0.441621] libphy: MACB_mii_bus: probed + [ 0.601316] Microsemi VSC8541 SyncE 10090000.ethernet-ffffffff:00: attached PHY driver [Microsemi VSC8541 SyncE] (mii_bus:phy_addr=10090000.ethernet-ffffffff:00, irq=POLL) + [ 0.615857] macb 10090000.ethernet eth0: Cadence GEM rev 0x10070109 at 0x10090000 irq 6 (70:b3:d5:92:f2:f3) + [ 0.625634] e1000e: Intel(R) PRO/1000 Network Driver - 3.2.6-k + [ 0.631381] e1000e: Copyright(c) 1999 - 2015 Intel Corporation. + [ 0.637382] ehci_hcd: USB 2.0 'Enhanced' Host Controller (EHCI) Driver + [ 0.643799] ehci-pci: EHCI PCI platform driver + [ 0.648261] ehci-platform: EHCI generic platform driver + [ 0.653497] ohci_hcd: USB 1.1 'Open' Host Controller (OHCI) Driver + [ 0.659599] ohci-pci: OHCI PCI platform driver + [ 0.664055] ohci-platform: OHCI generic platform driver + [ 0.669448] usbcore: registered new interface driver uas + [ 0.674575] usbcore: registered new interface driver usb-storage + [ 0.680642] mousedev: PS/2 mouse device common for all mice + [ 0.709493] mmc_spi spi1.0: SD/MMC host mmc0, no DMA, no WP, no poweroff, cd polling + [ 0.716615] usbcore: registered new interface driver usbhid + [ 0.722023] usbhid: USB HID core driver + [ 0.726738] NET: Registered protocol family 10 + [ 0.731359] Segment Routing with IPv6 + [ 0.734332] sit: IPv6, IPv4 and MPLS over IPv4 tunneling driver + [ 0.740687] NET: Registered protocol family 17 + [ 0.744660] Key type dns_resolver registered + [ 0.806775] mmc0: host does not support reading read-only switch, assuming write-enable + [ 0.814020] mmc0: new SDHC card on SPI + [ 0.820137] mmcblk0: mmc0:0000 SU08G 7.40 GiB + [ 0.850220] mmcblk0: p1 p2 + [ 3.821524] macb 10090000.ethernet eth0: link up (1000/Full) + [ 3.828938] IPv6: ADDRCONF(NETDEV_CHANGE): eth0: link becomes ready + [ 3.848919] Sending DHCP requests .., OK + [ 6.252076] IP-Config: Got DHCP answer from 10.206.4.1, my address is 10.206.7.133 + [ 6.259624] IP-Config: Complete: + [ 6.262831] device=eth0, hwaddr=70:b3:d5:92:f2:f3, ipaddr=10.206.7.133, mask=255.255.252.0, gw=10.206.4.1 + [ 6.272809] host=dhcp-10-206-7-133, domain=sdcorp.global.sandisk.com, nis-domain=(none) + [ 6.281228] bootserver=10.206.126.11, rootserver=10.206.126.11, rootpath= + [ 6.281232] nameserver0=10.86.1.1, nameserver1=10.86.2.1 + [ 6.294179] ntpserver0=10.86.1.1, ntpserver1=10.86.2.1 + [ 6.301026] Freeing unused kernel memory: 212K + [ 6.304683] This architecture does not have kernel memory protection. + [ 6.311121] Run /init as init process + _ _ + | ||_| + | | _ ____ _ _ _ _ + | || | _ \| | | |\ \/ / + | || | | | | |_| |/ \ + |_||_|_| |_|\____|\_/\_/ + + Busybox Rootfs + + Please press Enter to activate this console. + / # + +Booting from MMC using U-Boot SPL +--------------------------------- + +Building +~~~~~~~~ + +Before building U-Boot SPL, OpenSBI must be built first. OpenSBI can be +cloned and built for FU540 as below: + +.. code-block:: console + + git clone https://github.com/riscv/opensbi.git + cd opensbi + make PLATFORM=generic + export OPENSBI=<path to opensbi/build/platform/generic/firmware/fw_dynamic.bin> + +Now build the U-Boot SPL and U-Boot proper + +.. code-block:: console + + cd <U-Boot-dir> + make sifive_fu540_defconfig + make + +This will generate spl/u-boot-spl.bin and FIT image (u-boot.itb) + + +Flashing +~~~~~~~~ + +ZSBL loads the U-Boot SPL (u-boot-spl.bin) from a partition with GUID type +5B193300-FC78-40CD-8002-E86C45580B47 + +U-Boot SPL expects a U-Boot FIT image (u-boot.itb) from a partition with GUID +type 2E54B353-1271-4842-806F-E436D6AF6985 + +FIT image (u-boot.itb) is a combination of fw_dynamic.bin, u-boot-nodtb.bin and +device tree blob (hifive-unleashed-a00.dtb) + +Format the SD card (make sure the disk has GPT, otherwise use gdisk to switch) + +.. code-block:: none + + # sudo sgdisk --clear \ + > --set-alignment=2 \ + > --new=1:34:2081 --change-name=1:loader1 --typecode=1:5B193300-FC78-40CD-8002-E86C45580B47 \ + > --new=2:2082:10273 --change-name=2:loader2 --typecode=2:2E54B353-1271-4842-806F-E436D6AF6985 \ + > --new=3:10274: --change-name=3:rootfs --typecode=3:0FC63DAF-8483-4772-8E79-3D69D8477DE4 \ + > /dev/sda + +Program the SD card + +.. code-block:: none + + sudo dd if=spl/u-boot-spl.bin of=/dev/sda seek=34 + sudo dd if=u-boot.itb of=/dev/sda seek=2082 + +Booting +~~~~~~~ + +Once you plugin the sdcard and power up, you should see the U-Boot prompt. + +Sample boot log from HiFive Unleashed board +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. code-block:: none + + U-Boot SPL 2020.04-rc2-00109-g63efc7e07e-dirty (Apr 30 2020 - 13:52:36 +0530) + Trying to boot from MMC1 + + + U-Boot 2020.04-rc2-00109-g63efc7e07e-dirty (Apr 30 2020 - 13:52:36 +0530) + + CPU: rv64imafdc + Model: SiFive HiFive Unleashed A00 + DRAM: 8 GiB + MMC: spi@10050000:mmc@0: 0 + In: serial@10010000 + Out: serial@10010000 + Err: serial@10010000 + Net: eth0: ethernet@10090000 + Hit any key to stop autoboot: 0 + => version + U-Boot 2020.04-rc2-00109-g63efc7e07e-dirty (Apr 30 2020 - 13:52:36 +0530) + + riscv64-unknown-linux-gnu-gcc (crosstool-NG 1.24.0.37-3f461da) 9.2.0 + GNU ld (crosstool-NG 1.24.0.37-3f461da) 2.32 + => mmc info + Device: spi@10050000:mmc@0 + Manufacturer ID: 3 + OEM: 5344 + Name: SC16G + Bus Speed: 20000000 + Mode: SD Legacy + Rd Block Len: 512 + SD version 2.0 + High Capacity: Yes + Capacity: 14.8 GiB + Bus Width: 1-bit + Erase Group Size: 512 Bytes + => mmc part + + Partition Map for MMC device 0 -- Partition Type: EFI + + Part Start LBA End LBA Name + Attributes + Type GUID + Partition GUID + 1 0x00000022 0x00000821 "loader1" + attrs: 0x0000000000000000 + type: 5b193300-fc78-40cd-8002-e86c45580b47 + guid: 66e2b5d2-74db-4df8-ad6f-694b3617f87f + 2 0x00000822 0x00002821 "loader2" + attrs: 0x0000000000000000 + type: 2e54b353-1271-4842-806f-e436d6af6985 + guid: 8befaeaf-bca0-435d-b002-e201f37c0a2f + 3 0x00002822 0x01dacbde "rootfs" + attrs: 0x0000000000000000 + type: 0fc63daf-8483-4772-8e79-3d69d8477de4 + type: linux + guid: 9faa81b6-39b1-4418-af5e-89c48f29c20d + +Booting from SPI +---------------- + +Use Building steps from "Booting from MMC using U-Boot SPL" section. + +Partition the SPI in Linux via mtdblock. (Require to boot the board in +SD boot mode by enabling MTD block in Linux) + +Use prebuilt image from here [1], which support to partition the SPI flash. + +.. code-block:: none + + # sgdisk --clear \ + > --set-alignment=2 \ + > --new=1:40:2087 --change-name=1:loader1 --typecode=1:5B193300-FC78-40CD-8002-E86C45580B47 \ + > --new=2:2088:10279 --change-name=2:loader2 --typecode=2:2E54B353-1271-4842-806F-E436D6AF6985 \ + > --new=3:10536:65494 --change-name=3:rootfs --typecode=3:0FC63DAF-8483-4772-8E79-3D69D8477DE4 \ + > /dev/mtdblock0 + +Program the SPI (Require to boot the board in SD boot mode) + +Execute below steps on U-Boot proper, + +.. code-block:: none + + tftpboot $kernel_addr_r u-boot-spl.bin + sf erase 0x5000 $filesize + sf write $kernel_addr_r 0x5000 $filesize + + tftpboot $kernel_addr_r u-boot.itb + sf erase 0x105000 $filesize + sf write $kernel_addr_r 0x105000 $filesize + +Power off the board + +Change DIP switches MSEL[3:0] are set to 0110 + +Power up the board. + +[1] https://github.com/amarula/bsp-sifive diff --git a/roms/u-boot/doc/board/sifive/unmatched.rst b/roms/u-boot/doc/board/sifive/unmatched.rst new file mode 100644 index 000000000..e65b0d320 --- /dev/null +++ b/roms/u-boot/doc/board/sifive/unmatched.rst @@ -0,0 +1,536 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +HiFive Unmatched +================ + +FU740-C000 RISC-V SoC +--------------------- +The FU740-C000 is a 4+1 64-bit RISC-V core SoC from SiFive. + +The HiFive Unmatched development platform is based on FU740-C000 and capable +of running Linux. + +Mainline support +---------------- +The support for following drivers are already enabled: + +1. SiFive UART Driver. +2. SiFive PRCI Driver for clock. +3. Cadence MACB ethernet driver for networking support. +4. SiFive SPI Driver. +5. MMC SPI Driver for MMC/SD support. + +Booting from uSD using U-Boot SPL +--------------------------------- + +Building +-------- + +Before building U-Boot SPL, OpenSBI must be built first. OpenSBI can be +cloned and built for FU740 as below: + +.. code-block:: console + + git clone https://github.com/riscv/opensbi.git + cd opensbi + make PLATFORM=generic + export OPENSBI=<path to opensbi/build/platform/generic/firmware/fw_dynamic.bin> + +Now build the U-Boot SPL and U-Boot proper + +.. code-block:: console + + cd <U-Boot-dir> + make sifive_unmatched_defconfig + make + +This will generate spl/u-boot-spl.bin and u-boot.itb + + +Flashing +-------- + +ZSBL loads the U-Boot SPL (u-boot-spl.bin) from a partition with GUID type +5B193300-FC78-40CD-8002-E86C45580B47 + +U-Boot SPL expects u-boot.itb from a partition with GUID +type 2E54B353-1271-4842-806F-E436D6AF6985 + +u-boot.itb is a combination of fw_dynamic.bin, u-boot-nodtb.bin and +device tree blob (hifive-unmatched-a00.dtb) + +Format the SD card (make sure the disk has GPT, otherwise use gdisk to switch) + +.. code-block:: none + + # sudo sgdisk -g --clear -a 1 \ + > --new=1:34:2081 --change-name=1:spl --typecode=1:5B193300-FC78-40CD-8002-E86C45580B47 \ + > --new=2:2082:10273 --change-name=2:uboot --typecode=2:2E54B353-1271-4842-806F-E436D6AF6985 \ + > --new=3:16384:282623 --change-name=3:boot --typecode=3:0x0700 \ + > --new=4:286720:13918207 --change-name=4:root --typecode=4:0x8300 \ + > /dev/sdb + +Copy linux Image.gz and hifive-unmatched-a00.dtb to boot partition + +.. code-block:: none + + sudo mkfs.vfat /dev/sdb3 + sudo mkfs.ext4 /dev/sdb4 + + sudo mount /dev/sdb3 /media/sdb3 + sudo cp Image.gz hifive-unmatched-a00.dtb /media/sdb3/ + +Program the SD card + +.. code-block:: none + + sudo dd if=spl/u-boot-spl.bin of=/dev/sda seek=34 + sudo dd if=u-boot.itb of=/dev/sda seek=2082 + +Booting +------- +Once you plugin the sdcard and power up, you should see the U-Boot prompt. + + +Loading the kernel and dtb + +.. code-block:: none + + fatload mmc 0:3 ${kernel_addr_r} Image.gz + fatload mmc 0:3 ${fdt_addr_r} hifive-unmatched-a00.dtb + booti ${kernel_addr_r} - ${fdt_addr_r} + + +Sample boot log from HiFive Unmatched board +------------------------------------------- + +.. code-block:: none + + U-Boot SPL 2021.04-rc4-00009-g7d70643cc3-dirty (Mar 16 2021 - 18:03:14 +0800) + Trying to boot from MMC1 + + U-Boot 2021.04-rc4-00009-g7d70643cc3-dirty (Mar 16 2021 - 18:03:14 +0800) + + CPU: rv64imafdc + Model: SiFive HiFive Unmatched A00 + DRAM: 16 GiB + MMC: spi@10050000:mmc@0: 0 + In: serial@10010000 + Out: serial@10010000 + Err: serial@10010000 + Model: SiFive HiFive Unmatched A00 + Net: + Error: ethernet@10090000 address not set. + No ethernet found. + + Hit any key to stop autoboot: 0 + PCIe Link up, Gen1 + + Device 0: Vendor: 0x126f Rev: S1111A0L Prod: AA000000000000001995 + Type: Hard Disk + Capacity: 488386.3 MB = 476.9 GB (1000215216 x 512) + ... is now current device + Scanning nvme 0:1... + libfdt fdt_check_header(): FDT_ERR_BADMAGIC + Scanning disk mmc@0.blk... + ** Unrecognized filesystem type ** + ** Unrecognized filesystem type ** + Scanning disk nvme#0.blk#0... + Found 8 disks + No EFI system partition + + Error: ethernet@10090000 address not set. + BootOrder not defined + EFI boot manager: Cannot load any image + starting USB... + Bus xhci_pci: Register 4000840 NbrPorts 4 + Starting the controller + USB XHCI 1.00 + scanning bus xhci_pci for devices... 3 USB Device(s) found + scanning usb for storage devices... 0 Storage Device(s) found + + Device 0: unknown device + switch to partitions #0, OK + mmc0 is current device + Scanning mmc 0:3... + Found /extlinux/extlinux.conf + Retrieving file: /extlinux/extlinux.conf + 205 bytes read in 9 ms (21.5 KiB/s) + 1: OpenEmbedded-SiFive-HiFive-Unmatched + Retrieving file: /Image.gz + 7225919 bytes read in 4734 ms (1.5 MiB/s) + append: root=/dev/mmcblk0p4 rootfstype=ext4 rootwait console=ttySIF0,115200 earlycon=sbi + Retrieving file: /hifive-unmatched-a00.dtb + 10445 bytes read in 13 ms (784.2 KiB/s) + Uncompressing Kernel Image + Moving Image from 0x84000000 to 0x80200000, end=81629000 + ## Flattened Device Tree blob at 88000000 + Booting using the fdt blob at 0x88000000 + Using Device Tree in place at 0000000088000000, end 00000000880058cc + + Starting kernel ... + + [ 0.000000] Linux version 5.10.15 (oe-user@oe-host) (riscv64-oe-linux-gcc (GCC) 10.2.0, GNU ld (GNU Binutils) 2.35.0.201 + [ 0.000000] OF: fdt: Ignoring memory range 0x80000000 - 0x80200000 + [ 0.000000] earlycon: sbi0 at I/O port 0x0 (options '') + [ 0.000000] printk: bootconsole [sbi0] enabled + [ 0.000000] efi: UEFI not found. + [ 0.000000] Zone ranges: + [ 0.000000] DMA32 [mem 0x0000000080200000-0x00000000ffffffff] + [ 0.000000] Normal [mem 0x0000000100000000-0x000000027fffffff] + [ 0.000000] Movable zone start for each node + [ 0.000000] Early memory node ranges + [ 0.000000] node 0: [mem 0x0000000080200000-0x000000027fffffff] + [ 0.000000] Zeroed struct page in unavailable ranges: 512 pages + [ 0.000000] Initmem setup node 0 [mem 0x0000000080200000-0x000000027fffffff] + [ 0.000000] software IO TLB: mapped [mem 0x00000000fbfff000-0x00000000fffff000] (64MB) + [ 0.000000] SBI specification v0.3 detected + [ 0.000000] SBI implementation ID=0x1 Version=0x9 + [ 0.000000] SBI v0.2 TIME extension detected + [ 0.000000] SBI v0.2 IPI extension detected + [ 0.000000] SBI v0.2 RFENCE extension detected + [ 0.000000] SBI v0.2 HSM extension detected + [ 0.000000] CPU with hartid=0 is not available + [ 0.000000] CPU with hartid=0 is not available + [ 0.000000] riscv: ISA extensions acdfim + [ 0.000000] riscv: ELF capabilities acdfim + [ 0.000000] percpu: Embedded 26 pages/cpu s66904 r8192 d31400 u106496 + [ 0.000000] Built 1 zonelists, mobility grouping on. Total pages: 2067975 + [ 0.000000] Kernel command line: root=/dev/mmcblk0p4 rootfstype=ext4 rootwait console=ttySIF0,115200 earlycon=sbi + [ 0.000000] Dentry cache hash table entries: 1048576 (order: 11, 8388608 bytes, linear) + [ 0.000000] Inode-cache hash table entries: 524288 (order: 10, 4194304 bytes, linear) + [ 0.000000] Sorting __ex_table... + [ 0.000000] mem auto-init: stack:off, heap alloc:off, heap free:off + [ 0.000000] Memory: 8155880K/8386560K available (8490K kernel code, 5515K rwdata, 4096K rodata, 285K init, 383K bss, 23) + [ 0.000000] SLUB: HWalign=64, Order=0-3, MinObjects=0, CPUs=4, Nodes=1 + [ 0.000000] rcu: Hierarchical RCU implementation. + [ 0.000000] rcu: RCU restricting CPUs from NR_CPUS=8 to nr_cpu_ids=4. + [ 0.000000] Tracing variant of Tasks RCU enabled. + [ 0.000000] rcu: RCU calculated value of scheduler-enlistment delay is 25 jiffies. + [ 0.000000] rcu: Adjusting geometry for rcu_fanout_leaf=16, nr_cpu_ids=4 + [ 0.000000] NR_IRQS: 64, nr_irqs: 64, preallocated irqs: 0 + [ 0.000000] CPU with hartid=0 is not available + [ 0.000000] riscv-intc: unable to find hart id for /cpus/cpu@0/interrupt-controller + [ 0.000000] riscv-intc: 64 local interrupts mapped + [ 0.000000] plic: interrupt-controller@c000000: mapped 69 interrupts with 4 handlers for 9 contexts. + [ 0.000000] random: get_random_bytes called from 0xffffffe000002a6a with crng_init=0 + [ 0.000000] riscv_timer_init_dt: Registering clocksource cpuid [0] hartid [1] + [ 0.000000] clocksource: riscv_clocksource: mask: 0xffffffffffffffff max_cycles: 0x1d854df40, max_idle_ns: 352636161696s + [ 0.000007] sched_clock: 64 bits at 1000kHz, resolution 1000ns, wraps every 2199023255500ns + [ 0.008626] Console: colour dummy device 80x25 + [ 0.013049] Calibrating delay loop (skipped), value calculated using timer frequency.. 2.00 BogoMIPS (lpj=4000) + [ 0.023115] pid_max: default: 32768 minimum: 301 + [ 0.028423] Mount-cache hash table entries: 16384 (order: 5, 131072 bytes, linear) + [ 0.035919] Mountpoint-cache hash table entries: 16384 (order: 5, 131072 bytes, linear) + [ 0.045957] rcu: Hierarchical SRCU implementation. + [ 0.050393] EFI services will not be available. + [ 0.055132] smp: Bringing up secondary CPUs ... + [ 0.061824] smp: Brought up 1 node, 4 CPUs + [ 0.067458] devtmpfs: initialized + [ 0.072700] clocksource: jiffies: mask: 0xffffffff max_cycles: 0xffffffff, max_idle_ns: 7645041785100000 ns + [ 0.081789] futex hash table entries: 1024 (order: 4, 65536 bytes, linear) + [ 0.089738] NET: Registered protocol family 16 + [ 0.093999] thermal_sys: Registered thermal governor 'step_wise' + [ 0.109208] iommu: Default domain type: Translated + [ 0.119694] vgaarb: loaded + [ 0.122571] SCSI subsystem initialized + [ 0.126499] usbcore: registered new interface driver usbfs + [ 0.131686] usbcore: registered new interface driver hub + [ 0.137071] usbcore: registered new device driver usb + [ 0.142286] EDAC MC: Ver: 3.0.0 + [ 0.145760] Advanced Linux Sound Architecture Driver Initialized. + [ 0.152205] clocksource: Switched to clocksource riscv_clocksource + [ 1.046286] VFS: Disk quotas dquot_6.6.0 + [ 1.049651] VFS: Dquot-cache hash table entries: 512 (order 0, 4096 bytes) + [ 1.062844] NET: Registered protocol family 2 + [ 1.067172] tcp_listen_portaddr_hash hash table entries: 4096 (order: 4, 65536 bytes, linear) + [ 1.075455] TCP established hash table entries: 65536 (order: 7, 524288 bytes, linear) + [ 1.085428] TCP bind hash table entries: 65536 (order: 8, 1048576 bytes, linear) + [ 1.096548] TCP: Hash tables configured (established 65536 bind 65536) + [ 1.103043] UDP hash table entries: 4096 (order: 5, 131072 bytes, linear) + [ 1.109879] UDP-Lite hash table entries: 4096 (order: 5, 131072 bytes, linear) + [ 1.117413] NET: Registered protocol family 1 + [ 1.121881] RPC: Registered named UNIX socket transport module. + [ 1.127139] RPC: Registered udp transport module. + [ 1.131901] RPC: Registered tcp transport module. + [ 1.136677] RPC: Registered tcp NFSv4.1 backchannel transport module. + [ 1.143194] PCI: CLS 0 bytes, default 64 + [ 1.148359] Initialise system trusted keyrings + [ 1.152364] workingset: timestamp_bits=62 max_order=21 bucket_order=0 + [ 1.165382] NFS: Registering the id_resolver key type + [ 1.169781] Key type id_resolver registered + [ 1.174011] Key type id_legacy registered + [ 1.178179] nfs4filelayout_init: NFSv4 File Layout Driver Registering... + [ 1.184874] Installing knfsd (copyright (C) 1996 okir@monad.swb.de). + [ 1.192453] 9p: Installing v9fs 9p2000 file system support + [ 1.198116] NET: Registered protocol family 38 + [ 1.201886] Key type asymmetric registered + [ 1.206046] Asymmetric key parser 'x509' registered + [ 1.211029] Block layer SCSI generic (bsg) driver version 0.4 loaded (major 252) + [ 1.218468] io scheduler mq-deadline registered + [ 1.223072] io scheduler kyber registered + [ 1.228803] shpchp: Standard Hot Plug PCI Controller Driver version: 0.4 + [ 1.235017] fu740-pcie e00000000.pcie: FPGA PCIE PROBE + [ 1.281706] fu740-pcie e00000000.pcie: PCIE-PERSTN is GPIO 504 + [ 1.286922] fu740-pcie e00000000.pcie: PWREN is GPIO 501 + [ 1.292377] fu740-pcie e00000000.pcie: host bridge /soc/pcie@e00000000 ranges: + [ 1.299603] fu740-pcie e00000000.pcie: IO 0x0060080000..0x006008ffff -> 0x0060080000 + [ 1.307922] fu740-pcie e00000000.pcie: MEM 0x0060090000..0x0070ffffff -> 0x0060090000 + [ 1.316244] fu740-pcie e00000000.pcie: MEM 0x2000000000..0x3fffffffff -> 0x2000000000 + [ 1.432223] fu740-pcie e00000000.pcie: PWREN enabling + [ 1.436607] fu740-pcie e00000000.pcie: PWREN valid + [ 1.560226] fu740-pcie e00000000.pcie: invalid resource + [ 1.664802] fu740-pcie e00000000.pcie: Link up + [ 1.768582] fu740-pcie e00000000.pcie: Link up + [ 1.872369] fu740-pcie e00000000.pcie: Link up + [ 1.876116] fu740-pcie e00000000.pcie: Link up, Gen3 + [ 1.881352] fu740-pcie e00000000.pcie: PCI host bridge to bus 0000:00 + [ 1.887700] pci_bus 0000:00: root bus resource [bus 00-ff] + [ 1.893247] pci_bus 0000:00: root bus resource [io 0x0000-0xffff] (bus address [0x60080000-0x6008ffff]) + [ 1.902807] pci_bus 0000:00: root bus resource [mem 0x60090000-0x70ffffff] + [ 1.909748] pci_bus 0000:00: root bus resource [mem 0x2000000000-0x3fffffffff pref] + [ 1.917517] pci 0000:00:00.0: [f15e:0000] type 01 class 0x060400 + [ 1.923569] pci 0000:00:00.0: reg 0x10: [mem 0x00000000-0x000fffff] + [ 1.929902] pci 0000:00:00.0: reg 0x38: [mem 0x00000000-0x0000ffff pref] + [ 1.936723] pci 0000:00:00.0: supports D1 + [ 1.940755] pci 0000:00:00.0: PME# supported from D0 D1 D3hot + [ 1.947619] pci 0000:01:00.0: [1b21:2824] type 01 class 0x060400 + [ 1.953052] pci 0000:01:00.0: enabling Extended Tags + [ 1.958165] pci 0000:01:00.0: PME# supported from D0 D3hot D3cold + [ 1.976890] pci 0000:01:00.0: bridge configuration invalid ([bus 00-00]), reconfiguring + [ 1.984425] pci 0000:02:00.0: [1b21:2824] type 01 class 0x060400 + [ 1.990396] pci 0000:02:00.0: enabling Extended Tags + [ 1.995509] pci 0000:02:00.0: PME# supported from D0 D3hot D3cold + [ 2.001938] pci 0000:02:02.0: [1b21:2824] type 01 class 0x060400 + [ 2.007682] pci 0000:02:02.0: enabling Extended Tags + [ 2.012793] pci 0000:02:02.0: PME# supported from D0 D3hot D3cold + [ 2.019167] pci 0000:02:03.0: [1b21:2824] type 01 class 0x060400 + [ 2.024966] pci 0000:02:03.0: enabling Extended Tags + [ 2.030075] pci 0000:02:03.0: PME# supported from D0 D3hot D3cold + [ 2.036468] pci 0000:02:04.0: [1b21:2824] type 01 class 0x060400 + [ 2.042250] pci 0000:02:04.0: enabling Extended Tags + [ 2.047359] pci 0000:02:04.0: PME# supported from D0 D3hot D3cold + [ 2.053811] pci 0000:02:08.0: [1b21:2824] type 01 class 0x060400 + [ 2.059534] pci 0000:02:08.0: enabling Extended Tags + [ 2.064647] pci 0000:02:08.0: PME# supported from D0 D3hot D3cold + [ 2.071499] pci 0000:02:00.0: bridge configuration invalid ([bus 00-00]), reconfiguring + [ 2.078837] pci 0000:02:02.0: bridge configuration invalid ([bus 00-00]), reconfiguring + [ 2.086911] pci 0000:02:03.0: bridge configuration invalid ([bus 00-00]), reconfiguring + [ 2.094987] pci 0000:02:04.0: bridge configuration invalid ([bus 00-00]), reconfiguring + [ 2.103075] pci 0000:02:08.0: bridge configuration invalid ([bus 00-00]), reconfiguring + [ 2.111901] pci_bus 0000:03: busn_res: [bus 03-ff] end is updated to 03 + [ 2.118031] pci 0000:04:00.0: [1b21:1142] type 00 class 0x0c0330 + [ 2.123968] pci 0000:04:00.0: reg 0x10: [mem 0x00000000-0x00007fff 64bit] + [ 2.131038] pci 0000:04:00.0: PME# supported from D3cold + [ 2.148888] pci_bus 0000:04: busn_res: [bus 04-ff] end is updated to 04 + [ 2.155588] pci_bus 0000:05: busn_res: [bus 05-ff] end is updated to 05 + [ 2.162286] pci_bus 0000:06: busn_res: [bus 06-ff] end is updated to 06 + [ 2.168408] pci 0000:07:00.0: [126f:2263] type 00 class 0x010802 + [ 2.174351] pci 0000:07:00.0: reg 0x10: [mem 0x00000000-0x00003fff 64bit] + [ 2.192890] pci_bus 0000:07: busn_res: [bus 07-ff] end is updated to 07 + [ 2.198837] pci_bus 0000:02: busn_res: [bus 02-ff] end is updated to 07 + [ 2.205522] pci_bus 0000:01: busn_res: [bus 01-ff] end is updated to 07 + [ 2.212241] pci 0000:00:00.0: BAR 0: assigned [mem 0x60100000-0x601fffff] + [ 2.219067] pci 0000:00:00.0: BAR 14: assigned [mem 0x60200000-0x603fffff] + [ 2.226010] pci 0000:00:00.0: BAR 6: assigned [mem 0x60090000-0x6009ffff pref] + [ 2.233308] pci 0000:01:00.0: BAR 14: assigned [mem 0x60200000-0x603fffff] + [ 2.240259] pci 0000:02:02.0: BAR 14: assigned [mem 0x60200000-0x602fffff] + [ 2.247203] pci 0000:02:08.0: BAR 14: assigned [mem 0x60300000-0x603fffff] + [ 2.254150] pci 0000:02:00.0: PCI bridge to [bus 03] + [ 2.259217] pci 0000:04:00.0: BAR 0: assigned [mem 0x60200000-0x60207fff 64bit] + [ 2.266594] pci 0000:02:02.0: PCI bridge to [bus 04] + [ 2.271615] pci 0000:02:02.0: bridge window [mem 0x60200000-0x602fffff] + [ 2.278485] pci 0000:02:03.0: PCI bridge to [bus 05] + [ 2.283529] pci 0000:02:04.0: PCI bridge to [bus 06] + [ 2.288572] pci 0000:07:00.0: BAR 0: assigned [mem 0x60300000-0x60303fff 64bit] + [ 2.295952] pci 0000:02:08.0: PCI bridge to [bus 07] + [ 2.300973] pci 0000:02:08.0: bridge window [mem 0x60300000-0x603fffff] + [ 2.307842] pci 0000:01:00.0: PCI bridge to [bus 02-07] + [ 2.313133] pci 0000:01:00.0: bridge window [mem 0x60200000-0x603fffff] + [ 2.320009] pci 0000:00:00.0: PCI bridge to [bus 01-07] + [ 2.325288] pci 0000:00:00.0: bridge window [mem 0x60200000-0x603fffff] + [ 2.332808] pcieport 0000:00:00.0: AER: enabled with IRQ 51 + [ 2.337946] pcieport 0000:01:00.0: enabling device (0000 -> 0002) + [ 2.344786] pcieport 0000:02:02.0: enabling device (0000 -> 0002) + [ 2.351328] pcieport 0000:02:08.0: enabling device (0000 -> 0002) + [ 2.357091] pci 0000:04:00.0: enabling device (0000 -> 0002) + [ 2.362751] switchtec: loaded. + [ 2.365933] L2CACHE: DataError @ 0x00000003.00964470 + [ 2.365992] L2CACHE: No. of Banks in the cache: 4 + [ 2.375414] L2CACHE: No. of ways per bank: 16 + [ 2.379846] L2CACHE: Sets per bank: 512 + [ 2.383751] L2CACHE: Bytes per cache block: 64 + [ 2.388267] L2CACHE: Index of the largest way enabled: 15 + [ 2.434865] Serial: 8250/16550 driver, 4 ports, IRQ sharing disabled + [ 2.441695] 10010000.serial: ttySIF0 at MMIO 0x10010000 (irq = 1, base_baud = 115200) is a SiFive UART v0 + [ 2.450625] printk: console [ttySIF0] enabled + [ 2.450625] printk: console [ttySIF0] enabled + [ 2.459360] printk: bootconsole [sbi0] disabled + [ 2.459360] printk: bootconsole [sbi0] disabled + [ 2.468824] 10011000.serial: ttySIF1 at MMIO 0x10011000 (irq = 2, base_baud = 115200) is a SiFive UART v0 + [ 2.493853] loop: module loaded + [ 2.526475] nvme nvme0: pci function 0000:07:00.0 + [ 2.530852] nvme 0000:07:00.0: enabling device (0000 -> 0002) + [ 2.537716] Rounding down aligned max_sectors from 4294967295 to 4294967288 + [ 2.544470] db_root: cannot open: /etc/target + [ 2.545926] nvme nvme0: allocated 64 MiB host memory buffer. + [ 2.549020] sifive_spi 10040000.spi: mapped; irq=4, cs=1 + [ 2.559941] spi-nor spi0.0: is25wp256 (32768 Kbytes) + [ 2.566431] sifive_spi 10050000.spi: mapped; irq=6, cs=1 + [ 2.566707] nvme nvme0: 4/0/0 default/read/poll queues + [ 2.571935] libphy: Fixed MDIO Bus: probed + [ 2.580950] macb 10090000.ethernet: Registered clk switch 'sifive-gemgxl-mgmt' + [ 2.587536] macb 10090000.ethernet: invalid hw address, using random + [ 2.588100] nvme0n1: p1 p2 + [ 2.593875] BEU: Load or Store TILINK BUS ERR occurred + [ 2.594342] libphy: MACB_mii_bus: probed + [ 2.599312] macb 10090000.ethernet eth0: Cadence GEM rev 0x10070109 at 0x10090000 irq 7 (5e:57:b8:ab:24:4a) + [ 2.615501] e1000e: Intel(R) PRO/1000 Network Driver + [ 2.620251] e1000e: Copyright(c) 1999 - 2015 Intel Corporation. + [ 2.626463] ehci_hcd: USB 2.0 'Enhanced' Host Controller (EHCI) Driver + [ 2.632684] ehci-pci: EHCI PCI platform driver + [ 2.637144] ohci_hcd: USB 1.1 'Open' Host Controller (OHCI) Driver + [ 2.643273] ohci-pci: OHCI PCI platform driver + [ 2.647731] uhci_hcd: USB Universal Host Controller Interface driver + [ 2.654315] xhci_hcd 0000:04:00.0: xHCI Host Controller + [ 2.659450] xhci_hcd 0000:04:00.0: new USB bus registered, assigned bus number 1 + [ 2.807373] xhci_hcd 0000:04:00.0: hcc params 0x0200e081 hci version 0x100 quirks 0x0000000010000410 + [ 2.816609] usb usb1: New USB device found, idVendor=1d6b, idProduct=0002, bcdDevice= 5.10 + [ 2.824115] usb usb1: New USB device strings: Mfr=3, Product=2, SerialNumber=1 + [ 2.831312] usb usb1: Product: xHCI Host Controller + [ 2.836174] usb usb1: Manufacturer: Linux 5.10.15 xhci-hcd + [ 2.841652] usb usb1: SerialNumber: 0000:04:00.0 + [ 2.846639] hub 1-0:1.0: USB hub found + [ 2.850037] hub 1-0:1.0: 2 ports detected + [ 2.854306] xhci_hcd 0000:04:00.0: xHCI Host Controller + [ 2.859335] xhci_hcd 0000:04:00.0: new USB bus registered, assigned bus number 2 + [ 2.866599] xhci_hcd 0000:04:00.0: Host supports USB 3.0 SuperSpeed + [ 2.873638] usb usb2: We don't know the algorithms for LPM for this host, disabling LPM. + [ 2.881074] usb usb2: New USB device found, idVendor=1d6b, idProduct=0003, bcdDevice= 5.10 + [ 2.889212] usb usb2: New USB device strings: Mfr=3, Product=2, SerialNumber=1 + [ 2.896422] usb usb2: Product: xHCI Host Controller + [ 2.901282] usb usb2: Manufacturer: Linux 5.10.15 xhci-hcd + [ 2.906752] usb usb2: SerialNumber: 0000:04:00.0 + [ 2.911671] hub 2-0:1.0: USB hub found + [ 2.915130] hub 2-0:1.0: 2 ports detected + [ 2.919486] usbcore: registered new interface driver usb-storage + [ 2.925212] usbcore: registered new interface driver usbserial_generic + [ 2.931620] usbserial: USB Serial support registered for generic + [ 2.937771] mousedev: PS/2 mouse device common for all mice + [ 2.943220] usbcore: registered new interface driver usbtouchscreen + [ 2.949466] i2c /dev entries driver + [ 2.954218] lm90 0-004c: supply vcc not found, using dummy regulator + [ 2.961629] EDAC DEVICE0: Giving out device to module Sifive ECC Manager controller sifive_edac.0: DEV sifive_edac.0 (I) + [ 2.997874] mmc_spi spi1.0: SD/MMC host mmc0, no DMA, no WP, no poweroff, cd polling + [ 3.005138] ledtrig-cpu: registered to indicate activity on CPUs + [ 3.010980] usbcore: registered new interface driver usbhid + [ 3.016407] usbhid: USB HID core driver + [ 3.020540] usbcore: registered new interface driver snd-usb-audio + [ 3.027209] NET: Registered protocol family 10 + [ 3.031878] Segment Routing with IPv6 + [ 3.034864] sit: IPv6, IPv4 and MPLS over IPv4 tunneling driver + [ 3.041232] NET: Registered protocol family 17 + [ 3.045324] 9pnet: Installing 9P2000 support + [ 3.049397] Key type dns_resolver registered + [ 3.053786] Loading compiled-in X.509 certificates + [ 3.059729] ALSA device list: + [ 3.061943] No soundcards found. + [ 3.066057] Waiting for root device /dev/mmcblk0p4... + [ 3.077319] mmc0: host does not support reading read-only switch, assuming write-enable + [ 3.084564] mmc0: new SDHC card on SPI + [ 3.089699] mmcblk0: mmc0:0000 SD32G 29.7 GiB + [ 3.126488] GPT:Primary header thinks Alt. header is not at the end of the disk. + [ 3.133144] GPT:13918241 != 62333951 + [ 3.136679] GPT:Alternate GPT header not at the end of the disk. + [ 3.142673] GPT:13918241 != 62333951 + [ 3.146231] GPT: Use GNU Parted to correct GPT errors. + [ 3.151398] mmcblk0: p1 p2 p3 p4 + [ 3.212226] usb 1-2: new high-speed USB device number 2 using xhci_hcd + [ 3.258310] EXT4-fs (mmcblk0p4): INFO: recovery required on readonly filesystem + [ 3.264855] EXT4-fs (mmcblk0p4): write access will be enabled during recovery + [ 3.458247] usb 1-2: New USB device found, idVendor=174c, idProduct=2074, bcdDevice= 0.01 + [ 3.465662] usb 1-2: New USB device strings: Mfr=2, Product=3, SerialNumber=1 + [ 3.472775] usb 1-2: Product: AS2107 + [ 3.476336] usb 1-2: Manufacturer: ASMedia + [ 3.480419] usb 1-2: SerialNumber: USB2.0 Hub + [ 3.533583] EXT4-fs (mmcblk0p4): recovery complete + [ 3.543756] EXT4-fs (mmcblk0p4): mounted filesystem with ordered data mode. Opts: (null) + [ 3.551132] VFS: Mounted root (ext4 filesystem) readonly on device 179:4. + [ 3.554682] hub 1-2:1.0: USB hub found + [ 3.561105] devtmpfs: mounted + [ 3.561778] hub 1-2:1.0: 4 ports detected + [ 3.565546] Freeing unused kernel memory: 284K + [ 3.572964] Kernel memory protection not selected by kernel config. + [ 3.579225] Run /sbin/init as init process + [ 3.613136] usb 2-2: new SuperSpeed Gen 1 USB device number 2 using xhci_hcd + [ 3.643539] usb 2-2: New USB device found, idVendor=174c, idProduct=3074, bcdDevice= 0.01 + [ 3.650948] usb 2-2: New USB device strings: Mfr=2, Product=3, SerialNumber=1 + [ 3.658072] usb 2-2: Product: AS2107 + [ 3.661630] usb 2-2: Manufacturer: ASMedia + [ 3.665709] usb 2-2: SerialNumber: USB2.0 Hub + [ 3.762380] hub 2-2:1.0: USB hub found + [ 3.766074] hub 2-2:1.0: 4 ports detected + [ 7.487226] systemd[1]: System time before build time, advancing clock. + [ 7.788093] systemd[1]: systemd 247.2+ running in system mode. (+PAM -AUDIT -SELINUX +IMA -APPARMOR -SMACK +SYSVINIT +U) + [ 7.809694] systemd[1]: Detected architecture riscv64. + + Welcome to OpenEmbedded nodistro.0! + + [ 7.832648] systemd[1]: Set hostname to <unmatched>. + [ 9.397499] systemd[1]: Queued start job for default target Multi-User System. + [ 9.408518] random: systemd: uninitialized urandom read (16 bytes read) + [ 9.429329] systemd[1]: Created slice system-getty.slice. + [ OK ] Created slice system-getty.slice. + [ 9.440400] random: systemd: uninitialized urandom read (16 bytes read) + [ 9.447086] systemd[1]: Created slice system-modprobe.slice. + [ OK ] Created slice system-modprobe.slice. + [ 9.458480] random: systemd: uninitialized urandom read (16 bytes read) + [ 9.465436] systemd[1]: Created slice system-serial\x2dgetty.slice. + [ OK ] Created slice system-serial\x2dgetty.slice. + [ 9.478594] systemd[1]: Created slice User and Session Slice. + [ OK ] Created slice User and Session Slice. + [ 9.490225] systemd[1]: Started Dispatch Password Requests to Console Directory Watch. + [ OK ] Started Dispatch Password ��…ts to Console Directory Watch. + [ 9.506407] systemd[1]: Started Forward Password Requests to Wall Directory Watch. + [ OK ] Started Forward Password R��…uests to Wall Directory Watch. + [ 9.522312] systemd[1]: Reached target Paths. + [ OK ] Reached target Paths. + [ 9.531078] systemd[1]: Reached target Remote File Systems. + [ OK ] Reached target Remote File Systems. + [ 9.542855] systemd[1]: Reached target Slices. + [ OK ] Reached target Slices. + [ 9.552712] systemd[1]: Reached target Swap. + [ OK ] Reached target Swap. + [ 9.561566] systemd[1]: Listening on initctl Compatibility Named Pipe. + [ OK ] Listening on initctl Compatibility Named Pipe. + [ 9.578686] systemd[1]: Condition check resulted in Journal Audit Socket being skipped. + [ 9.586545] systemd[1]: Listening on Journal Socket (/dev/log). + [ OK ] Listening on Journal Socket (/dev/log). + + [snip] + + [ OK ] Reached target System Time Synchronized. + [ OK ] Reached target Timers. + [ OK ] Listening on D-Bus System Message Bus Socket. + [ OK ] Reached target Sockets. + [ OK ] Reached target Basic System. + [ OK ] Started D-Bus System Message Bus. + Starting User Login Management... + Starting Permit User Sessions... + [ OK ] Started Xinetd A Powerful Replacement For Inetd. + [ OK ] Finished Permit User Sessions. + [ OK ] Started Getty on tty1. + [ OK ] Started Serial Getty on hvc0. + [ OK ] Started Serial Getty on ttySIF0. + [ OK ] Reached target Login Prompts. + [ OK ] Started User Login Management. + [ OK ] Reached target Multi-User System. + Starting Update UTMP about System Runlevel Changes... + [ OK ] Finished Update UTMP about System Runlevel Changes. + + OpenEmbedded nodistro.0 unmatched hvc0 + + unmatched login: + OpenEmbedded nodistro.0 unmatched ttySIF0 + + unmatched login: diff --git a/roms/u-boot/doc/board/sipeed/index.rst b/roms/u-boot/doc/board/sipeed/index.rst new file mode 100644 index 000000000..3518e2d8f --- /dev/null +++ b/roms/u-boot/doc/board/sipeed/index.rst @@ -0,0 +1,9 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +Sipeed +====== + +.. toctree:: + :maxdepth: 2 + + maix diff --git a/roms/u-boot/doc/board/sipeed/maix.rst b/roms/u-boot/doc/board/sipeed/maix.rst new file mode 100644 index 000000000..ef79297ef --- /dev/null +++ b/roms/u-boot/doc/board/sipeed/maix.rst @@ -0,0 +1,697 @@ +.. SPDX-License-Identifier: GPL-2.0+ +.. Copyright (C) 2020 Sean Anderson <seanga2@gmail.com> + +MAIX +==== + +Several of the Sipeed Maix series of boards cotain the Kendryte K210 processor, +a 64-bit RISC-V CPU. This processor contains several peripherals to accelerate +neural network processing and other "ai" tasks. This includes a "KPU" neural +network processor, an audio processor supporting beamforming reception, and a +digital video port supporting capture and output at VGA resolution. Other +peripherals include 8M of SRAM (accessible with and without caching); remappable +pins, including 40 GPIOs; AES, FFT, and SHA256 accelerators; a DMA controller; +and I2C, I2S, and SPI controllers. Maix peripherals vary, but include spi flash; +on-board usb-serial bridges; ports for cameras, displays, and sd cards; and +ESP32 chips. + +Currently, only the Sipeed MAIX BiT V2.0 (bitm) and Sipeed MAIXDUINO are +supported, but the boards are fairly similar. + +Documentation for Maix boards is available from +`Sipeed's website <http://dl.sipeed.com/MAIX/HDK/>`_. +Documentation for the Kendryte K210 is available from +`Kendryte's website <https://kendryte.com/downloads/>`_. However, hardware +details are rather lacking, so most technical reference has been taken from the +`standalone sdk <https://github.com/kendryte/kendryte-standalone-sdk>`_. + +Build and boot steps +-------------------- + +To build U-Boot, run + +.. code-block:: none + + make <defconfig> + make CROSS_COMPILE=<your cross compile prefix> + +To flash U-Boot, run + +.. code-block:: none + + kflash -tp /dev/<your tty here> -B <board_id> u-boot-dtb.bin + +The board provides two serial devices, e.g. + +* /dev/serial/by-id/usb-Kongou_Hikari_Sipeed-Debug_12345678AB-if00-port0 +* /dev/serial/by-id/usb-Kongou_Hikari_Sipeed-Debug_12345678AB-if01-port0 + +Which one is used for flashing depends on the board. + +Currently only a small subset of the board features are supported. So we can +use the same default configuration and device tree. In the long run we may need +separate settings. + +======================== ========================== ========== ========== +Board defconfig board_id TTY device +======================== ========================== ========== ========== +Sipeed MAIX BiT sipeed_maix_bitm_defconfig bit first +Sipeed MAIX BiT with Mic sipeed_maix_bitm_defconfig bit_mic first +Sipeed MAIXDUINO sipeed_maix_bitm_defconfig maixduino first +Sipeed MAIX GO goE second +Sipeed MAIX ONE DOCK dan first +======================== ========================== ========== ========== + +Flashing causes a reboot of the device. Parameter -t specifies that the serial +console shall be opened immediately. Boot output should look like the following: + +.. code-block:: none + + U-Boot 2020.04-rc2-00087-g2221cc09c1-dirty (Feb 28 2020 - 13:53:09 -0500) + + DRAM: 8 MiB + MMC: spi@53000000:slot@0: 0 + In: serial@38000000 + Out: serial@38000000 + Err: serial@38000000 + => + +OpenSBI +^^^^^^^ + +OpenSBI is an open source supervisor execution environment implementing the +RISC-V Supervisor Binary Interface Specification [1]. One of its features is +to intercept run-time exceptions, e.g. for unaligned access or illegal +instructions, and to emulate the failing instructions. + +The OpenSBI source can be downloaded via: + +.. code-block:: bash + + git clone https://github.com/riscv/opensbi + +As OpenSBI will be loaded at 0x80000000 we have to adjust the U-Boot text base. +Furthermore we have to enable building U-Boot for S-mode:: + + CONFIG_SYS_TEXT_BASE=0x80020000 + CONFIG_RISCV_SMODE=y + +Both settings are contained in sipeed_maix_smode_defconfig so we can build +U-Boot with: + +.. code-block:: bash + + make sipeed_maix_smode_defconfig + make + +To build OpenSBI with U-Boot as a payload: + +.. code-block:: bash + + cd opensbi + make \ + PLATFORM=kendryte/k210 \ + FW_PAYLOAD=y \ + FW_PAYLOAD_OFFSET=0x20000 \ + FW_PAYLOAD_PATH=<path to U-Boot>/u-boot-dtb.bin + +The value of FW_PAYLOAD_OFFSET must match CONFIG_SYS_TEXT_BASE - 0x80000000. + +The file to flash is build/platform/kendryte/k210/firmware/fw_payload.bin. + +Booting +^^^^^^^ + +The default boot process is to load and boot the files ``/uImage`` and +``/k210.dtb`` off of the first partition of the MMC. For Linux, this will result +in an output like + +.. code-block:: none + + U-Boot 2020.10-00691-gd1d651d988-dirty (Oct 16 2020 - 17:05:24 -0400) + + DRAM: 8 MiB + MMC: spi@53000000:slot@0: 0 + Loading Environment from SPIFlash... SF: Detected w25q128fw with page size 256 Bytes, erase size 4 KiB, total 16 MiB + OK + In: serial@38000000 + Out: serial@38000000 + Err: serial@38000000 + Hit any key to stop autoboot: 0 + 1827380 bytes read in 1044 ms (1.7 MiB/s) + 13428 bytes read in 10 ms (1.3 MiB/s) + ## Booting kernel from Legacy Image at 80060000 ... + Image Name: linux + Image Type: RISC-V Linux Kernel Image (uncompressed) + Data Size: 1827316 Bytes = 1.7 MiB + Load Address: 80000000 + Entry Point: 80000000 + Verifying Checksum ... OK + ## Flattened Device Tree blob at 80400000 + Booting using the fdt blob at 0x80400000 + Loading Kernel Image + Loading Device Tree to 00000000803f9000, end 00000000803ff473 ... OK + + Starting kernel ... + + [ 0.000000] Linux version 5.9.0-00021-g6dcc2f0814c6-dirty (sean@godwin) (riscv64-linux-gnu-gcc (GCC) 10.2.0, GNU ld (GNU Binutils) 2.35) #34 SMP Fri Oct 16 14:40:57 EDT 2020 + [ 0.000000] earlycon: sifive0 at MMIO 0x0000000038000000 (options '115200n8') + [ 0.000000] printk: bootconsole [sifive0] enabled + [ 0.000000] Zone ranges: + [ 0.000000] DMA32 [mem 0x0000000080000000-0x00000000807fffff] + [ 0.000000] Normal empty + [ 0.000000] Movable zone start for each node + [ 0.000000] Early memory node ranges + [ 0.000000] node 0: [mem 0x0000000080000000-0x00000000807fffff] + [ 0.000000] Initmem setup node 0 [mem 0x0000000080000000-0x00000000807fffff] + [ 0.000000] riscv: ISA extensions acdfgim + [ 0.000000] riscv: ELF capabilities acdfim + [ 0.000000] percpu: max_distance=0x18000 too large for vmalloc space 0x0 + [ 0.000000] percpu: Embedded 12 pages/cpu s18848 r0 d30304 u49152 + [ 0.000000] Built 1 zonelists, mobility grouping off. Total pages: 2020 + [ 0.000000] Kernel command line: earlycon console=ttySIF0 + [ 0.000000] Dentry cache hash table entries: 1024 (order: 1, 8192 bytes, linear) + [ 0.000000] Inode-cache hash table entries: 512 (order: 0, 4096 bytes, linear) + [ 0.000000] Sorting __ex_table... + [ 0.000000] mem auto-init: stack:off, heap alloc:off, heap free:off + [ 0.000000] Memory: 6004K/8192K available (1139K kernel code, 126K rwdata, 198K rodata, 90K init, 81K bss, 2188K reserved, 0K cma-reserved) + [ 0.000000] rcu: Hierarchical RCU implementation. + [ 0.000000] rcu: RCU calculated value of scheduler-enlistment delay is 25 jiffies. + [ 0.000000] NR_IRQS: 64, nr_irqs: 64, preallocated irqs: 0 + [ 0.000000] riscv-intc: 64 local interrupts mapped + [ 0.000000] plic: interrupt-controller@C000000: mapped 65 interrupts with 2 handlers for 2 contexts. + [ 0.000000] random: get_random_bytes called from 0x00000000800019a8 with crng_init=0 + [ 0.000000] k210-clk: clock-controller + [ 0.000000] k210-clk: clock-controller: fixed-rate 26 MHz osc base clock + [ 0.000000] clint: clint@2000000: timer running at 7800000 Hz + [ 0.000000] clocksource: clint_clocksource: mask: 0xffffffffffffffff max_cycles: 0x3990be68b, max_idle_ns: 881590404272 ns + [ 0.000014] sched_clock: 64 bits at 7MHz, resolution 128ns, wraps every 4398046511054ns + [ 0.008450] Console: colour dummy device 80x25 + [ 0.012494] Calibrating delay loop (skipped), value calculated using timer frequency.. 15.60 BogoMIPS (lpj=31200) + [ 0.022693] pid_max: default: 4096 minimum: 301 + [ 0.027352] Mount-cache hash table entries: 512 (order: 0, 4096 bytes, linear) + [ 0.034428] Mountpoint-cache hash table entries: 512 (order: 0, 4096 bytes, linear) + [ 0.045099] rcu: Hierarchical SRCU implementation. + [ 0.050048] smp: Bringing up secondary CPUs ... + [ 0.055417] smp: Brought up 1 node, 2 CPUs + [ 0.059602] devtmpfs: initialized + [ 0.082796] clocksource: jiffies: mask: 0xffffffff max_cycles: 0xffffffff, max_idle_ns: 7645041785100000 ns + [ 0.091820] futex hash table entries: 16 (order: -2, 1024 bytes, linear) + [ 0.098507] pinctrl core: initialized pinctrl subsystem + [ 0.140938] clocksource: Switched to clocksource clint_clocksource + [ 0.247216] workingset: timestamp_bits=62 max_order=11 bucket_order=0 + [ 0.277392] k210-fpioa 502b0000.pinmux: K210 FPIOA pin controller + [ 0.291724] k210-sysctl 50440000.syscon: K210 system controller + [ 0.305317] k210-rst 50440000.syscon:reset-controller: K210 reset controller + [ 0.313808] 38000000.serial: ttySIF0 at MMIO 0x38000000 (irq = 1, base_baud = 115200) is a SiFive UART v0 + [ 0.322712] printk: console [ttySIF0] enabled + [ 0.322712] printk: console [ttySIF0] enabled + [ 0.331328] printk: bootconsole [sifive0] disabled + [ 0.331328] printk: bootconsole [sifive0] disabled + [ 0.353347] Freeing unused kernel memory: 88K + [ 0.357004] This architecture does not have kernel memory protection. + [ 0.363397] Run /init as init process + +Loading, Booting, and Storing Images +------------------------------------ + +.. _loading: + +Loading Images +^^^^^^^^^^^^^^ + +Serial +"""""" + +Use the ``loady`` command to load images over serial. + +.. code-block:: none + + => loady $loadaddr 1500000 + ## Switch baudrate to 1500000 bps and press ENTER ... + + *** baud: 1500000 + + *** baud: 1500000 *** + ## Ready for binary (ymodem) download to 0x80000000 at 1500000 bps... + C + *** file: loader.bin + $ sz -vv loader.bin + Sending: loader.bin + Bytes Sent:2478208 BPS:72937 + Sending: + Ymodem sectors/kbytes sent: 0/ 0k + Transfer complete + + *** exit status: 0 *** + ## Total Size = 0x0025d052 = 2478162 Bytes + ## Switch baudrate to 115200 bps and press ESC ... + + *** baud: 115200 + + *** baud: 115200 *** + => + +This command does not set ``$filesize``, so it may need to be set manually. + +SPI Flash +""""""""" + +To load an image off of SPI flash, first set up a partition as described in +:ref:`k210_partitions`. Then, use ``mtd`` to load that partition + +.. code-block:: none + + => sf probe + SF: Detected w25q128fw with page size 256 Bytes, erase size 4 KiB, total 16 MiB + => mtd read linux $loadaddr + Reading 2097152 byte(s) at offset 0x00000000 + +This command does not set ``$filesize``, so it may need to be set manually. + +MMC +""" + +The MMC device number is 0. To list partitions on the device, use ``part``: + +.. code-block:: none + + => part list mmc 0 + + Partition Map for MMC device 0 -- Partition Type: EFI + + Part Start LBA End LBA Name + Attributes + Type GUID + Partition GUID + 1 0x00000800 0x039effde "boot" + attrs: 0x0000000000000000 + type: c12a7328-f81f-11d2-ba4b-00a0c93ec93b + guid: 96161f7d-7113-4cc7-9a24-08ab7fc5cb72 + +To list files, use ``ls``: + +.. code-block:: none + + => ls mmc 0:1 + <DIR> 4096 . + <DIR> 4096 .. + <DIR> 16384 lost+found + 13428 k210.dtb + 1827380 uImage + +To load a file, use ``load``: + +.. code-block:: none + + => load mmc 0:1 $loadaddr uImage + 1827380 bytes read in 1049 ms (1.7 MiB/s) + +Running Programs +^^^^^^^^^^^^^^^^ + +Binaries +"""""""" + +To run a bare binary, use the ``go`` command: + +.. code-block:: none + + => go 80000000 + ## Starting application at 0x80000000 ... + Example expects ABI version 9 + Actual U-Boot ABI version 9 + Hello World + argc = 1 + argv[0] = "80000000" + argv[1] = "<NULL>" + Hit any key to exit ... + +Note that this will only start a program on one hart. As-of this writing it is +only possible to start a program on multiple harts using the ``bootm`` command. + +Legacy Images +""""""""""""" + +To create a legacy image, use ``tools/mkimage``: + +.. code-block:: none + + $ tools/mkimage -A riscv -O linux -T kernel -C none -a 0x80000000 -e 0x80000000 -n linux -d ../linux-git/arch/riscv/boot/Image uImage + Image Name: linux + Created: Fri Oct 16 17:36:32 2020 + Image Type: RISC-V Linux Kernel Image (uncompressed) + Data Size: 1827316 Bytes = 1784.49 KiB = 1.74 MiB + Load Address: 80000000 + Entry Point: 80000000 + +The ``bootm`` command also requires an FDT, even if the image doesn't require +one. After loading the image to ``$loadaddr`` and the FDT to ``$fdt_addr_r``, +boot with: + +.. code-block:: none + + => bootm $loadaddr - $fdt_addr_r + ## Booting kernel from Legacy Image at 80060000 ... + Image Name: linux + Image Type: RISC-V Linux Kernel Image (uncompressed) + Data Size: 1827316 Bytes = 1.7 MiB + Load Address: 80000000 + Entry Point: 80000000 + Verifying Checksum ... OK + ## Flattened Device Tree blob at 80400000 + Booting using the fdt blob at 0x80400000 + Loading Kernel Image + Loading Device Tree to 00000000803f9000, end 00000000803ff473 ... OK + + Starting kernel ... + +The FDT is verified after the kernel is relocated, so it must be loaded high +enough so that it won't be overwritten. The default values for ``$loadaddr`` +and ``$fdt_addr_r`` should provide ample headroom for most use-cases. + +Flashing Images +^^^^^^^^^^^^^^^ + +SPI Flash +""""""""" + +To flash data to SPI flash, first load it using one of the methods in +:ref:`loading`. Addiotionally, create some partitions as described in +:ref:`partitions`. Then use the ``mtd`` command: + +.. code-block:: none + + => sf probe + SF: Detected w25q128fw with page size 256 Bytes, erase size 4 KiB, total 16 MiB + => mtd write linux $loadaddr 0 $filesize + Writing 2478162 byte(s) at offset 0x00000000 + +Note that in order to write a bootable image, a header and tailer must be added. + +MMC +""" + +MMC writes are unsupported for now. + +SPI Flash +^^^^^^^^^ + +Sipeed MAIX boards typically provide around 16 MiB of SPI NOR flash. U-Boot is +stored in the first 1 MiB or so of this flash. U-Boot's environment is stored at +the end of flash. + +.. _k210_partitions: + +Partitions +"""""""""" + +There is no set data layout. The default partition layout only allocates +partitions for U-Boot and its default environment + +.. code-block:: none + + => mtd list + List of MTD devices: + * nor0 + - type: NOR flash + - block size: 0x1000 bytes + - min I/O: 0x1 bytes + - 0x000000000000-0x000001000000 : "nor0" + - 0x000000000000-0x000000100000 : "u-boot" + - 0x000000fff000-0x000001000000 : "env" + +As an example, to allocate 2MiB for Linux and (almost) 13 MiB for other data, +set the ``mtdparts`` like: + +.. code-block:: none + + => env set mtdparts nor0:1M(u-boot),2M(linux),0xcff000(data),0x1000@0xfff000(env) + => mtd list + List of MTD devices: + * nor0 + - type: NOR flash + - block size: 0x1000 bytes + - min I/O: 0x1 bytes + - 0x000000000000-0x000001000000 : "nor0" + - 0x000000000000-0x000000100000 : "u-boot" + - 0x000000100000-0x000000300000 : "linux" + - 0x000000300000-0x000000fff000 : "data" + - 0x000000fff000-0x000001000000 : "env" + +To make these changes permanent, save the environment: + +.. code-block:: none + + => env save + Saving Environment to SPIFlash... Erasing SPI flash...Writing to SPI flash...done + OK + +U-Boot will always load the environment from the last 4 KiB of flash. + +Pin Assignment +-------------- + +The K210 contains a Fully Programmable I/O Array (FPIOA), which can remap any of +its 256 input functions to any any of 48 output pins. The following table has +the default pin assignments for the BitM. + +===== ========== ======= +Pin Function Comment +===== ========== ======= +IO_0 JTAG_TCLK +IO_1 JTAG_TDI +IO_2 JTAG_TMS +IO_3 JTAG_TDO +IO_4 UARTHS_RX +IO_5 UARTHS_TX +IO_6 Not set +IO_7 Not set +IO_8 GPIO_0 +IO_9 GPIO_1 +IO_10 GPIO_2 +IO_11 GPIO_3 +IO_12 GPIO_4 Green LED +IO_13 GPIO_5 Red LED +IO_14 GPIO_6 Blue LED +IO_15 GPIO_7 +IO_16 GPIOHS_0 ISP +IO_17 GPIOHS_1 +IO_18 I2S0_SCLK MIC CLK +IO_19 I2S0_WS MIC WS +IO_20 I2S0_IN_D0 MIC SD +IO_21 GPIOHS_5 +IO_22 GPIOHS_6 +IO_23 GPIOHS_7 +IO_24 GPIOHS_8 +IO_25 GPIOHS_9 +IO_26 SPI1_D1 MMC MISO +IO_27 SPI1_SCLK MMC CLK +IO_28 SPI1_D0 MMC MOSI +IO_29 GPIOHS_13 MMC CS +IO_30 GPIOHS_14 +IO_31 GPIOHS_15 +IO_32 GPIOHS_16 +IO_33 GPIOHS_17 +IO_34 GPIOHS_18 +IO_35 GPIOHS_19 +IO_36 GPIOHS_20 Panel CS +IO_37 GPIOHS_21 Panel RST +IO_38 GPIOHS_22 Panel DC +IO_39 SPI0_SCK Panel WR +IO_40 SCCP_SDA +IO_41 SCCP_SCLK +IO_42 DVP_RST +IO_43 DVP_VSYNC +IO_44 DVP_PWDN +IO_45 DVP_HSYNC +IO_46 DVP_XCLK +IO_47 DVP_PCLK +===== ========== ======= + +Over- and Under-clocking +------------------------ + +To change the clock speed of the K210, you will need to enable +``CONFIG_CLK_K210_SET_RATE`` and edit the board's device tree. To do this, add a +section to ``arch/riscv/arch/riscv/dts/k210-maix-bit.dts`` like the following: + +.. code-block:: none + + &sysclk { + assigned-clocks = <&sysclk K210_CLK_PLL0>; + assigned-clock-rates = <800000000>; + }; + +There are three PLLs on the K210: PLL0 is the parent of most of the components, +including the CPU and RAM. PLL1 is the parent of the neural network coprocessor. +PLL2 is the parent of the sound processing devices. Note that child clocks of +PLL0 and PLL2 run at *half* the speed of the PLLs. For example, if PLL0 is +running at 800 MHz, then the CPU will run at 400 MHz. This is the example given +above. The CPU can be overclocked to around 600 MHz, and underclocked to 26 MHz. + +It is possible to set PLL2's parent to PLL0. The plls are more accurate when +converting between similar frequencies. This makes it easier to get an accurate +frequency for I2S. As an example, consider sampling an I2S device at 44.1 kHz. +On this device, the I2S serial clock runs at 64 times the sample rate. +Therefore, we would like to run PLL2 at an even multiple of 2.8224 MHz. If +PLL2's parent is IN0, we could use a frequency of 390 MHz (the same as the CPU's +default speed). Dividing by 138 yields a serial clock of about 2.8261 MHz. This +results in a sample rate of 44.158 kHz---around 50 Hz or .1% too fast. If, +instead, we set PLL2's parent to PLL1 running at 390 MHz, and request a rate of +2.8224 * 136 = 383.8464 MHz, the achieved rate is 383.90625 MHz. Dividing by 136 +yields a serial clock of about 2.8228 MHz. This results in a sample rate of +44.107 kHz---just 7 Hz or .02% too fast. This configuration is shown in the +following example: + +.. code-block:: none + + &sysclk { + assigned-clocks = <&sysclk K210_CLK_PLL1>, <&sysclk K210_CLK_PLL2>; + assigned-clock-parents = <0>, <&sysclk K210_CLK_PLL1>; + assigned-clock-rates = <390000000>, <383846400>; + }; + +There are a couple of quirks to the PLLs. First, there are more frequency ratios +just above and below 1.0, but there is a small gap around 1.0. To be explicit, +if the input frequency is 100 MHz, it would be impossible to have an output of +99 or 101 MHz. In addition, there is a maximum frequency for the internal VCO, +so higher input/output frequencies will be less accurate than lower ones. + +Technical Details +----------------- + +Boot Sequence +^^^^^^^^^^^^^ + +1. ``RESET`` pin is deasserted. The pin is connected to the ``RESET`` button. It + can also be set to low via either the ``DTR`` or the ``RTS`` line of the + serial interface (depending on the board). +2. Both harts begin executing at ``0x00001000``. +3. Both harts jump to firmware at ``0x88000000``. +4. One hart is chosen as a boot hart. +5. Firmware reads the value of pin ``IO_16`` (ISP). This pin is connected to the + ``BOOT`` button. The pin can equally be set to low via either the ``DTR`` or + ``RTS`` line of the serial interface (depending on the board). + + * If the pin is low, enter ISP mode. This mode allows loading data to ram, + writing it to flash, and booting from specific addresses. + * If the pin is high, continue boot. +6. Firmware reads the next stage from flash (SPI3) to address ``0x80000000``. + + * If byte 0 is 1, the next stage is decrypted using the built-in AES + accelerator and the one-time programmable, 128-bit AES key. + * Bytes 1 to 4 hold the length of the next stage. + * The SHA-256 sum of the next stage is automatically calculated, and verified + against the 32 bytes following the next stage. +7. The boot hart sends an IPI to the other hart telling it to jump to the next + stage. +8. The boot hart jumps to ``0x80000000``. + +Debug UART +^^^^^^^^^^ + +The Debug UART is provided with the following settings:: + + CONFIG_DEBUG_UART=y + CONFIG_DEBUG_UART_SIFIVE=y + CONFIG_DEBUG_UART_BASE=0x38000000 + CONFIG_DEBUG_UART_CLOCK=390000000 + +Resetting the board +^^^^^^^^^^^^^^^^^^^ + +The MAIX boards can be reset using the DTR and RTS lines of the serial console. +How the lines are used depends on the specific board. See the code of kflash.py +for details. + +This is the reset sequence for the MAXDUINO and MAIX BiT with Mic: + +.. code-block:: python + + def reset(self): + self.device.setDTR(False) + self.device.setRTS(False) + time.sleep(0.1) + self.device.setDTR(True) + time.sleep(0.1) + self.device.setDTR(False) + time.sleep(0.1) + +and this for the MAIX Bit: + +.. code-block:: python + + def reset(self): + self.device.setDTR(False) + self.device.setRTS(False) + time.sleep(0.1) + self.device.setRTS(True) + time.sleep(0.1) + self.device.setRTS(False) + time.sleep(0.1) + +Memory Map +^^^^^^^^^^ + +========== ========= =========== +Address Size Description +========== ========= =========== +0x00000000 0x1000 debug +0x00001000 0x1000 rom +0x02000000 0xC000 clint +0x0C000000 0x4000000 plic +0x38000000 0x1000 uarths +0x38001000 0x1000 gpiohs +0x40000000 0x400000 sram0 (non-cached) +0x40400000 0x200000 sram1 (non-cached) +0x40600000 0x200000 airam (non-cached) +0x40800000 0xC00000 kpu +0x42000000 0x400000 fft +0x50000000 0x1000 dmac +0x50200000 0x200000 apb0 +0x50200000 0x80 gpio +0x50210000 0x100 uart0 +0x50220000 0x100 uart1 +0x50230000 0x100 uart2 +0x50240000 0x100 spi slave +0x50250000 0x200 i2s0 +0x50250200 0x200 apu +0x50260000 0x200 i2s1 +0x50270000 0x200 i2s2 +0x50280000 0x100 i2c0 +0x50290000 0x100 i2c1 +0x502A0000 0x100 i2c2 +0x502B0000 0x100 fpioa +0x502C0000 0x100 sha256 +0x502D0000 0x100 timer0 +0x502E0000 0x100 timer1 +0x502F0000 0x100 timer2 +0x50400000 0x200000 apb1 +0x50400000 0x100 wdt0 +0x50410000 0x100 wdt1 +0x50420000 0x100 otp control +0x50430000 0x100 dvp +0x50440000 0x100 sysctl +0x50450000 0x100 aes +0x50460000 0x100 rtc +0x52000000 0x4000000 apb2 +0x52000000 0x100 spi0 +0x53000000 0x100 spi1 +0x54000000 0x200 spi3 +0x80000000 0x400000 sram0 (cached) +0x80400000 0x200000 sram1 (cached) +0x80600000 0x200000 airam (cached) +0x88000000 0x20000 otp +0x88000000 0xC200 firmware +0x8801C000 0x1000 riscv priv spec 1.9 config +0x8801D000 0x2000 flattened device tree (contains only addresses and + interrupts) +0x8801F000 0x1000 credits +========== ========= =========== + +Links +----- + +[1] https://github.com/riscv/riscv-sbi-doc + RISC-V Supervisor Binary Interface Specification diff --git a/roms/u-boot/doc/board/st/index.rst b/roms/u-boot/doc/board/st/index.rst new file mode 100644 index 000000000..91f1d51b4 --- /dev/null +++ b/roms/u-boot/doc/board/st/index.rst @@ -0,0 +1,9 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +STMicroelectronics +================== + +.. toctree:: + :maxdepth: 2 + + stm32mp1 diff --git a/roms/u-boot/doc/board/st/stm32mp1.rst b/roms/u-boot/doc/board/st/stm32mp1.rst new file mode 100644 index 000000000..f0c2b09b9 --- /dev/null +++ b/roms/u-boot/doc/board/st/stm32mp1.rst @@ -0,0 +1,614 @@ +.. SPDX-License-Identifier: GPL-2.0+ OR BSD-3-Clause +.. sectionauthor:: Patrick Delaunay <patrick.delaunay@foss.st.com> + +STM32MP15x boards +================= + +This is a quick instruction for setup STM32MP15x boards. + +Supported devices +----------------- + +U-Boot supports STMP32MP15x SoCs: + + - STM32MP157 + - STM32MP153 + - STM32MP151 + +The STM32MP15x is a Cortex-A MPU aimed at various applications. + +It features: + + - Dual core Cortex-A7 application core (Single on STM32MP151) + - 2D/3D image composition with GPU (only on STM32MP157) + - Standard memories interface support + - Standard connectivity, widely inherited from the STM32 MCU family + - Comprehensive security support + +Each line comes with a security option (cryptography & secure boot) and +a Cortex-A frequency option: + + - A : Cortex-A7 @ 650 MHz + - C : Secure Boot + HW Crypto + Cortex-A7 @ 650 MHz + - D : Cortex-A7 @ 800 MHz + - F : Secure Boot + HW Crypto + Cortex-A7 @ 800 MHz + +Everything is supported in Linux but U-Boot is limited to: + + 1. UART + 2. SD card/MMC controller (SDMMC) + 3. NAND controller (FMC) + 4. NOR controller (QSPI) + 5. USB controller (OTG DWC2) + 6. Ethernet controller + +And the necessary drivers + + 1. I2C + 2. STPMIC1 (PMIC and regulator) + 3. Clock, Reset, Sysreset + 4. Fuse + +Currently the following boards are supported: + + + stm32mp157a-dk1.dts + + stm32mp157c-dk2.dts + + stm32mp157c-ed1.dts + + stm32mp157c-ev1.dts + + stm32mp15xx-dhcor-avenger96.dts + +Boot Sequences +-------------- + +3 boot configurations are supported with: + ++----------+------------------------+-------------------------+--------------+ +| **ROM** | **FSBL** | **SSBL** | **OS** | ++ **code** +------------------------+-------------------------+--------------+ +| | First Stage Bootloader | Second Stage Bootloader | Linux Kernel | ++ +------------------------+-------------------------+--------------+ +| | embedded RAM | DDR | ++----------+------------------------+-------------------------+--------------+ + +The **Trusted** boot chain +`````````````````````````` + +defconfig_file : stm32mp15_trusted_defconfig + + +-------------+-------------------------+------------+-------+ + | ROM code | FSBL | SSBL | OS | + + +-------------------------+------------+-------+ + | |Trusted Firmware-A (TF-A)| U-Boot | Linux | + +-------------+-------------------------+------------+-------+ + | TrustZone |secure monitor | + +-------------+-------------------------+------------+-------+ + +TF-A performs a full initialization of Secure peripherals and installs a +secure monitor, BL32: + + * SPMin provided by TF-A or + * OP-TEE from specific partitions (teeh, teed, teex). + +U-Boot is running in normal world and uses the secure monitor to access +to secure resources. + +The **Basic** boot chain +```````````````````````` + +defconfig_file : stm32mp15_basic_defconfig + + +-------------+------------+------------+-------+ + | ROM code | FSBL | SSBL | OS | + + +------------+------------+-------+ + | |U-Boot SPL | U-Boot | Linux | + +-------------+------------+------------+-------+ + | TrustZone | | PSCI from U-Boot | + +-------------+------------+------------+-------+ + +SPL has limited security initialization + +U-Boot is running in secure mode and provide a secure monitor to the kernel +with only PSCI support (Power State Coordination Interface defined by ARM). + +All the STM32MP15x boards supported by U-Boot use the same generic board +stm32mp1 which support all the bootable devices. + +Each board is configured only with the associated device tree. + +Device Tree Selection +--------------------- + +You need to select the appropriate device tree for your board, +the supported device trees for STM32MP15x are: + ++ ev1: eval board with pmic stpmic1 (ev1 = mother board + daughter ed1) + + + stm32mp157c-ev1 + ++ ed1: daughter board with pmic stpmic1 + + + stm32mp157c-ed1 + ++ dk1: Discovery board + + + stm32mp157a-dk1 + ++ dk2: Discovery board = dk1 with a BT/WiFI combo and a DSI panel + + + stm32mp157c-dk2 + ++ avenger96: Avenger96 board from Arrow Electronics based on DH Elec. DHCOR SoM + + + stm32mp15xx-dhcor-avenger96 + +Build Procedure +--------------- + +1. Install the required tools for U-Boot + + * install package needed in U-Boot makefile + (libssl-dev, swig, libpython-dev...) + + * install ARMv7 toolchain for 32bit Cortex-A (from Linaro, + from SDK for STM32MP15x, or any crosstoolchains from your distribution) + (you can use any gcc cross compiler compatible with U-Boot) + +2. Set the cross compiler:: + + # export CROSS_COMPILE=/path/to/toolchain/arm-linux-gnueabi- + +3. Select the output directory (optional):: + + # export KBUILD_OUTPUT=/path/to/output + + for example: use one output directory for each configuration:: + + # export KBUILD_OUTPUT=stm32mp15_trusted + # export KBUILD_OUTPUT=stm32mp15_basic + + you can build outside of code directory:: + + # export KBUILD_OUTPUT=../build/stm32mp15_trusted + +4. Configure U-Boot:: + + # make <defconfig_file> + + with <defconfig_file>: + + - For **trusted** boot mode : **stm32mp15_trusted_defconfig** + - For basic boot mode: stm32mp15_basic_defconfig + +5. Configure the device-tree and build the U-Boot image:: + + # make DEVICE_TREE=<name> all + + Examples: + + a) trusted boot on ev1:: + + # export KBUILD_OUTPUT=stm32mp15_trusted + # make stm32mp15_trusted_defconfig + # make DEVICE_TREE=stm32mp157c-ev1 all + + b) trusted with OP-TEE boot on dk2:: + + # export KBUILD_OUTPUT=stm32mp15_trusted + # make stm32mp15_trusted_defconfig + # make DEVICE_TREE=stm32mp157c-dk2 all + + c) basic boot on ev1:: + + # export KBUILD_OUTPUT=stm32mp15_basic + # make stm32mp15_basic_defconfig + # make DEVICE_TREE=stm32mp157c-ev1 all + + d) basic boot on ed1:: + + # export KBUILD_OUTPUT=stm32mp15_basic + # make stm32mp15_basic_defconfig + # make DEVICE_TREE=stm32mp157c-ed1 all + + e) basic boot on dk1:: + + # export KBUILD_OUTPUT=stm32mp15_basic + # make stm32mp15_basic_defconfig + # make DEVICE_TREE=stm32mp157a-dk1 all + + f) basic boot on avenger96:: + + # export KBUILD_OUTPUT=stm32mp15_basic + # make stm32mp15_basic_defconfig + # make DEVICE_TREE=stm32mp15xx-dhcor-avenger96 all + +6. Output files + + BootRom and TF-A expect binaries with STM32 image header + SPL expects file with U-Boot uImage header + + So in the output directory (selected by KBUILD_OUTPUT), + you can found the needed files: + + - For **Trusted** boot (with or without OP-TEE) + + - FSBL = **tf-a.stm32** (provided by TF-A compilation) + - SSBL = **u-boot.stm32** + + - For Basic boot + + - FSBL = spl/u-boot-spl.stm32 + - SSBL = u-boot.img (without CONFIG_SPL_LOAD_FIT) or + u-boot.itb (with CONFIG_SPL_LOAD_FIT=y) + +Switch Setting for Boot Mode +---------------------------- + +You can select the boot mode, on the board with one switch, to select +the boot pin values = BOOT0, BOOT1, BOOT2 + + +-------------+---------+---------+---------+ + |*Boot Mode* | *BOOT2* | *BOOT1* | *BOOT0* | + +=============+=========+=========+=========+ + | Recovery | 0 | 0 | 0 | + +-------------+---------+---------+---------+ + | NOR | 0 | 0 | 1 | + +-------------+---------+---------+---------+ + | eMMC | 0 | 1 | 0 | + +-------------+---------+---------+---------+ + | NAND | 0 | 1 | 1 | + +-------------+---------+---------+---------+ + | Reserved | 1 | 0 | 0 | + +-------------+---------+---------+---------+ + | SD-Card | 1 | 0 | 1 | + +-------------+---------+---------+---------+ + | Recovery | 1 | 1 | 0 | + +-------------+---------+---------+---------+ + | SPI-NAND | 1 | 1 | 1 | + +-------------+---------+---------+---------+ + +- on the **daugther board ed1 = MB1263** with the switch SW1 +- on **Avenger96** with switch S3 (NOR and SPI-NAND are not applicable) +- on board **DK1/DK2** with the switch SW1 = BOOT0, BOOT2 + with only 2 pins available (BOOT1 is forced to 0 and NOR not supported), + the possible value becomes: + + +-------------+---------+---------+ + |*Boot Mode* | *BOOT2* | *BOOT0* | + +=============+=========+=========+ + | Recovery | 0 | 0 | + +-------------+---------+---------+ + | NOR (NA)| 0 | 1 | + +-------------+---------+---------+ + | Reserved | 1 | 0 | + +-------------+---------+---------+ + | SD-Card | 1 | 1 | + +-------------+---------+---------+ + +Recovery is a boot from serial link (UART/USB) and it is used with +STM32CubeProgrammer tool to load executable in RAM and to update the flash +devices available on the board (NOR/NAND/eMMC/SD card). + +The communication between HOST and board is based on + + - for UARTs : the uart protocol used with all MCU STM32 + - for USB : based on USB DFU 1.1 (without the ST extensions used on MCU STM32) + +Prepare an SD card +------------------ + +The minimal requirements for STMP32MP15x boot up to U-Boot are: + +- GPT partitioning (with gdisk or with sgdisk) +- 2 fsbl partitions, named fsbl1 and fsbl2, size at least 256KiB +- one ssbl partition for U-Boot + +Then the minimal GPT partition is: + + +-------+--------+---------+-------------+ + | *Num* | *Name* | *Size* | *Content* | + +=======+========+=========+=============+ + | 1 | fsbl1 | 256 KiB | TF-A or SPL | + +-------+--------+---------+-------------+ + | 2 | fsbl2 | 256 KiB | TF-A or SPL | + +-------+--------+---------+-------------+ + | 3 | ssbl | enought | U-Boot | + +-------+--------+---------+-------------+ + | 4 | <any> | <any> | Rootfs | + +-------+--------+---------+-------------+ + +Add a 4th partition (Rootfs) marked bootable with a file extlinux.conf +following the Generic Distribution feature (doc/README.distro for use). + +According the used card reader select the correct block device +(for example /dev/sdx or /dev/mmcblk0). + +In the next example, it is /dev/mmcblk0 + +For example: with gpt table with 128 entries + +a) remove previous formatting:: + + # sgdisk -o /dev/<SD card dev> + +b) create minimal image:: + + # sgdisk --resize-table=128 -a 1 \ + -n 1:34:545 -c 1:fsbl1 \ + -n 2:546:1057 -c 2:fsbl2 \ + -n 3:1058:5153 -c 3:ssbl \ + -n 4:5154: -c 4:rootfs \ + -p /dev/<SD card dev> + + With other partition for kernel one partition rootfs for kernel. + +c) copy the FSBL (2 times) and SSBL file on the correct partition. + in this example in partition 1 to 3 + + for basic boot mode : <SD card dev> = /dev/mmcblk0:: + + # dd if=u-boot-spl.stm32 of=/dev/mmcblk0p1 + # dd if=u-boot-spl.stm32 of=/dev/mmcblk0p2 + # dd if=u-boot.img of=/dev/mmcblk0p3 # Without CONFIG_SPL_LOAD_FIT + OR + dd if=u-boot.itb of=/dev/mmcblk0p3 # With CONFIG_SPL_LOAD_FIT=y + + for trusted boot mode: :: + + # dd if=tf-a.stm32 of=/dev/mmcblk0p1 + # dd if=tf-a.stm32 of=/dev/mmcblk0p2 + # dd if=u-boot.stm32 of=/dev/mmcblk0p3 + +To boot from SD card, select BootPinMode = 1 0 1 and reset. + +Prepare eMMC +------------ + +You can use U-Boot to copy binary in eMMC. + +In the next example, you need to boot from SD card and the images +(u-boot-spl.stm32, u-boot.img for systems without CONFIG_SPL_LOAD_FIT +or u-boot.itb for systems with CONFIG_SPL_LOAD_FIT=y) are presents on +SD card (mmc 0) in ext4 partition 4 (bootfs). + +To boot from SD card, select BootPinMode = 1 0 1 and reset. + +Then you update the eMMC with the next U-Boot command : + +a) prepare GPT on eMMC, + example with 2 partitions, bootfs and roots:: + + # setenv emmc_part "name=ssbl,size=2MiB;name=bootfs,type=linux,bootable,size=64MiB;name=rootfs,type=linux,size=512" + # gpt write mmc 1 ${emmc_part} + +b) copy SPL on eMMC on firts boot partition + (SPL max size is 256kB, with LBA 512, 0x200):: + + # ext4load mmc 0:4 0xC0000000 u-boot-spl.stm32 + # mmc dev 1 + # mmc partconf 1 1 1 1 + # mmc write ${fileaddr} 0 200 + # mmc partconf 1 1 1 0 + +c) copy U-Boot in first GPT partition of eMMC:: + + # ext4load mmc 0:4 0xC0000000 u-boot.img # Without CONFIG_SPL_LOAD_FIT + OR + ext4load mmc 0:4 0xC0000000 u-boot.itb # With CONFIG_SPL_LOAD_FIT=y + # mmc dev 1 + # part start mmc 1 1 partstart + # mmc write ${fileaddr} ${partstart} ${filesize} + +To boot from eMMC, select BootPinMode = 0 1 0 and reset. + +MAC Address +----------- + +Please read doc/README.enetaddr for the implementation guidelines for mac id +usage. Basically, environment has precedence over board specific storage. + +For STMicroelectonics board, it is retrieved in STM32MP15x OTP : + + - OTP_57[31:0] = MAC_ADDR[31:0] + - OTP_58[15:0] = MAC_ADDR[47:32] + +To program a MAC address on virgin OTP words above, you can use the fuse command +on bank 0 to access to internal OTP and lock them: + +Prerequisite: check if a MAC address isn't yet programmed in OTP + +1) check OTP: their value must be equal to 0:: + + STM32MP> fuse sense 0 57 2 + Sensing bank 0: + Word 0x00000039: 00000000 00000000 + +2) check environment variable:: + + STM32MP> env print ethaddr + ## Error: "ethaddr" not defined + +3) check lock status of fuse 57 & 58 (at 0x39, 0=unlocked, 1=locked):: + + STM32MP> fuse sense 0 0x10000039 2 + Sensing bank 0: + Word 0x10000039: 00000000 00000000 + +Example to set mac address "12:34:56:78:9a:bc" + +1) Write OTP:: + + STM32MP> fuse prog -y 0 57 0x78563412 0x0000bc9a + +2) Read OTP:: + + STM32MP> fuse sense 0 57 2 + Sensing bank 0: + Word 0x00000039: 78563412 0000bc9a + +3) Lock OTP:: + + STM32MP> fuse prog 0 0x10000039 1 1 + + STM32MP> fuse sense 0 0x10000039 2 + Sensing bank 0: + Word 0x10000039: 00000001 00000001 + +4) next REBOOT, in the trace:: + + ### Setting environment from OTP MAC address = "12:34:56:78:9a:bc" + +5) check env update:: + + STM32MP> env print ethaddr + ethaddr=12:34:56:78:9a:bc + +.. warning:: This command can't be executed twice on the same board as + OTP are protected. It is already done for the board + provided by STMicroelectronics. + +Coprocessor firmware +-------------------- + +U-Boot can boot the coprocessor before the kernel (coprocessor early boot). + +a) Manuallly by using rproc commands (update the bootcmd) + + Configurations:: + + # env set name_copro "rproc-m4-fw.elf" + # env set dev_copro 0 + # env set loadaddr_copro 0xC1000000 + + Load binary from bootfs partition (number 4) on SD card (mmc 0):: + + # ext4load mmc 0:4 ${loadaddr_copro} ${name_copro} + + => ${filesize} variable is updated with the size of the loaded file. + + Start M4 firmware with remote proc command:: + + # rproc init + # rproc load ${dev_copro} ${loadaddr_copro} ${filesize} + # rproc start ${dev_copro}"00270033 + +b) Automatically by using FIT feature and generic DISTRO bootcmd + + see examples in the board stm32mp1 directory: fit_copro_kernel_dtb.its + + Generate FIT including kernel + device tree + M4 firmware with cfg with M4 boot:: + + $> mkimage -f fit_copro_kernel_dtb.its fit_copro_kernel_dtb.itb + + Then using DISTRO configuration file: see extlinux.conf to select the correct + configuration: + + - stm32mp157c-ev1-m4 + - stm32mp157c-dk2-m4 + +DFU support +----------- + +The DFU is supported on ST board. + +The env variable dfu_alt_info is automatically build, and all +the memory present on the ST boards are exported. + +The dfu mode is started by the command:: + + STM32MP> dfu 0 + +On EV1 board, booting from SD card, without OP-TEE:: + + STM32MP> dfu 0 list + DFU alt settings list: + dev: RAM alt: 0 name: uImage layout: RAM_ADDR + dev: RAM alt: 1 name: devicetree.dtb layout: RAM_ADDR + dev: RAM alt: 2 name: uramdisk.image.gz layout: RAM_ADDR + dev: eMMC alt: 3 name: mmc0_fsbl1 layout: RAW_ADDR + dev: eMMC alt: 4 name: mmc0_fsbl2 layout: RAW_ADDR + dev: eMMC alt: 5 name: mmc0_ssbl layout: RAW_ADDR + dev: eMMC alt: 6 name: mmc0_bootfs layout: RAW_ADDR + dev: eMMC alt: 7 name: mmc0_vendorfs layout: RAW_ADDR + dev: eMMC alt: 8 name: mmc0_rootfs layout: RAW_ADDR + dev: eMMC alt: 9 name: mmc0_userfs layout: RAW_ADDR + dev: eMMC alt: 10 name: mmc1_boot1 layout: RAW_ADDR + dev: eMMC alt: 11 name: mmc1_boot2 layout: RAW_ADDR + dev: eMMC alt: 12 name: mmc1_ssbl layout: RAW_ADDR + dev: eMMC alt: 13 name: mmc1_bootfs layout: RAW_ADDR + dev: eMMC alt: 14 name: mmc1_vendorfs layout: RAW_ADDR + dev: eMMC alt: 15 name: mmc1_rootfs layout: RAW_ADDR + dev: eMMC alt: 16 name: mmc1_userfs layout: RAW_ADDR + dev: MTD alt: 17 name: nor0 layout: RAW_ADDR + dev: MTD alt: 18 name: nand0 layout: RAW_ADDR + dev: VIRT alt: 19 name: OTP layout: RAW_ADDR + dev: VIRT alt: 20 name: PMIC layout: RAW_ADDR + +All the supported device are exported for dfu-util tool:: + + $> dfu-util -l + Found DFU: [0483:df11] ver=9999, devnum=99, cfg=1, intf=0, alt=20, name="PMIC", serial="002700333338511934383330" + Found DFU: [0483:df11] ver=9999, devnum=99, cfg=1, intf=0, alt=19, name="OTP", serial="002700333338511934383330" + Found DFU: [0483:df11] ver=9999, devnum=99, cfg=1, intf=0, alt=18, name="nand0", serial="002700333338511934383330" + Found DFU: [0483:df11] ver=9999, devnum=99, cfg=1, intf=0, alt=17, name="nor0", serial="002700333338511934383330" + Found DFU: [0483:df11] ver=9999, devnum=99, cfg=1, intf=0, alt=16, name="mmc1_userfs", serial="002700333338511934383330" + Found DFU: [0483:df11] ver=9999, devnum=99, cfg=1, intf=0, alt=15, name="mmc1_rootfs", serial="002700333338511934383330" + Found DFU: [0483:df11] ver=9999, devnum=99, cfg=1, intf=0, alt=14, name="mmc1_vendorfs", serial="002700333338511934383330" + Found DFU: [0483:df11] ver=9999, devnum=99, cfg=1, intf=0, alt=13, name="mmc1_bootfs", serial="002700333338511934383330" + Found DFU: [0483:df11] ver=9999, devnum=99, cfg=1, intf=0, alt=12, name="mmc1_ssbl", serial="002700333338511934383330" + Found DFU: [0483:df11] ver=9999, devnum=99, cfg=1, intf=0, alt=11, name="mmc1_boot2", serial="002700333338511934383330" + Found DFU: [0483:df11] ver=9999, devnum=99, cfg=1, intf=0, alt=10, name="mmc1_boot1", serial="002700333338511934383330" + Found DFU: [0483:df11] ver=9999, devnum=99, cfg=1, intf=0, alt=9, name="mmc0_userfs", serial="002700333338511934383330" + Found DFU: [0483:df11] ver=9999, devnum=99, cfg=1, intf=0, alt=8, name="mmc0_rootfs", serial="002700333338511934383330" + Found DFU: [0483:df11] ver=9999, devnum=99, cfg=1, intf=0, alt=7, name="mmc0_vendorfs", serial="002700333338511934383330" + Found DFU: [0483:df11] ver=9999, devnum=99, cfg=1, intf=0, alt=6, name="mmc0_bootfs", serial="002700333338511934383330" + Found DFU: [0483:df11] ver=9999, devnum=99, cfg=1, intf=0, alt=5, name="mmc0_ssbl", serial="002700333338511934383330" + Found DFU: [0483:df11] ver=9999, devnum=99, cfg=1, intf=0, alt=4, name="mmc0_fsbl2", serial="002700333338511934383330" + Found DFU: [0483:df11] ver=9999, devnum=99, cfg=1, intf=0, alt=3, name="mmc0_fsbl1", serial="002700333338511934383330" + Found DFU: [0483:df11] ver=9999, devnum=99, cfg=1, intf=0, alt=2, name="uramdisk.image.gz", serial="002700333338511934383330" + Found DFU: [0483:df11] ver=9999, devnum=99, cfg=1, intf=0, alt=1, name="devicetree.dtb", serial="002700333338511934383330" + Found DFU: [0483:df11] ver=9999, devnum=99, cfg=1, intf=0, alt=0, name="uImage", serial="002700333338511934383330" + +You can update the boot device: + +- SD card (mmc0) :: + + $> dfu-util -d 0483:5720 -a 3 -D tf-a-stm32mp157c-ev1-trusted.stm32 + $> dfu-util -d 0483:5720 -a 4 -D tf-a-stm32mp157c-ev1-trusted.stm32 + $> dfu-util -d 0483:5720 -a 5 -D u-boot-stm32mp157c-ev1-trusted.img + $> dfu-util -d 0483:5720 -a 6 -D st-image-bootfs-openstlinux-weston-stm32mp1.ext4 + $> dfu-util -d 0483:5720 -a 7 -D st-image-vendorfs-openstlinux-weston-stm32mp1.ext4 + $> dfu-util -d 0483:5720 -a 8 -D st-image-weston-openstlinux-weston-stm32mp1.ext4 + $> dfu-util -d 0483:5720 -a 9 -D st-image-userfs-openstlinux-weston-stm32mp1.ext4 + +- EMMC (mmc1):: + + $> dfu-util -d 0483:5720 -a 10 -D tf-a-stm32mp157c-ev1-trusted.stm32 + $> dfu-util -d 0483:5720 -a 11 -D tf-a-stm32mp157c-ev1-trusted.stm32 + $> dfu-util -d 0483:5720 -a 12 -D u-boot-stm32mp157c-ev1-trusted.img + $> dfu-util -d 0483:5720 -a 13 -D st-image-bootfs-openstlinux-weston-stm32mp1.ext4 + $> dfu-util -d 0483:5720 -a 14 -D st-image-vendorfs-openstlinux-weston-stm32mp1.ext4 + $> dfu-util -d 0483:5720 -a 15 -D st-image-weston-openstlinux-weston-stm32mp1.ext4 + $> dfu-util -d 0483:5720 -a 16 -D st-image-userfs-openstlinux-weston-stm32mp1.ext4 + +- you can also dump the OTP and the PMIC NVM with:: + + $> dfu-util -d 0483:5720 -a 19 -U otp.bin + $> dfu-util -d 0483:5720 -a 20 -U pmic.bin + + +When the board is booting for nor0 or nand0, +only the MTD partition on the boot devices are available, for example: + +- NOR (nor0 = alt 20) & NAND (nand0 = alt 26) :: + + $> dfu-util -d 0483:5720 -a 21 -D tf-a-stm32mp157c-ev1-trusted.stm32 + $> dfu-util -d 0483:5720 -a 22 -D tf-a-stm32mp157c-ev1-trusted.stm32 + $> dfu-util -d 0483:5720 -a 23 -D u-boot-stm32mp157c-ev1-trusted.img + $> dfu-util -d 0483:5720 -a 27 -D st-image-weston-openstlinux-weston-stm32mp1_nand_4_256_multivolume.ubi + +- NAND (nand0 = alt 21):: + + $> dfu-util -d 0483:5720 -a 22 -D tf-a-stm32mp157c-ev1-trusted.stm32 + $> dfu-util -d 0483:5720 -a 23 -D u-boot-stm32mp157c-ev1-trusted.img + $> dfu-util -d 0483:5720 -a 24 -D u-boot-stm32mp157c-ev1-trusted.img + $> dfu-util -d 0483:5720 -a 25 -D st-image-weston-openstlinux-weston-stm32mp1_nand_4_256_multivolume.ubi diff --git a/roms/u-boot/doc/board/tbs/index.rst b/roms/u-boot/doc/board/tbs/index.rst new file mode 100644 index 000000000..b677bc624 --- /dev/null +++ b/roms/u-boot/doc/board/tbs/index.rst @@ -0,0 +1,9 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +TBS +=== + +.. toctree:: + :maxdepth: 2 + + tbs2910 diff --git a/roms/u-boot/doc/board/tbs/tbs2910.rst b/roms/u-boot/doc/board/tbs/tbs2910.rst new file mode 100644 index 000000000..e97f2b6e6 --- /dev/null +++ b/roms/u-boot/doc/board/tbs/tbs2910.rst @@ -0,0 +1,191 @@ +TBS2910 Matrix ARM miniPC +========================= + +Building +-------- +To build u-boot for the TBS2910 Matrix ARM miniPC, you can use the following +procedure: + +First add the ARM toolchain to your PATH + +Then setup the ARCH and cross compilation environment variables. + +When this is done you can then build u-boot for the TBS2910 Matrix ARM miniPC +with the following commands: + +.. code-block:: none + + make mrproper + make tbs2910_defconfig + make + +Once the build is complete, you can find the resulting image as u-boot.imx in +the current directory. + +UART +---- +The UART voltage is at 3.3V and its settings are 115200bps 8N1 + +BOOT/UPDATE boot switch: +------------------------ +The BOOT/UPDATE switch (SW11) is connected to the BOOT_MODE0 and +BOOT_MODE1 SoC pins. It has "BOOT" and "UPDATE" markings both on +the PCB and on the plastic case. + +When set to the "UPDATE" position, the SoC will use the "Boot From Fuses" +configuration, and since BT_FUSE_SEL is 0, this makes the SOC jump to serial +downloader. + +When set in the "BOOT" position, the SoC will use the "Internal boot" +configuration, and since BT_FUSE_SEL is 0, it will then use the GPIO pins +for the boot configuration. + +SW6 binary DIP switch array on the PCB revision 2.1: +---------------------------------------------------- +On that PCB revision, SW6 has 8 positions. + +Switching a position to ON sets the corresponding +register to 1. + +See the following table for a correspondence between the switch positions and +registers: + +=============== ============ +Switch position Register +=============== ============ +1 BOOT_CFG2[3] +2 BOOT_CFG2[4] +3 BOOT_CFG2[5] +4 BOOT_CFG2[6] +5 BOOT_CFG1[4] +6 BOOT_CFG1[5] +7 BOOT_CFG1[6] +8 BOOT_CFG1[7] +=============== ============ + +For example: + + - To boot from the eMMC: 1:ON , 2:ON, 3:ON, 4:OFF, 5:OFF, 6:ON, 7:ON, 8:OFF + - To boot from the microSD slot: 1: ON, 2: OFF, 3: OFF, 4: OFF, 5:OFF, 6:OFF, + 7:ON, 8:OFF + - To boot from the SD slot: 1: OFF, 2: ON, 3: OFF, 4: OFF, 5:OFF, 6:OFF, 7:ON, + 8:OFF + - To boot from SATA: 1: OFF, 2: OFF, 3: OFF, 4: OFF, 5:OFF, 6:ON, 7:OFF, 8:OFF + +You can refer to the BOOT_CFG registers in the I.MX6Q reference manual for +additional details. + +SW6 binary DIP switch array on the PCB revision 2.3: +---------------------------------------------------- +On that PCB revision, SW6 has only 4 positions. + +Switching a position to ON sets the corresponding +register to 1. + +See the following table for a correspondence between the switch positions and +registers: + +=============== ============ +Switch position Register +=============== ============ +1 BOOT_CFG2[3] +2 BOOT_CFG2[4] +3 BOOT_CFG2[5] +4 BOOT_CFG1[5] +=============== ============ + +For example: + +- To boot from the eMMC: 1:ON, 2:ON, 3:ON, 4:ON +- To boot from the microSD slot: 1:ON, 2:OFF, 3:OFF, 4:OFF +- To boot from the SD slot: 1:OFF, 2:ON, 3:OFF, 4:OFF + +You can refer to the BOOT_CFG registers in the I.MX6Q reference manual for +additional details. + +Loading u-boot from USB: +------------------------ +If you need to load u-boot from USB, you can use the following instructions: + +First build imx_usb_loader, as we will need it to load u-boot from USB. This +can be done with the following commands: + +.. code-block:: none + + git clone git://github.com/boundarydevices/imx_usb_loader.git + cd imx_usb_loader + make + +This will create the resulting imx_usb binary. + +When this is done, you can copy the u-boot.imx image that you built earlier +in in the imx_usb_loader directory. + +You will then need to power off the TBS2910 Matrix ARM miniPC and make sure that +the boot switch is set to "UPDATE" + +Once this is done you can connect an USB cable between the computer that will +run imx_usb and the TBS2910 Matrix ARM miniPC. + +If you also need to access the u-boot console, you will also need to connect an +UART cable between the computer running imx_usb and the TBS2910 Matrix ARM +miniPC. + +Once everything is connected you can finally power on the TBS2910 Matrix ARM +miniPC. The SoC will then jump to the serial download and wait for you. + +Finlay, you can load u-boot through USB with with the following command: + +.. code-block:: none + + sudo ./imx_usb -v u-boot.imx + +The u-boot boot messages will then appear in the serial console. + +Install u-boot on the eMMC: +--------------------------- +To install u-boot on the eMMC, you first need to boot the TBS2910 Matrix ARM +miniPC. + +Once booted, you can flash u-boot.imx to mmcblk0boot0 with the +following commands: + +.. code-block:: none + + sudo echo 0 >/sys/block/mmcblk0boot0/force_ro + sudo dd if=u-boot.imx of=/dev/mmcblk0boot0 bs=1k seek=1; sync + +Note that the eMMC card node may vary, so adjust this as needed. + +Once the new u-boot version is installed, to boot on it you then need to power +off the TBS2910 Matrix ARM miniPC. + +Once it is off, you need make sure that the boot switch is set to "BOOT" and +that the SW6 switch is set to boot on the eMMC as described in the previous +sections. + +If you also need to access the u-boot console, you will also need to connect an +UART cable between the computer running imx_usb and the TBS2910 Matrix ARM +miniPC. + +You can then power up the TBS2910 Matrix ARM miniPC and U-Boot messages will +appear in the serial console. + +Booting a distribution: +----------------------- +When booting on the TBS2910 Matrix ARM miniPC, by default U-Boot will first try +to boot from hardcoded offsets from the start of the eMMC. This is for +compatibility with the stock GNU/Linux distribution. + +If that fails it will then try to boot from several interfaces using +'distro_bootcmd': It will first try to boot from the microSD slot, then the +SD slot, then the internal eMMC, then the SATA interface and finally the USB +interface. For more information on how to configure your distribution to boot, +see 'README.distro'. + +Links: +------ + - https://www.tbsdtv.com/download/document/tbs2910/TBS2910-Matrix-ARM-mini-PC-SCH_rev2.1.pdf + - The schematics for the revision 2.1 of the TBS2910 Matrix ARM miniPC. + - https://cache.freescale.com/files/32bit/doc/ref_manual/IMX6DQRM.pdf - The + SoC reference manual for additional details on the BOOT_CFG registers. diff --git a/roms/u-boot/doc/board/toradex/apalix-imx8.rst b/roms/u-boot/doc/board/toradex/apalix-imx8.rst new file mode 100644 index 000000000..29593faf1 --- /dev/null +++ b/roms/u-boot/doc/board/toradex/apalix-imx8.rst @@ -0,0 +1,82 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +Apalis iMX8QM V1.0B Module +========================== + +Quick Start +----------- + +- Build the ARM trusted firmware binary +- Get scfw_tcm.bin and ahab-container.img +- Build U-Boot +- Load U-Boot binary using uuu +- Flash U-Boot binary into the eMMC +- Boot + +Get and Build the ARM Trusted Firmware +-------------------------------------- + +.. code-block:: bash + + $ git clone -b imx_4.14.78_1.0.0_ga https://source.codeaurora.org/external/imx/imx-atf + $ cd imx-atf/ + $ make PLAT=imx8qm bl31 + +Get scfw_tcm.bin and ahab-container.img +--------------------------------------- + +.. code-block:: bash + + $ wget https://github.com/toradex/meta-fsl-bsp-release/blob/toradex-sumo-4.14.78-1.0.0_ga-bringup/imx/meta-bsp/recipes- + bsp/imx-sc-firmware/files/mx8qm-apalis-scfw-tcm.bin?raw=true + $ mv mx8qm-apalis-scfw-tcm.bin\?raw\=true mx8qm-apalis-scfw-tcm.bin + $ wget https://www.nxp.com/lgfiles/NMG/MAD/YOCTO/firmware-imx-8.0.bin + $ chmod +x firmware-imx-8.0.bin + $ ./firmware-imx-8.0.bin + +Copy the following binaries to the U-Boot folder: + +.. code-block:: bash + + $ cp imx-atf/build/imx8qm/release/bl31.bin . + $ cp u-boot/u-boot.bin . + +Copy the following firmware to the U-Boot folder: + +.. code-block:: bash + + $ cp firmware-imx-8.0/firmware/seco/ahab-container.img . + +Build U-Boot +------------ +.. code-block:: bash + + $ make apalis-imx8_defconfig + $ make u-boot-dtb.imx + +Load the U-Boot Binary Using UUU +-------------------------------- + +Get the latest version of the universal update utility (uuu) aka ``mfgtools 3.0``: + +https://community.nxp.com/external-link.jspa?url=https%3A%2F%2Fgithub.com%2FNXPmicro%2Fmfgtools%2Freleases + +Put the module into USB recovery aka serial downloader mode, connect USB device +to your host and execute uuu: + +.. code-block:: bash + + sudo ./uuu u-boot/u-boot-dtb.imx + +Flash the U-Boot Binary into the eMMC +------------------------------------- + +Burn the ``u-boot-dtb.imx`` binary to the primary eMMC hardware boot area +partition and boot: + +.. code-block:: bash + + load mmc 1:1 $loadaddr u-boot-dtb.imx + setexpr blkcnt ${filesize} + 0x1ff && setexpr blkcnt ${blkcnt} / 0x200 + mmc dev 0 1 + mmc write ${loadaddr} 0x0 ${blkcnt} diff --git a/roms/u-boot/doc/board/toradex/apalix-imx8x.rst b/roms/u-boot/doc/board/toradex/apalix-imx8x.rst new file mode 100644 index 000000000..e62578b15 --- /dev/null +++ b/roms/u-boot/doc/board/toradex/apalix-imx8x.rst @@ -0,0 +1,77 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +Apalis iMX8X V1.1A Module (SoC NXP i.MX8QXP RevB) +================================================= + +Quick Start +----------- + +- Get and Build the ARM trusted firmware +- Get System Controller firmware +- Get SECO container +- Build U-Boot +- Load U-Boot binary using uuu +- Flash U-Boot binary into the eMMC +- Boot + +Note: builddir is U-Boot build directory (source directory for in-tree builds) + +Get and Build the ARM Trusted Firmware +-------------------------------------- + +.. code-block:: bash + + $ cd $(builddir) + $ git clone -b toradex_imx_5.4.70_2.3.0 http://git.toradex.com/cgit/imx-atf.git + $ make PLAT=imx8qx bl31 -C imx-atf + $ cp imx-atf/build/imx8qx/release/bl31.bin $(builddir) + +Get System Controller firmware +--------------------------------------- + +.. code-block:: bash + + $ wget https://github.com/toradex/i.MX-System-Controller-Firmware/raw/master/src/scfw_export_mx8qx_b0/build_mx8qx_b0/mx8qx-apalis-scfw-tcm.bin + +Get SECO container +--------------------------------------- + +.. code-block:: bash + + $ wget https://www.nxp.com/lgfiles/NMG/MAD/YOCTO/imx-seco-3.7.4.bin + $ sh imx-seco-3.7.4.bin + $ cp imx-seco-3.7.4/firmware/seco/mx8qxb0-ahab-container.img $(builddir)/mx8qx-ahab-container.img + +Build U-Boot +------------ +.. code-block:: bash + + $ make apalis-imx8x_defconfig + $ make u-boot-dtb.imx + +Load the U-Boot Binary Using UUU +-------------------------------- + +Get the latest version of the universal update utility (uuu) aka ``mfgtools 3.0``: + +https://community.nxp.com/external-link.jspa?url=https%3A%2F%2Fgithub.com%2FNXPmicro%2Fmfgtools%2Freleases + +Put the module into USB recovery aka serial downloader mode, connect USB device +to your host and execute uuu: + +.. code-block:: bash + + sudo ./uuu $(builddir)/u-boot-dtb.imx + +Flash the U-Boot Binary into the eMMC +------------------------------------- + +Burn the ``u-boot-dtb.imx`` binary to the primary eMMC hardware boot area +partition and boot: + +.. code-block:: bash + + load mmc 1:1 $loadaddr u-boot-dtb.imx + setexpr blkcnt ${filesize} + 0x1ff && setexpr blkcnt ${blkcnt} / 0x200 + mmc dev 0 1 + mmc write ${loadaddr} 0x0 ${blkcnt} diff --git a/roms/u-boot/doc/board/toradex/colibri-imx8x.rst b/roms/u-boot/doc/board/toradex/colibri-imx8x.rst new file mode 100644 index 000000000..616f40ae0 --- /dev/null +++ b/roms/u-boot/doc/board/toradex/colibri-imx8x.rst @@ -0,0 +1,82 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +Colibri iMX8QXP V1.0B Module +============================ + +Quick Start +----------- + +- Build the ARM trusted firmware binary +- Get scfw_tcm.bin and ahab-container.img +- Build U-Boot +- Load U-Boot binary using uuu +- Flash U-Boot binary into the eMMC +- Boot + +Get and Build the ARM Trusted Firmware +-------------------------------------- + +.. code-block:: bash + + $ git clone -b imx_4.14.78_1.0.0_ga https://source.codeaurora.org/external/imx/imx-atf + $ cd imx-atf/ + $ make PLAT=imx8qxp bl31 + +Get scfw_tcm.bin and ahab-container.img +--------------------------------------- +.. code-block:: bash + + $ wget https://github.com/toradex/meta-fsl-bsp-release/blob/ + toradex-sumo-4.14.78-1.0.0_ga-bringup/imx/meta-bsp/recipes- + bsp/imx-sc-firmware/files/mx8qx-colibri-scfw-tcm.bin?raw=true + $ mv mx8qx-colibri-scfw-tcm.bin\?raw\=true mx8qx-colibri-scfw-tcm.bin + $ wget https://www.nxp.com/lgfiles/NMG/MAD/YOCTO/firmware-imx-8.0.bin + $ chmod +x firmware-imx-8.0.bin + $ ./firmware-imx-8.0.bin + +Copy the following binaries to the U-Boot folder: + +.. code-block:: bash + + $ cp imx-atf/build/imx8qxp/release/bl31.bin . + $ cp u-boot/u-boot.bin . + +Copy the following firmware to the U-Boot folder: + +.. code-block:: bash + + $ cp firmware-imx-8.0/firmware/seco/ahab-container.img . + +Build U-Boot +------------ + +.. code-block:: bash + + $ make colibri-imx8x_defconfig + $ make u-boot-dtb.imx + +Load the U-Boot Binary Using UUU +-------------------------------- + +Get the latest version of the universal update utility (uuu) aka ``mfgtools 3.0``: + +https://community.nxp.com/external-link.jspa?url=https%3A%2F%2Fgithub.com%2FNXPmicro%2Fmfgtools%2Freleases + +Put the module into USB recovery aka serial downloader mode, connect USB device +to your host and execute ``uuu``: + +.. code-block:: bash + + sudo ./uuu u-boot/u-boot-dtb.imx + +Flash the U-Boot Binary into the eMMC +------------------------------------- + +Burn the ``u-boot-dtb.imx`` binary to the primary eMMC hardware boot area partition: + +.. code-block:: bash + + load mmc 1:1 $loadaddr u-boot-dtb.imx + setexpr blkcnt ${filesize} + 0x1ff && setexpr blkcnt ${blkcnt} / 0x200 + mmc dev 0 1 + mmc write ${loadaddr} 0x0 ${blkcnt} diff --git a/roms/u-boot/doc/board/toradex/colibri_imx7.rst b/roms/u-boot/doc/board/toradex/colibri_imx7.rst new file mode 100644 index 000000000..a30e72137 --- /dev/null +++ b/roms/u-boot/doc/board/toradex/colibri_imx7.rst @@ -0,0 +1,126 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +Colibri iMX7 +============ + +Quick Start +----------- + +- Build U-Boot +- NAND IMX image adjustments before flashing +- Flashing manually U-Boot to eMMC +- Flashing manually U-Boot to NAND +- Using ``update_uboot`` script + +Build U-Boot +------------ + +.. code-block:: bash + + $ export CROSS_COMPILE=arm-linux-gnueabi- + $ make colibri_imx7_emmc_defconfig # For NAND: colibri_imx7_defconfig + $ make + +After build succeeds, you will obtain final ``u-boot-dtb.imx`` IMX specific +image, ready for flashing (but check next section for additional +adjustments). + +Final IMX program image includes (section ``6.6.7`` from `IMX7DRM +<https://www.nxp.com/webapp/Download?colCode=IMX7DRM>`_): + +* **Image vector table** (IVT) for BootROM +* **Boot data** -indicates the program image location, program image size + in bytes, and the plugin flag. +* **Device configuration data** +* **User image**: U-Boot image (``u-boot-dtb.bin``) + + +IMX image adjustments prior to flashing +--------------------------------------- + +1. U-Boot for both Colibri iMX7 NAND and eMMC versions +is built with HABv4 support (`AN4581.pdf +<https://www.nxp.com/docs/en/application-note/AN4581.pdf>`_) +enabled by default, which requires to generate a proper +Command Sequence File (CSF) by srktool from NXP (not included in the +U-Boot tree, check additional details in introduction_habv4.txt) +and concatenate it to the final ``u-boot-dtb.imx``. + +2. In case if you don't want to generate a proper ``CSF`` (for any reason), +you still need to pad the IMX image so i has the same size as specified in +in **Boot Data** section of IMX image. +To obtain this value, run: + +.. code-block:: bash + + $ od -X -N 0x30 u-boot-dtb.imx + 0000000 402000d1 87800000 00000000 877ff42c + 0000020 877ff420 877ff400 878a5000 00000000 + ^^^^^^^^ + 0000040 877ff000 000a8060 00000000 40b401d2 + ^^^^^^^^ ^^^^^^^^ + +Where: + +* ``877ff400`` - IVT self address +* ``877ff000`` - Program image address +* ``000a8060`` - Program image size + +To calculate the padding: + +* IVT offset = ``0x877ff400`` - ``0x877ff000`` = ``0x400`` +* Program image size = ``0xa8060`` - ``0x400`` = ``0xa7c60`` + +and then pad the image: + +.. code-block:: bash + + $ objcopy -I binary -O binary --pad-to 0xa7c60 --gap-fill=0x00 \ + u-boot-dtb.imx u-boot-dtb.imx.zero-padded + +3. Also, according to requirement from ``6.6.7.1``, the final image +should have ``0x400`` offset for initial IVT table. + +For eMMC setup we handle this by flashing it to ``0x400``, howewer +for NAND setup we adjust the image prior to flashing, adding padding in the +beginning of the image. + +.. code-block:: bash + + $ dd if=u-boot-dtb.imx.zero-padded of=u-boot-dtb.imx.ready bs=1024 seek=1 + +Flash U-Boot IMX image to eMMC +------------------------------ + +Flash the ``u-boot-dtb.imx.zero-padded`` binary to the primary eMMC hardware +boot area partition: + +.. code-block:: bash + + + => load mmc 1:1 $loadaddr u-boot-dtb.imx.zero-padded + => setexpr blkcnt ${filesize} + 0x1ff && setexpr blkcnt ${blkcnt} / 0x200 + => mmc dev 0 1 + => mmc write ${loadaddr} 0x2 ${blkcnt} + +Flash U-Boot IMX image to NAND +------------------------------ + +.. code-block:: bash + + => load mmc 1:1 $loadaddr u-boot-dtb.imx.ready + => nand erase.part u-boot1 + => nand write ${loadaddr} u-boot1 ${filesize} + => nand erase.part u-boot2 + => nand write ${loadaddr} u-boot2 ${filesize} + +Using update_uboot script +------------------------- + +You can also usb U-Boot env update_uboot script, +which wraps all eMMC/NAND specific command invocation: + +.. code-block:: bash + + => load mmc 1:1 $loadaddr u-boot-dtb.imx.ready + => run update_uboot diff --git a/roms/u-boot/doc/board/toradex/index.rst b/roms/u-boot/doc/board/toradex/index.rst new file mode 100644 index 000000000..abba648f8 --- /dev/null +++ b/roms/u-boot/doc/board/toradex/index.rst @@ -0,0 +1,13 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +Toradex +======= + +.. toctree:: + :maxdepth: 2 + + apalix-imx8 + apalix-imx8x + colibri_imx7 + colibri-imx8x + verdin-imx8mm diff --git a/roms/u-boot/doc/board/toradex/verdin-imx8mm.rst b/roms/u-boot/doc/board/toradex/verdin-imx8mm.rst new file mode 100644 index 000000000..b9f7dc39c --- /dev/null +++ b/roms/u-boot/doc/board/toradex/verdin-imx8mm.rst @@ -0,0 +1,98 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +Verdin iMX8M Mini Module +======================== + +Quick Start +----------- + +- Build the ARM trusted firmware binary +- Get the DDR firmware +- Build U-Boot +- Flash to eMMC +- Boot + +Get and Build the ARM Trusted Firmware (Trusted Firmware A) +----------------------------------------------------------- + +.. code-block:: bash + + $ echo "Downloading and building TF-A..." + $ git clone https://git.trustedfirmware.org/TF-A/trusted-firmware-a.git + $ cd trusted-firmware-a + +Then build ATF (TF-A): + +.. code-block:: bash + + $ make PLAT=imx8mm IMX_BOOT_UART_BASE=0x30860000 bl31 + $ cp build/imx8mm/release/bl31.bin ../ + +Get the DDR Firmware +-------------------- + +.. code-block:: bash + + $ cd .. + $ wget https://www.nxp.com/lgfiles/NMG/MAD/YOCTO/firmware-imx-8.4.1.bin + $ chmod +x firmware-imx-8.4.1.bin + $ ./firmware-imx-8.4.1.bin + $ cp firmware-imx-8.4.1/firmware/ddr/synopsys/lpddr4*.bin ./ + +Build U-Boot +------------ +.. code-block:: bash + + $ export CROSS_COMPILE=aarch64-linux-gnu- + $ export ATF_LOAD_ADDR=0x920000 + $ make verdin-imx8mm_defconfig + $ make flash.bin + +Flash to eMMC +------------- + +.. code-block:: bash + + > tftpboot ${loadaddr} flash.bin + > setexpr blkcnt ${filesize} + 0x1ff && setexpr blkcnt ${blkcnt} / 0x200 + > mmc dev 0 1 && mmc write ${loadaddr} 0x2 ${blkcnt} + +As a convenience, instead of the last two commands one may also use the update +U-Boot wrapper: + +.. code-block:: bash + + > run update_uboot + +Boot +---- + +ATF, U-Boot proper and u-boot.dtb images are packed into FIT image, +which is loaded and parsed by SPL. + +Boot sequence is: + +* SPL ---> ATF (TF-A) ---> U-Boot proper + +Output: + +.. code-block:: bash + + U-Boot SPL 2020.01-00187-gd411d164e5 (Jan 26 2020 - 04:47:26 +0100) + Normal Boot + Trying to boot from MMC1 + + U-Boot 2020.01-00187-gd411d164e5 (Jan 26 2020 - 04:47:26 +0100) + + CPU: Freescale i.MX8MMQ rev1.0 at 0 MHz + Reset cause: POR + DRAM: 2 GiB + MMC: FSL_SDHC: 0, FSL_SDHC: 1, FSL_SDHC: 2 + Loading Environment from MMC... OK + In: serial + Out: serial + Err: serial + Model: Toradex Verdin iMX8M Mini Quad 2GB Wi-Fi / BT IT V1.0A, Serial: + Net: eth0: ethernet@30be0000 + Hit any key to stop autoboot: 0 + Verdin iMX8MM # diff --git a/roms/u-boot/doc/board/xen/index.rst b/roms/u-boot/doc/board/xen/index.rst new file mode 100644 index 000000000..e58fe9e35 --- /dev/null +++ b/roms/u-boot/doc/board/xen/index.rst @@ -0,0 +1,9 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +XenGuestARM64 +============= + +.. toctree:: + :maxdepth: 2 + + xenguest_arm64 diff --git a/roms/u-boot/doc/board/xen/xenguest_arm64.rst b/roms/u-boot/doc/board/xen/xenguest_arm64.rst new file mode 100644 index 000000000..1327f88f9 --- /dev/null +++ b/roms/u-boot/doc/board/xen/xenguest_arm64.rst @@ -0,0 +1,81 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +Xen guest ARM64 board +===================== + +This board specification +------------------------ + +This board is to be run as a virtual Xen [1] guest with U-boot as its primary +bootloader. Xen is a type 1 hypervisor that allows multiple operating systems +to run simultaneously on a single physical server. Xen is capable of running +virtual machines in both full virtualization and para-virtualization (PV) +modes. Xen runs virtual machines, which are called “domains”. + +Paravirtualized drivers are a special type of device drivers that are used in +a guest system in the Xen domain and perform I/O operations using a special +interface provided by the virtualization system and the host system. + +Xen support for U-boot is implemented by introducing a new Xen guest ARM64 +board and porting essential drivers from MiniOS [3] as well as some of the work +previously done by NXP [4]: + +- PV block device frontend driver with XenStore based device enumeration and + UCLASS_PVBLOCK class; +- PV serial console device frontend driver; +- Xen hypervisor support with minimal set of the essential headers adapted from + the Linux kernel; +- Xen grant table support; +- Xen event channel support in polling mode; +- XenBus support; +- dynamic RAM size as defined in the device tree instead of the statically + defined values; +- position-independent pre-relocation code is used as we cannot statically + define any start addresses at compile time which is up to Xen to choose at + run-time; +- new defconfig introduced: xenguest_arm64_defconfig. + + +Board limitations +----------------- + +1. U-boot runs without MMU enabled at the early stages. + According to Xen on ARM ABI (xen/include/public/arch-arm.h): all memory + which is shared with other entities in the system (including the hypervisor + and other guests) must reside in memory which is mapped as Normal Inner + Write-Back Outer Write-Back Inner-Shareable. + Thus, page attributes must be equally set for all the entities working with + that page. + Before MMU is set up the data cache is turned off and pages are seen by the + vCPU and Xen in different ways - cacheable by Xen and non-cacheable by vCPU. + So it means that manual data cache maintenance is required at the early + stages. + +2. No serial console until MMU is up. + Because data cache maintenance is required until the MMU setup the + early/debug serial console is not implemented. Therefore, we do not have + usual prints like U-boot’s banner etc. until the serial driver is + initialized. + +3. Single RAM bank supported. + If a Xen guest is given much memory it is possible that Xen allocates two + memory banks for it. The first one is allocated under 4GB address space and + in some cases may represent the whole guest’s memory. It is assumed that + U-boot most likely won’t require high memory bank for its work andlaunching + OS, so it is enough to take the first one. + + +Board default configuration +--------------------------- + +One can select the configuration as follows: + + - make xenguest_arm64_defconfig + +[1] - https://xenproject.org/ + +[2] - https://wiki.xenproject.org/wiki/Paravirtualization_(PV) + +[3] - https://wiki.xenproject.org/wiki/Mini-OS + +[4] - https://source.codeaurora.org/external/imx/uboot-imx/tree/?h=imx_v2018.03_4.14.98_2.0.0_ga diff --git a/roms/u-boot/doc/board/xilinx/index.rst b/roms/u-boot/doc/board/xilinx/index.rst new file mode 100644 index 000000000..2e31fe3f3 --- /dev/null +++ b/roms/u-boot/doc/board/xilinx/index.rst @@ -0,0 +1,12 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +Xilinx +====== + +.. toctree:: + :maxdepth: 2 + + xilinx + zynq + zynqmp + zynqmp-r5 diff --git a/roms/u-boot/doc/board/xilinx/xilinx.rst b/roms/u-boot/doc/board/xilinx/xilinx.rst new file mode 100644 index 000000000..8c9afb482 --- /dev/null +++ b/roms/u-boot/doc/board/xilinx/xilinx.rst @@ -0,0 +1,48 @@ +.. SPDX-License-Identifier: GPL-2.0+ +.. (C) Copyright 2019 Xilinx, Inc. + +U-Boot device tree bindings +---------------------------- + +All the device tree bindings used in U-Boot are specified in Linux +kernel. Please refer dt bindings from below specified paths in Linux +kernel. + +* ata + - Documentation/devicetree/bindings/ata/ahci-ceva.txt +* clock + - Documentation/devicetree/bindings/clock/xlnx,zynqmp-clk.txt +* firmware + - Documentation/devicetree/bindings/firmware/xilinx/xlnx,zynqmp-firmware.txt +* fpga + - Documentation/devicetree/bindings/fpga/xlnx,zynqmp-pcap-fpga.txt +* gpio + - Documentation/devicetree/bindings/gpio/gpio-xilinx.txt + - Documentation/devicetree/bindings/gpio/gpio-zynq.txt +* i2c + - Documentation/devicetree/bindings/i2c/xlnx,xps-iic-2.00.a.yaml + - Documentation/devicetree/bindings/i2c/cdns,i2c-r1p10.yaml +* mmc + - Documentation/devicetree/bindings/mmc/arasan,sdhci.yaml +* net + - Documentation/devicetree/bindings/net/macb.txt + - Documentation/devicetree/bindings/net/xilinx_axienet.txt + - Documentation/devicetree/bindings/net/xilinx_emaclite.txt +* nvmem + - Documentation/devicetree/bindings/nvmem/xlnx,zynqmp-nvmem.txt +* power + - Documentation/devicetree/bindings/power/reset/xlnx,zynqmp-power.txt +* serial + - Documentation/devicetree/bindings/serial/cdns,uart.txt + - Documentation/devicetree/bindings/serial/xlnx,opb-uartlite.txt +* spi + - Documentation/devicetree/bindings/spi/spi-cadence.txt + - Documentation/devicetree/bindings/spi/spi-xilinx.txt + - Documentation/devicetree/bindings/spi/spi-zynqmp-qspi.txt + - Documentation/devicetree/bindings/spi/spi-zynq-qspi.txt +* usb + - Documentation/devicetree/bindings/usb/dwc3-xilinx.txt + - Documentation/devicetree/bindings/usb/dwc3.txt + - Documentation/devicetree/bindings/usb/ci-hdrc-usb2.txt +* wdt + - Documentation/devicetree/bindings/watchdog/of-xilinx-wdt.txt diff --git a/roms/u-boot/doc/board/xilinx/zynq.rst b/roms/u-boot/doc/board/xilinx/zynq.rst new file mode 100644 index 000000000..438912fe4 --- /dev/null +++ b/roms/u-boot/doc/board/xilinx/zynq.rst @@ -0,0 +1,110 @@ +.. SPDX-License-Identifier: GPL-2.0+ +.. (C) Copyright 2013 Xilinx, Inc. + +ZYNQ +==== + +About this +---------- + +This document describes the information about Xilinx Zynq U-Boot - +like supported boards, ML status and TODO list. + +Zynq boards +----------- + +Xilinx Zynq-7000 All Programmable SoCs enable extensive system level +differentiation, integration, and flexibility through hardware, software, +and I/O programmability. + +* zc702 (single qspi, gem0, mmc) [1] +* zc706 (dual parallel qspi, gem0, mmc) [2] +* zed (single qspi, gem0, mmc) [3] +* microzed (single qspi, gem0, mmc) [4] +* zc770 + - zc770-xm010 (single qspi, gem0, mmc) + - zc770-xm011 (8 or 16 bit nand) + - zc770-xm012 (nor) + - zc770-xm013 (dual parallel qspi, gem1) + +Building +-------- + +configure and build for zc702 board:: + + $ export DEVICE_TREE=zynq-zc702 + $ make xilinx_zynq_virt_defconfig + $ make + +Bootmode +-------- + +Zynq has a facility to read the bootmode from the slcr bootmode register +once user is setting through jumpers on the board - see page no:1546 on [5] + +All possible bootmode values are defined in Table 6-2:Boot_Mode MIO Pins +on [5]. + +board_late_init() will read the bootmode values using slcr bootmode register +at runtime and assign the modeboot variable to specific bootmode string which +is intern used in autoboot. + +SLCR bootmode register Bit[3:0] values + +.. code-block:: c + + #define ZYNQ_BM_NOR 0x02 + #define ZYNQ_BM_SD 0x05 + #define ZYNQ_BM_JTAG 0x0 + +"modeboot" variable can assign any of "norboot", "sdboot" or "jtagboot" +bootmode strings at runtime. + +Flashing +-------- + +SD Card +^^^^^^^ + +To write an image that boots from a SD card first create a FAT32 partition +and a FAT32 filesystem on the SD card:: + + sudo fdisk /dev/sdx + sudo mkfs.vfat -F 32 /dev/sdx1 + +Mount the SD card and copy the SPL and U-Boot to the root directory of the +SD card:: + + sudo mount -t vfat /dev/sdx1 /mnt + sudo cp spl/boot.bin /mnt + sudo cp u-boot.img /mnt + +Mainline status +--------------- + +- Added basic board configurations support. +- Added zynq u-boot bsp code - arch/arm/mach-zynq +- Added zynq boards named - zc70x, zed, microzed, zc770_xm010/xm011/xm012/xm013 +- Added zynq drivers: + + :serial: drivers/serial/serial_zynq.c + :net: drivers/net/zynq_gem.c + :mmc: drivers/mmc/zynq_sdhci.c + :spi: drivers/spi/zynq_spi.c + :qspi: drivers/spi/zynq_qspi.c + :i2c: drivers/i2c/zynq_i2c.c + :nand: drivers/mtd/nand/raw/zynq_nand.c + +- Done proper cleanups on board configurations +- Added basic FDT support for zynq boards +- d-cache support for zynq_gem.c + +* [1] http://www.xilinx.com/products/boards-and-kits/EK-Z7-ZC702-G.htm +* [2] http://www.xilinx.com/products/boards-and-kits/EK-Z7-ZC706-G.htm +* [3] http://zedboard.org/product/zedboard +* [4] http://zedboard.org/product/microzed +* [5] http://www.xilinx.com/support/documentation/user_guides/ug585-Zynq-7000-TRM.pdf + + +.. Jagannadha Sutradharudu Teki <jaganna@xilinx.com> +.. Sun Dec 15 14:52:41 IST 2013 diff --git a/roms/u-boot/doc/board/xilinx/zynqmp-r5.rst b/roms/u-boot/doc/board/xilinx/zynqmp-r5.rst new file mode 100644 index 000000000..2cd368b03 --- /dev/null +++ b/roms/u-boot/doc/board/xilinx/zynqmp-r5.rst @@ -0,0 +1,137 @@ +.. SPDX-License-Identifier: GPL-2.0 +.. (C) Copyright 2020 Xilinx, Inc. + +ZYNQMP-R5 +========= + +About this +---------- + +This document describes the information about Xilinx Zynq UltraScale+ MPSOC +U-Boot Cortex R5 support. + +ZynqMP R5 boards +---------------- + +* zynqmp-r5 - U-Boot running on RPU Cortex-R5 + +Building +-------- + +configure and build armv7 toolchain:: + + $ make xilinx_zynqmp_r5_defconfig + $ make + +Notes +^^^^^ + +Output fragment is u-boot. + +Loading +------- + +ZynqMP R5 U-Boot was created for supporting loading OS on RPU. There are two +ways how to start U-Boot on R5. + +Bootgen +^^^^^^^ + +The first way is to use Xilinx FSBL (First stage +bootloader) to load u-boot and start it. The following bif can be used for boot +image generation via Xilinx bootgen utility:: + + + the_ROM_image: + { + [bootloader,destination_cpu=r5-0] fsbl_rpu.elf + [destination_cpu=r5-0]u-boot.elf + } + +Bootgen command for building boot.bin:: + + bootgen -image <bif>.bif -r -w -o i boot.bin + + +U-Boot cpu command +^^^^^^^^^^^^^^^^^^ + +The second way to load U-Boot to Cortex R5 is from U-Boot running on A53 as is +visible from the following log:: + + U-Boot SPL 2020.10-rc4-00090-g801b3d5c5757 (Sep 15 2020 - 14:07:24 +0200) + PMUFW: v1.1 + Loading new PMUFW cfg obj (2024 bytes) + EL Level: EL3 + Multiboot: 0 + Trying to boot from MMC2 + spl: could not initialize mmc. error: -19 + Trying to boot from MMC1 + spl_load_image_fat_os: error reading image u-boot.bin, err - -2 + NOTICE: ATF running on XCZU7EG/EV/silicon v4/RTL5.1 at 0xfffea000 + NOTICE: BL31: v2.2(release):v2.2-614-ged9dc512fb9c + NOTICE: BL31: Built : 09:32:09, Mar 13 2020 + + + U-Boot 2020.10-rc4-00090-g801b3d5c5757 (Sep 15 2020 - 14:07:24 +0200) + + Model: ZynqMP ZCU104 RevC + Board: Xilinx ZynqMP + DRAM: 2 GiB + PMUFW: v1.1 + EL Level: EL2 + Chip ID: zu7e + WDT: Started with servicing (60s timeout) + NAND: 0 MiB + MMC: mmc@ff170000: 0 + Loading Environment from FAT... *** Warning - bad CRC, using default environment + + In: serial + Out: serial + Err: serial + Bootmode: LVL_SHFT_SD_MODE1 + Reset reason: SOFT + Net: + ZYNQ GEM: ff0e0000, mdio bus ff0e0000, phyaddr 12, interface rgmii-id + eth0: ethernet@ff0e0000 + Hit any key to stop autoboot: 0 + ZynqMP> setenv autoload no + ZynqMP> dhcp + BOOTP broadcast 1 + DHCP client bound to address 192.168.0.167 (8 ms) + ZynqMP> tftpboot 20000000 192.168.0.105:u-boot-r5-2.elf + Using ethernet@ff0e0000 device + TFTP from server 192.168.0.105; our IP address is 192.168.0.167 + Filename 'u-boot-r5-2.elf'. + Load address: 0x20000000 + Loading: ################################################################# + ################################################################# + ################################################################# + ################################################################# + ################################################################# + ################################################################# + ################ + 376 KiB/s + done + Bytes transferred = 2075464 (1fab48 hex) + ZynqMP> setenv autostart no + ZynqMP> bootelf -p 20000000 + ZynqMP> cpu 4 release 10000000 lockstep + Using TCM jump trampoline for address 0x10000000 + R5 lockstep mode + ZynqMP> + +Then on second uart you can see U-Boot up and running on R5:: + + U-Boot 2020.10-rc4-00071-g7045622cc9ba (Sep 16 2020 - 13:38:53 +0200) + + Model: Xilinx ZynqMP R5 + DRAM: 512 MiB + MMC: + In: serial@ff010000 + Out: serial@ff010000 + Err: serial@ff010000 + Net: No ethernet found. + ZynqMP r5> + +Please make sure MIO pins for uart are properly configured to see output. diff --git a/roms/u-boot/doc/board/xilinx/zynqmp.rst b/roms/u-boot/doc/board/xilinx/zynqmp.rst new file mode 100644 index 000000000..a035cff1a --- /dev/null +++ b/roms/u-boot/doc/board/xilinx/zynqmp.rst @@ -0,0 +1,115 @@ +.. SPDX-License-Identifier: GPL-2.0 +.. (C) Copyright 2020 Xilinx, Inc. + +ZYNQMP +====== + +About this +---------- + +This document describes the information about Xilinx Zynq UltraScale+ MPSOC +U-Boot support. Core support is available in arch/arm/mach-zynqmp folder. + +ZynqMP boards +------------- + +* zcu100 (ultra96 v1), zcu102, zcu104, zcu106 - Evaluation boards +* zc1232 - Characterization boards +* zcu111, zcu208, zcu216 - RFSOC evaluation boards +* zcu1254, zcu1275, zcu1285 - RFSOC characterization boards +* a2197 - System Controller on Versal boards +* mini - Mini U-Boot running out of OCM +* zc1751 - Characterization Processor boards + - zc1751-xm015-dc1 + - zc1751-xm016-dc2 + - zc1751-xm017-dc3 + - zc1751-xm018-dc4 + - zc1751-xm019-dc5 + +Building +-------- + +Configure and build for zcu102 board:: + + $ source arm64 toolchain + $ export DEVICE_TREE=zynqmp-zcu102-revA + $ make xilinx_zynqmp_virt_defconfig + $ make + +U-Boot SPL flow +--------------- + +For getting U-Boot SPL flow up and running it is necessary to do some additional +steps because booting device requires external images which are not the part of +U-Boot repository. + +PMU firmware +^^^^^^^^^^^^ +The Platform Management Unit (PMU) RAM can be loaded with a firmware (PMU +Firmware) at run-time and can be used to extend or customize the functionality +of PMU. The PMU firmware is the part of boot image (boot.bin) and it is +automatically loaded by BootROM. boot.bin can be directly generated by mkimage +tool as the part of make. If you want to create boot.bin with PMU Firmware +include please point CONFIG_PMUFW_INIT_FILE to PMU firmware binary. For example::: + + CONFIG_PMUFW_INIT_FILE="<path>/pmu.bin" + +If you see below message you need to load PMU Firmware:: + + PMUFW is not found - Please load it! + +The second external blob is PMU Configuration object which is object which is +passed from U-Boot SPL to PMU Firmware for initial system configuration. PMU +configuration object is the part of U-Boot SPL image. For pointing to this +object please use CONFIG_ZYNQMP_SPL_PM_CFG_OBJ_FILE symbol. For example::: + + CONFIG_ZYNQMP_SPL_PM_CFG_OBJ_FILE="<path>/pmu_obj.bin" + + +PMU configuration object +^^^^^^^^^^^^^^^^^^^^^^^^ + +Object can be obtain in several ways. The easiest way is to take pm_cfg_obj.c +from SDK/Vitis design and build it::: + + $ git clone https://github.com/Xilinx/embeddedsw.git + $ export EMBEDDED_SW=$PWD/embeddedsw + $ gcc -c pm_cfg_obj.c -I ${EMBEDDED_SW}/lib/bsp/standalone/src/common/ -I ${EMBEDDED_SW}/lib/sw_services/xilpm/src/zynqmp/client/common/ + $ objcopy -O binary pm_cfg_obj.o pmu_obj.bin + +The second way is to use tools/zynqmp_pm_cfg_obj_convert.py. For more +information about this tool please run it with -h parameter. + +The third way is to extract it from Xilinx FSBL elf file. Object is starting at +XPm_ConfigObject symbol. + + +Arm Trusted Firmware (ATF) +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +U-Boot itself can run from EL3 to EL1. Without ATF U-Boot runs in EL3. Boot flow +is U-Boot SPL->U-Boot in EL3. When ATF is used U-Boot normally runs in EL2. Boot +flow is U-Boot SPL->ATF->U-Boot in EL2. As the part of build process u-boot.itb +is generated. When BL31 shell variable is present u-boot.itb is generated with +ATF included. You can point to it by::: + + $ export BL31=<path>/bl31.bin + +Flashing +-------- + +SD Card +^^^^^^^ + +To write an image that boots from a SD card first create a FAT32 partition +and a FAT32 filesystem on the SD card:: + + sudo fdisk /dev/sdx + sudo mkfs.vfat -F 32 /dev/sdx1 + +Mount the SD card and copy the SPL and U-Boot to the root directory of the +SD card:: + + sudo mount -t vfat /dev/sdx1 /mnt + sudo cp spl/boot.bin /mnt + sudo cp u-boot.itb /mnt diff --git a/roms/u-boot/doc/bounces b/roms/u-boot/doc/bounces new file mode 100644 index 000000000..d1c5f0d24 --- /dev/null +++ b/roms/u-boot/doc/bounces @@ -0,0 +1,3 @@ +# List of addresses picked up by patman/get_maintainer.pl that are known to +# bounce. Addresses are listed one per line and need to match the author +# information recorded in git. diff --git a/roms/u-boot/doc/build/clang.rst b/roms/u-boot/doc/build/clang.rst new file mode 100644 index 000000000..1d35616eb --- /dev/null +++ b/roms/u-boot/doc/build/clang.rst @@ -0,0 +1,76 @@ +Building with Clang +=================== + +The biggest problem when trying to compile U-Boot with Clang is that almost all +archs rely on storing gd in a global register and the Clang 3.5 user manual +states: "Clang does not support global register variables; this is unlikely to +be implemented soon because it requires additional LLVM backend support." + +The ARM backend can be instructed not to use the r9 and x18 registers using +-ffixed-r9 or -ffixed-x18 respectively. As global registers themselves are not +supported inline assembly is needed to get and set the r9 or x18 value. This +leads to larger code then strictly necessary, but at least works. + +**NOTE:** target compilation only work for _some_ ARM boards at the moment. +Also AArch64 is not supported currently due to a lack of private libgcc +support. Boards which reassign gd in c will also fail to compile, but there is +in no strict reason to do so in the ARM world, since crt0.S takes care of this. +These assignments can be avoided by changing the init calls but this is not in +mainline yet. + + +Debian based +------------ + +Required packages can be installed via apt, e.g. + +.. code-block:: bash + + sudo apt-get install clang + +Note that we still use binutils for some tools so we must continue to set +CROSS_COMPILE. To compile U-Boot with Clang on Linux without IAS use e.g. + +.. code-block:: bash + + make HOSTCC=clang rpi_2_defconfig + make HOSTCC=clang CROSS_COMPILE=arm-linux-gnueabi- \ + CC="clang -target arm-linux-gnueabi" -j8 + +It can also be used to compile sandbox: + +.. code-block:: bash + + make HOSTCC=clang sandbox_defconfig + make HOSTCC=clang CC=clang -j8 + + +FreeBSD 11 +---------- + +Since llvm 3.4 is currently in the base system, the integrated assembler as +is incapable of building U-Boot. Therefore gas from devel/arm-gnueabi-binutils +is used instead. It needs a symlink to be picked up correctly though: + +.. code-block:: bash + + ln -s /usr/local/bin/arm-gnueabi-freebsd-as /usr/bin/arm-freebsd-eabi-as + +The following commands compile U-Boot using the Clang xdev toolchain. + +**NOTE:** CROSS_COMPILE and target differ on purpose! + +.. code-block:: bash + + export CROSS_COMPILE=arm-gnueabi-freebsd- + gmake rpi_2_defconfig + gmake CC="clang -target arm-freebsd-eabi --sysroot /usr/arm-freebsd" -j8 + +Given that U-Boot will default to gcc, above commands can be +simplified with a simple wrapper script - saved as +/usr/local/bin/arm-gnueabi-freebsd-gcc - listed below: + +.. code-block:: bash + + #!/bin/sh + exec clang -target arm-freebsd-eabi --sysroot /usr/arm-freebsd "$@" diff --git a/roms/u-boot/doc/build/docker.rst b/roms/u-boot/doc/build/docker.rst new file mode 100644 index 000000000..953d1b28a --- /dev/null +++ b/roms/u-boot/doc/build/docker.rst @@ -0,0 +1,14 @@ +GitLab CI / U-Boot runner container +=================================== + +In order to have a reproducible and portable build environment for CI we use a container for building in. This means that developers can also reproduce the CI environment, to a large degree at least, locally. This file is located in the tools/docker directory. To build the image yourself + +.. code-block:: bash + + sudo docker build -t your-namespace:your-tag . + +Or to use an existing container + +.. code-block:: bash + + sudo docker pull trini/u-boot-gitlab-ci-runner:bionic-20200807-02Sep2020 diff --git a/roms/u-boot/doc/build/gcc.rst b/roms/u-boot/doc/build/gcc.rst new file mode 100644 index 000000000..c51b3e73b --- /dev/null +++ b/roms/u-boot/doc/build/gcc.rst @@ -0,0 +1,139 @@ +Building with GCC +================= + +Dependencies +------------ + +For building U-Boot you need a GCC compiler for your host platform. If you +are not building on the target platform you further need a GCC cross compiler. + +Debian based +~~~~~~~~~~~~ + +On Debian based systems the cross compiler packages are named +gcc-<architecture>-linux-gnu. + +You could install GCC and the GCC cross compiler for the ARMv8 architecture with + +.. code-block:: bash + + sudo apt-get install gcc gcc-aarch64-linux-gnu + +Depending on the build targets further packages maybe needed + +.. code-block:: bash + + sudo apt-get install bc bison build-essential coccinelle \ + device-tree-compiler dfu-util efitools flex gdisk liblz4-tool \ + libguestfs-tools libncurses-dev libpython3-dev libsdl2-dev libssl-dev \ + lzma-alone openssl python3 python3-coverage python3-pyelftools \ + python3-pytest python3-sphinxcontrib.apidoc python3-sphinx-rtd-theme swig + +SUSE based +~~~~~~~~~~ + +On suse based systems the cross compiler packages are named +cross-<architecture>-gcc<version>. + +You could install GCC and the GCC 10 cross compiler for the ARMv8 architecture +with + +.. code-block:: bash + + sudo zypper install gcc cross-aarch64-gcc10 + +Depending on the build targets further packages maybe needed. + +.. code-block:: bash + + zypper install bc bison flex gcc libopenssl-devel libSDL2-devel make \ + ncurses-devel python3-devel python3-pytest swig + +Prerequisites +------------- + +For some boards you have to build prerequisite files before you can build +U-Boot, e.g. for the some boards you will need to build the ARM Trusted Firmware +beforehand. Please, refer to the board specific documentation +:doc:`../board/index`. + +Configuration +------------- + +Directory configs/ contains the template configuration files for the maintained +boards following the naming scheme:: + + <board name>_defconfig + +These files have been stripped of default settings. So you cannot use them +directly. Instead their name serves as a make target to generate the actual +configuration file .config. For instance the configuration template for the +Odroid C2 board is called odroid-c2_defconfig. The corresponding .config file +is generated by + +.. code-block:: bash + + make odroid-c2_defconfig + +You can adjust the configuration using + +.. code-block:: bash + + make menuconfig + +Building +-------- + +When cross compiling you will have to specify the prefix of the cross-compiler. +You can either specify the value of the CROSS_COMPILE variable on the make +command line or export it beforehand. + +.. code-block:: bash + + CROSS_COMPILE=<compiler-prefix> make + +Assuming cross compiling on Debian for ARMv8 this would be + +.. code-block:: bash + + CROSS_COMPILE=aarch64-linux-gnu- make + +Build parameters +~~~~~~~~~~~~~~~~ + +A list of available parameters for the make command can be obtained via + +.. code-block:: bash + + make help + +You can speed up compilation by parallelization using the -j parameter, e.g. + +.. code-block:: bash + + CROSS_COMPILE=aarch64-linux-gnu- make -j$(nproc) + +Further important build parameters are + +* O=<dir> - generate all output files in directory <dir>, including .config +* V=1 - verbose build + +Other build targets +~~~~~~~~~~~~~~~~~~~ + +A list of all make targets can be obtained via + +.. code-block:: bash + + make help + +Important ones are + +* clean - remove most generated files but keep the configuration +* mrproper - remove all generated files + config + various backup files + +Installation +------------ + +The process for installing U-Boot on the target device is device specific. +Please, refer to the board specific documentation :doc:`../board/index`. diff --git a/roms/u-boot/doc/build/index.rst b/roms/u-boot/doc/build/index.rst new file mode 100644 index 000000000..69952f90d --- /dev/null +++ b/roms/u-boot/doc/build/index.rst @@ -0,0 +1,13 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +Build U-Boot +============ + +.. toctree:: + :maxdepth: 2 + + source + gcc + clang + docker + tools diff --git a/roms/u-boot/doc/build/source.rst b/roms/u-boot/doc/build/source.rst new file mode 100644 index 000000000..470f79398 --- /dev/null +++ b/roms/u-boot/doc/build/source.rst @@ -0,0 +1,30 @@ +Obtaining the source +===================== + +The source of the U-Boot project is maintained in a Git repository. + +You can download the source via + +.. code-block:: bash + + git clone https://source.denx.de/u-boot/u-boot.git + +A mirror of the source is maintained on Github + +.. code-block:: bash + + git clone https://github.com/u-boot/u-boot + +The released versions are available as tags which use the naming scheme:: + + v<year>.<month> + +Release candidates are named:: + + v<year>.<month>-rc<number> + +To checkout the October 2020 release you would use: + +.. code-block:: bash + + git checkout v2020.10 diff --git a/roms/u-boot/doc/build/tools.rst b/roms/u-boot/doc/build/tools.rst new file mode 100644 index 000000000..c06f91527 --- /dev/null +++ b/roms/u-boot/doc/build/tools.rst @@ -0,0 +1,47 @@ +.. SPDX-License-Identifier: GPL-2.0+ +.. sectionauthor:: Bin Meng <bmeng.cn@gmail.com> + +Host tools +========== + +Building tools for Linux +------------------------ + +To allow distributions to distribute all possible tools in a generic way, +avoiding the need of specific tools building for each machine, a tools only +defconfig file is provided. + +Using this, we can build the tools by doing:: + + $ make tools-only_defconfig + $ make tools-only + +Building tools for Windows +-------------------------- +If you wish to generate Windows versions of the utilities in the tools directory +you can use MSYS2, a software distro and building platform for Windows. + +Download the MSYS2 installer from https://www.msys2.org. Make sure you have +installed all required packages below in order to build these host tools:: + + * gcc (9.1.0) + * make (4.2.1) + * bison (3.4.2) + * diffutils (3.7) + * openssl-devel (1.1.1.d) + +Note the version numbers in these parentheses above are the package versions +at the time being when writing this document. The MSYS2 installer tested is +http://repo.msys2.org/distrib/x86_64/msys2-x86_64-20190524.exe. + +There are 3 MSYS subsystems installed: MSYS2, MinGW32 and MinGW64. Each +subsystem provides an environment to build Windows applications. The MSYS2 +environment is for building POSIX compliant software on Windows using an +emulation layer. The MinGW32/64 subsystems are for building native Windows +applications using a linux toolchain (gcc, bash, etc), targeting respectively +32 and 64 bit Windows. + +Launch the MSYS2 shell of the MSYS2 environment, and do the following:: + + $ make tools-only_defconfig + $ make tools-only NO_SDL=1 diff --git a/roms/u-boot/doc/chromium/chainload.rst b/roms/u-boot/doc/chromium/chainload.rst new file mode 100644 index 000000000..7b6bb10d3 --- /dev/null +++ b/roms/u-boot/doc/chromium/chainload.rst @@ -0,0 +1,257 @@ +.. SPDX-License-Identifier: GPL-2.0+ +.. Copyright 2020 Google LLC + +Running U-Boot from coreboot on Chromebooks +=========================================== + +U-Boot can be used as a secondary boot loader in a few situations such as from +UEFI and coreboot (see README.x86). Recent Chromebooks use coreboot even on +ARM platforms to start up the machine. + +This document aims to provide a guide to booting U-Boot on a Chromebook. It +is only a starting point, and there are many guides on the interwebs. But +placing this information in the U-Boot tree should make it easier to find for +those who use U-Boot habitually. + +Most of these platforms are supported by U-Boot natively, but it is risky to +replace the ROM unless you have a servo board and cable to restore it with. + + +For all of these the standard U-Boot build instructions apply. For example on +ARM:: + + sudo apt install gcc-arm-linux-gnueabi + mkdir b + make O=b/nyan_big CROSS_COMPILE=arm-linux-gnueabi- nyan-big_defconfig all + +You can obtain the vbutil_kernel utility here: + + https://drive.google.com/open?id=0B7WYZbZ9zd-3dHlVVXo4VXE2T0U + + +Snow (Samsung ARM Chromebook) +----------------------------- + +See here: + +https://www.chromium.org/chromium-os/firmware-porting-guide/using-nv-u-boot-on-the-samsung-arm-chromebook + + +Nyan-big +-------- + +Compiled based on information here:: + + https://lists.denx.de/pipermail/u-boot/2015-March/209530.html + https://git.collabora.com/cgit/user/tomeu/u-boot.git/commit/?h=nyan-big + https://lists.denx.de/pipermail/u-boot/2017-May/289491.html + https://github.com/chromeos-nvidia-androidtv/gnu-linux-on-acer-chromebook-13#copy-data-to-the-sd-card + +1. Build U-Boot + +Steps:: + + mkdir b + make -j8 O=b/nyan-big CROSS_COMPILE=arm-linux-gnueabi- nyan-big_defconfig all + + +2. Select a .its file + +Select something from doc/chromium which matches your board, or create your +own. + +Note that the device tree node is required, even though it is not actually +used by U-Boot. This is because the Chromebook expects to pass it to the +kernel, and crashes if it is not present. + + +3. Build and sign an image + +Steps:: + + ./b/nyan-big/tools/mkimage -f doc/chromium/files/nyan-big.its u-boot-chromium.fit + echo test >dummy.txt + vbutil_kernel --arch arm \ + --keyblock doc/chromium/files/devkeys/kernel.keyblock \ + --signprivate doc/chromium/files/devkeys/kernel_data_key.vbprivk \ + --version 1 --config dummy.txt --vmlinuz u-boot-chromium.fit \ + --bootloader dummy.txt --pack u-boot.kpart + + +4. Prepare an SD card + +Steps:: + + DISK=/dev/sdc # Replace with your actual SD card device + sudo cgpt create $DISK + sudo cgpt add -b 34 -s 32768 -P 1 -S 1 -t kernel $DISK + sudo cgpt add -b 32802 -s 2000000 -t rootfs $DISK + sudo gdisk $DISK # Enter command 'w' to write a protective MBR to the disk + + +5. Write U-Boot to the SD card + +Steps:: + + sudo dd if=u-boot.kpart of=/dev/sdc1; sync + + +6. Start it up + +Reboot the device in dev mode. Make sure that you have USB booting enabled. To +do this, login as root (via Ctrl-Alt-forward_arrow) and type +'enable_dev_usb_boot'. You only need to do this once. + +Reboot the device with the SD card inserted. Press Clrl-U at the developer +mode screen. It should show something like the following on the display:: + + U-Boot 2017.07-00637-g242eb42-dirty (May 22 2017 - 06:14:21 -0600) + + Model: Acer Chromebook 13 CB5-311 + Board: Google/NVIDIA Nyan-big, ID: 1 + + Net: No ethernet found. + Hit any key to stop autoboot: 0 + Tegra124 (Nyan-big) # + + +7. Known problems + +On the serial console the word MMC is chopped at the start of the line:: + + C: sdhci@700b0000: 2, sdhci@700b0400: 1, sdhci@700b0600: 0 + +This is likely due to some problem with change-over of the serial driver +during relocation (or perhaps updating the clock setup in board_init()). + + +9. Notes + +To check that you copied the u-boot.its file correctly, use these commands. +You should see that the data at 0x100 in u-boot-chromium.fit is the first few +bytes of U-Boot:: + + hd u-boot-chromium.fit |head -20 + ... + 00000100 b8 00 00 ea 14 f0 9f e5 14 f0 9f e5 14 f0 9f e5 |................| + + hd b/nyan-big/u-boot.bin |head + 00000000 b8 00 00 ea 14 f0 9f e5 14 f0 9f e5 14 f0 9f e5 |................| + + +The 'data' property of the FIT is set up to start at offset 0x100 bytes into +the file. The change to CONFIG_SYS_TEXT_BASE is also an offset of 0x100 bytes +from the load address. If this changes, you either need to modify U-Boot to be +fully relocatable, or expect it to hang. + + +chromebook_jerry +---------------- + +The instruction are similar to those for Nyan with changes as noted below: + +1. Patch U-Boot + +Open include/configs/rk3288_common.h + +Change:: + + #define CONFIG_SYS_TEXT_BASE 0x00100000 + +to:: + + #define CONFIG_SYS_TEXT_BASE 0x02000100 + + + +2. Build U-Boot + +Steps:: + + mkdir b + make -j8 O=b/chromebook_jerry CROSS_COMPILE=arm-linux-gnueabi- \ + chromebook_jerry_defconfig all + + +3. See above + +4. Build and sign an image + +Steps:: + + ./b/chromebook_jerry/tools/mkimage -f doc/chromium/chromebook_jerry.its \ + u-boot-chromium.fit + echo test >dummy.txt + vbutil_kernel --arch arm \ + --keyblock doc/chromium/files/devkeys/kernel.keyblock \ + --signprivate doc/chromium/files/devkeys/kernel_data_key.vbprivk \ + --version 1 --config dummy.txt --vmlinuz u-boot-chromium.fit \ + --bootloader dummy.txt --pack u-boot.kpart + + +5. See above + +6. See above + +7. Start it up + +Reboot the device in dev mode. Make sure that you have USB booting enabled. To +do this, login as root (via Ctrl-Alt-forward_arrow) and type +'enable_dev_usb_boot'. You only need to do this once. + +Reboot the device with the SD card inserted. Press Clrl-U at the developer +mode screen. It should show something like the following on the display:: + + U-Boot 2017.05-00649-g72acdbf-dirty (May 29 2017 - 14:57:05 -0600) + + Model: Google Jerry + Net: Net Initialization Skipped + No ethernet found. + Hit any key to stop autoboot: 0 + + +8. Known problems + +None as yet. + + +9. Notes + +None as yet. + + +Other notes +----------- + +flashrom +~~~~~~~~ + +Used to make a backup of your firmware, or to replace it. + +See: https://www.chromium.org/chromium-os/packages/cros-flashrom + + +coreboot +~~~~~~~~ + +Coreboot itself is not designed to actually boot an OS. Instead, a program +called Depthcharge is used. This originally came out of U-Boot and was then +heavily hacked and modified such that is is almost unrecognisable. It does +include a very small part of the U-Boot command-line interface but is not +usable as a general-purpose boot loader. + +In addition, it has a very unusual design in that it does not do device init +itself, but instead relies on coreboot. This is similar to (in U-Boot) having +a SPI driver with an empty probe() method, relying on whatever was set up +beforehand. It can be quite hard to figure out between these two code bases +what settings are actually used. When chain-loading into U-Boot we must be +careful to reinit anything that U-Boot expects. If not, some peripherals (or +the whole machine) may not work. This makes the process of chainloading more +complicated than it could be on some platforms. + +Finally, it supports only a subset of the U-Boot's FIT format. In particular +it uses a fixed address to load the FIT and does not support load/exec +addresses. This means that U-Boot must be able to boot from whatever +address Depthcharge happens to use (it is the CONFIG_KERNEL_START setting +in Depthcharge). In practice this means that the data in the kernel@1 FIT node +(see above) must start at the same address as U-Boot's CONFIG_SYS_TEXT_BASE. diff --git a/roms/u-boot/doc/chromium/files/chromebook_jerry.its b/roms/u-boot/doc/chromium/files/chromebook_jerry.its new file mode 100644 index 000000000..7505a2053 --- /dev/null +++ b/roms/u-boot/doc/chromium/files/chromebook_jerry.its @@ -0,0 +1,42 @@ +/dts-v1/; + +/ { + description = "U-Boot mainline"; + #address-cells = <1>; + + images { + kernel { + description = "U-Boot mainline"; + type = "kernel_noload"; + arch = "arm"; + os = "linux"; + data = /incbin/("../../b/chromebook_jerry/u-boot.bin"); + compression = "none"; + load = <0>; + entry = <0>; + hash-2 { + algo = "sha1"; + }; + }; + + fdt-1{ + description = "rk3288-veryron-jerry.dtb"; + data = /incbin/("../../b/chromebook_jerry/u-boot.dtb"); + type = "flat_dt"; + arch = "arm"; + compression = "none"; + hash-1{ + algo = "sha1"; + }; + }; + }; + + configurations { + default = "config-1"; + config-1 { + description = "Boot U-Boot"; + kernel = "kernel"; + fdt = "fdt-1"; + }; + }; +}; diff --git a/roms/u-boot/doc/chromium/files/devkeys/kernel.keyblock b/roms/u-boot/doc/chromium/files/devkeys/kernel.keyblock Binary files differnew file mode 100644 index 000000000..9740be4e6 --- /dev/null +++ b/roms/u-boot/doc/chromium/files/devkeys/kernel.keyblock diff --git a/roms/u-boot/doc/chromium/files/devkeys/kernel_data_key.vbprivk b/roms/u-boot/doc/chromium/files/devkeys/kernel_data_key.vbprivk Binary files differnew file mode 100644 index 000000000..8d392fb29 --- /dev/null +++ b/roms/u-boot/doc/chromium/files/devkeys/kernel_data_key.vbprivk diff --git a/roms/u-boot/doc/chromium/files/nyan-big.its b/roms/u-boot/doc/chromium/files/nyan-big.its new file mode 100644 index 000000000..bd412915e --- /dev/null +++ b/roms/u-boot/doc/chromium/files/nyan-big.its @@ -0,0 +1,42 @@ +/dts-v1/; + +/ { + description = "U-Boot mainline"; + #address-cells = <1>; + + images { + kernel { + description = "U-Boot mainline "; + type = "kernel_noload"; + arch = "arm"; + os = "linux"; + data = /incbin/("../.././b/nyan-big/u-boot.bin"); + compression = "none"; + load = <0>; + entry = <0>; + hash-2 { + algo = "sha1"; + }; + }; + + fdt-1{ + description = "tegra124-nyan-big.dtb"; + data = /incbin/("../.././b/nyan-big/u-boot.dtb"); + type = "flat_dt"; + arch = "arm"; + compression = "none"; + hash-1{ + algo = "sha1"; + }; + }; + }; + + configurations { + default = "config-1"; + config-1 { + description = "Boot U-Boot"; + kernel = "kernel"; + fdt = "fdt-1"; + }; + }; +}; diff --git a/roms/u-boot/doc/chromium/index.rst b/roms/u-boot/doc/chromium/index.rst new file mode 100644 index 000000000..0722c2500 --- /dev/null +++ b/roms/u-boot/doc/chromium/index.rst @@ -0,0 +1,14 @@ +.. SPDX-License-Identifier: GPL-2.0+ +.. Copyright 2020 Google LLC + +Chromium OS-specific doc +======================== + +This provides some information about Chromium OS and U-Boot. + +.. toctree:: + :maxdepth: 2 + + overview + run_vboot + chainload diff --git a/roms/u-boot/doc/chromium/overview.rst b/roms/u-boot/doc/chromium/overview.rst new file mode 100644 index 000000000..790233cb6 --- /dev/null +++ b/roms/u-boot/doc/chromium/overview.rst @@ -0,0 +1,74 @@ +.. SPDX-License-Identifier: GPL-2.0+ +.. Copyright 2020 Google LLC + +Chromium OS Support in U-Boot +============================= + +Introduction +------------ + +This describes how to use U-Boot with Chromium OS. Several options are +available: + + - Running U-Boot from the 'altfw' feature, which is available on selected + Chromebooks from 2019 onwards (initially Grunt). Press '1' from the + developer-mode screen to get into U-Boot. See here for details: + https://chromium.googlesource.com/chromiumos/docs/+/HEAD/developer_mode.md + + - Running U-Boot from the disk partition. This involves signing U-Boot and + placing it on the disk, for booting as a 'kernel'. See + :doc:`chainload` for information on this. This is the only + option on non-U-Boot Chromebooks from 2013 to 2018 and is somewhat + more involved. + + - Running U-Boot with Chromium OS verified boot. This allows U-Boot to be + used instead of either or both of depthcharge (a bootloader which forked + from U-Boot in 2013) and coreboot. See :doc:`run_vboot` for more + information on this. + + - Running U-Boot from coreboot. This allows U-Boot to run on more devices + since many of them only support coreboot as the bootloader and have + no bare-metal support in U-Boot. For this, use the 'coreboot' target. + + - Running U-Boot and booting into a Chrome OS image, but without verified + boot. This can be useful for testing. + + +Talks and documents +------------------- + +Here is some material relevant to Chromium OS verified boot with U-Boot: + + - "U-Boot with Chrome OS and firmware packaging" + + - Author: Simon Glass + - Presented at Open Source Firmware Conference 2018, Erlangen + - Describes the work in progress as at the end of 2018 + - Slides at `OSFC <https://2018.osfc.io/uploads/talk/paper/26/U-Boot_with_Chrome_OS_and_firmware_packaging.pdf>`_ + - `Youtube video 'OSFC - U-Boot with Chrome OS and firmware packaging' <https://www.youtube.com/watch?v=1jknxUvmwpo>`_ + + - "Verified Boot in Chrome OS and how to make it work for you" + + - Author: Simon Glass + - Presented at ELCE 2013, Edinburgh + - Describes the original 2013 implementation as shipped on snow (first + `ARM Chromebook was a Samsung Chromebook <https://www.cnet.com/products/samsung-series-3-chromebook-xe303c12-11-6-exynos-5250-2-gb-ram-16-gb-ssd-bilingual-english-french/>`_ + with Samsung Exynos5250 `review <https://www.cnet.com/reviews/samsung-chromebook-series-3-review/>`_), + spring (`HP Chromebook 11 <https://www.cnet.com/products/hp-chromebook-11-g2-11-6-exynos-5250-4-gb-ram-16-gb-emmc/>`_) + and pit/pi (`Samsung Chromebook 2 <https://www.cnet.com/products/samsung-chromebook-2-xe503c12-11-6-exynos-5-octa-4-gb-ram-16-gb-ssd/>`_ + with Exynos 5 Octa 5420 in 2014). + - Slides at `Google research <https://research.google/pubs/pub42038/>`_ + - `Youtube video 'Verified Boot on Chrome OS and How to do it yourself' <https://www.youtube.com/watch?v=kdpZC9jFzZA>`_ + + - "Chrome University 2018: Chrome OS Firmware and Verified Boot 201" + + - Author: Duncan Laurie + - Describes Chrome OS firmware as of 2018 and includes a wide range of + topics. This has no U-Boot information, but does cover coreboot and also + talks about the Chrome OS EC and Security chip. This is probably the + best introduction talk. + - `Youtube video 'Chrome University 2018: Chrome OS Firmware and Verified Boot 201' <https://www.youtube.com/watch?v=WY2sWpuda2g>`_ + + - `Chromium OS U-Boot <https://www.chromium.org/developers/u-boot>`_ + + - `Firmware porting Guide <https://www.chromium.org/chromium-os/firmware-porting-guide>`_ diff --git a/roms/u-boot/doc/chromium/run_vboot.rst b/roms/u-boot/doc/chromium/run_vboot.rst new file mode 100644 index 000000000..41b4f6318 --- /dev/null +++ b/roms/u-boot/doc/chromium/run_vboot.rst @@ -0,0 +1,204 @@ +.. SPDX-License-Identifier: GPL-2.0+ +.. Copyright 2020 Google LLC +.. sectionauthor:: Simon Glass <sjg@chromium.org> + + +Running U-Boot with Chromium OS verified boot +============================================= + +To obtain:: + + git clone https://github.com/sjg20/u-boot.git + cd u-boot + git checkout cros-master + + cd .. + git clone https://chromium.googlesource.com/chromiumos/platform/vboot_reference + cd vboot_reference + git checkout 45964294 + # futility: updater: Correct output version for Snow + +To build for sandbox:: + + UB=/tmp/b/chromeos_sandbox # U-Boot build directory + cd u-boot + make O=$UB chromeos_sandbox_defconfig + make O=$UB -j20 -s VBOOT_SOURCE=/path/to/vboot_reference \ + MAKEFLAGS_VBOOT=DEBUG=1 QUIET=1 + +Replace sandbox with another supported target. + +This produces $UB/image.bin which contains the firmware binaries in a SPI +flash image. + +To run on sandbox:: + + CROS=~/cosarm + IMG=$CROS/src/build/images/coral/latest/chromiumos_image.bin + $UB/tpl/u-boot-tpl -d $UB/u-boot.dtb.out \ + -L6 -c "host bind 0 $IMG; vboot go auto" \ + -l -w -s state.dtb -r -n -m $UB/ram + + $UB/tpl/u-boot-tpl -d $UB/u-boot.dtb.out -L6 -l \ + -c "host bind 0 $IMG; vboot go auto" -w -s $UB/state.dtb -r -n -m $UB/mem + + +To run on other boards: + + - Install image.bin in the SPI flash of your device + - Boot your system + + +Sandbox +------- + +Most Chromium OS development with U-Boot is undertaken using sandbox. There is +a sandbox target available (chromeos_sandbox) which allows running U-Boot on +a Linux machine completion with emulations of the display, TPM, disk, etc. + +Running sandbox starts TPL, which contains the first phase of vboot, providing +a device tree and binding a Chromium OS disk image for use to find kernels +(any Chromium OS image will do). It also saves driver state between U-Boot +phases into state.dtb and will automatically ensure that memory is shared +between all phases. TPL will jump to SPL and then on to U-Boot proper. + +It is possible to run with debugging on, e.g.:: + + gdb --args $UB/tpl/u-boot-tpl -d .... + +Breakpoints can be set in any U-Boot phase. Overall this is a good debugging +environment for new verified-boot features. + + +Samus +----- + +Basic support is available for samus, using the chromeos_samus target. If you +have an em100, use:: + + sudo em100 -s -c W25Q128FW -d $UB/image.bin -t -r + +to write the image and then boot samus (Power-Refresh). + + +Boot flow +--------- + +Verified boot starts in TPL, which selects the A or B SPL, which in turn selects +the A or B U-Boot. Then this jumps to the selected kernel. If anything goes +wrong, the device reboots and the recovery SPL and U-Boot are used instead. + +More details are available here: + + https://www.chromium.org/chromium-os/chromiumos-design-docs/firmware-boot-and-recovery + + +New uclasses +------------ + +Several uclasses are provided in cros/: + +UCLASS_CROS_AUX_FW + Chrome OS auxiliary firmware + +UCLASS_CROS_FWSTORE + Chrome OS firmware storage + +UCLASS_CROS_NVDATA + Chrome OS non-volatile data device + +UCLASS_CROS_VBOOT_EC + Chrome OS vboot EC operations + +UCLASS_CROS_VBOOT_FLAG + Chrome OS verified boot flag + +The existing UCLASS_CROS_EC is also used. + + +Commands +-------- + +A new 'vboot' command is provided to run particular vboot stages. The most +useful command is 'vboot go auto', which continues where the last stage left +off. + +Note that TPL and SPL do not supports commands as yet, so the vboot code is +called directly from the SPL boot devices (BOOT_DEVICE_CROS_VBOOT). See +cros_load_image_tpl() and cros_load_image_spl() which both call +vboot_run_auto(). + + +Config options +-------------- + +The main option is CONFIG_CHROMEOS, which enables a wide array of other options +so that the required features are present. + + +Device-tree config +------------------ + +Various options are available which control the operation of verified boot. +See cros/dts/bindings/config.txt for details. Most config is handled at run- +time, although build-time config (with Kconfig) could also be added fairly +easily. + + +Porting to other hardware +------------------------- + +A basic port to samus (Chromebook Pixel 2015) is in a basic working state, +using the chromeos_samus target. Patches will likely be forthcoming in early +2019. Ports to an ARM board and coreboot (for x86 Chromebooks) are in the +dreaming state. + + +Tests +----- + +Chromium OS firmware has a very limited set of tests. The tests that originally +existed in U-Boot were not brought over to coreboot or depthcharge. + +The U-Boot tests ('make check') do operate, but at present there are no +Chromium OS tests available. These will hopefully come together over time. Of +course the above sandbox feature provides a sort of functional test and can +detect problems that affect the flow or particular vboot features. + + +U-Boot without Chromium OS verified boot +---------------------------------------- + +The following script can be used to boot a Chrome OS image on coral:: + + # Read the image header and obtain the address of the kernel + # The offset 4f0 is defined by verified boot and may change for other + # Chromebooks + read mmc 2:2 100000 0 80; setexpr loader *001004f0; + + # Get the kernel size and calculate the number of blocks (0x200 bytes each) + setexpr size *00100518; setexpr blocks $size / 200; + + # Read the full kernel and calculate the address of the setup block + read mmc 2:2 100000 80 $blocks; setexpr setup $loader - 1000; + + # Locate the command line + setexpr cmdline $loader - 2000; + + # Start the zboot process with the loaded kernel, setup block and cmdline + zboot start 100000 0 0 0 $setup $cmdline; + + # Load the kernel, fix up the 'setup' block, dump information + zboot load; zboot setup; zboot dump + + # Boot into Chrome OS + zboot go + + +TO DO +----- + +Get the full ACPI tables working with Coral + + +7 October 2018 diff --git a/roms/u-boot/doc/conf.py b/roms/u-boot/doc/conf.py new file mode 100644 index 000000000..eb74b86ae --- /dev/null +++ b/roms/u-boot/doc/conf.py @@ -0,0 +1,644 @@ +# -*- coding: utf-8 -*- +# +# The U-Boot documentation build configuration file, created by +# sphinx-quickstart on Fri Feb 12 13:51:46 2016. +# +# This file is execfile()d with the current directory set to its +# containing dir. +# +# Note that not all possible configuration values are present in this +# autogenerated file. +# +# All configuration values have a default; values that are commented out +# serve to show the default. + +import sys +import os +import sphinx + +from subprocess import check_output + +# Get Sphinx version +major, minor, patch = sphinx.version_info[:3] + + +# If extensions (or modules to document with autodoc) are in another directory, +# add these directories to sys.path here. If the directory is relative to the +# documentation root, use os.path.abspath to make it absolute, like shown here. +sys.path.insert(0, os.path.abspath('sphinx')) +from load_config import loadConfig + +# -- General configuration ------------------------------------------------ + +# If your documentation needs a minimal Sphinx version, state it here. +needs_sphinx = '1.3' + +# Add any Sphinx extension module names here, as strings. They can be +# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom +# ones. +extensions = ['kerneldoc', 'rstFlatTable', 'kernel_include', + 'kfigure', 'sphinx.ext.ifconfig', # 'automarkup', + 'maintainers_include', 'sphinx.ext.autosectionlabel', + 'kernel_abi', 'kernel_feat'] + +# +# cdomain is badly broken in Sphinx 3+. Leaving it out generates *most* +# of the docs correctly, but not all. Scream bloody murder but allow +# the process to proceed; hopefully somebody will fix this properly soon. +# +if major >= 3: + sys.stderr.write('''WARNING: The kernel documentation build process + support for Sphinx v3.0 and above is brand new. Be prepared for + possible issues in the generated output. + ''') + if (major > 3) or (minor > 0 or patch >= 2): + # Sphinx c function parser is more pedantic with regards to type + # checking. Due to that, having macros at c:function cause problems. + # Those needed to be scaped by using c_id_attributes[] array + c_id_attributes = [ + # GCC Compiler types not parsed by Sphinx: + "__restrict__", + + # include/linux/compiler_types.h: + "__iomem", + "__kernel", + "noinstr", + "notrace", + "__percpu", + "__rcu", + "__user", + + # include/linux/compiler_attributes.h: + "__alias", + "__aligned", + "__aligned_largest", + "__always_inline", + "__assume_aligned", + "__cold", + "__attribute_const__", + "__copy", + "__pure", + "__designated_init", + "__visible", + "__printf", + "__scanf", + "__gnu_inline", + "__malloc", + "__mode", + "__no_caller_saved_registers", + "__noclone", + "__nonstring", + "__noreturn", + "__packed", + "__pure", + "__section", + "__always_unused", + "__maybe_unused", + "__used", + "__weak", + "noinline", + + # include/efi.h + "EFIAPI", + + # include/efi_loader.h + "__efi_runtime", + + # include/linux/memblock.h: + "__init_memblock", + "__meminit", + + # include/linux/init.h: + "__init", + "__ref", + + # include/linux/linkage.h: + "asmlinkage", + ] + +else: + extensions.append('cdomain') + if major == 1 and minor < 7: + sys.stderr.write('WARNING: Sphinx 1.7 or greater will be required as of ' + 'the v2021.04 release\n') + +# Ensure that autosectionlabel will produce unique names +autosectionlabel_prefix_document = True +autosectionlabel_maxdepth = 2 + +# The name of the math extension changed on Sphinx 1.4 +if (major == 1 and minor > 3) or (major > 1): + extensions.append("sphinx.ext.imgmath") +else: + extensions.append("sphinx.ext.pngmath") + +# Add any paths that contain templates here, relative to this directory. +templates_path = ['_templates'] + +# The suffix(es) of source filenames. +# You can specify multiple suffix as a list of string: +# source_suffix = ['.rst', '.md'] +source_suffix = '.rst' + +# The encoding of source files. +#source_encoding = 'utf-8-sig' + +# The master toctree document. +master_doc = 'index' + +# General information about the project. +project = 'Das U-Boot' +copyright = 'The U-Boot development community' +author = 'The U-Boot development community' + +# The version info for the project you're documenting, acts as replacement for +# |version| and |release|, also used in various other places throughout the +# built documents. +# +# In a normal build, version and release are are set to KERNELVERSION and +# KERNELRELEASE, respectively, from the Makefile via Sphinx command line +# arguments. +# +# The following code tries to extract the information by reading the Makefile, +# when Sphinx is run directly (e.g. by Read the Docs). +try: + makefile_version = None + makefile_patchlevel = None + for line in open('../Makefile'): + key, val = [x.strip() for x in line.split('=', 2)] + if key == 'VERSION': + makefile_version = val + elif key == 'PATCHLEVEL': + makefile_patchlevel = val + if makefile_version and makefile_patchlevel: + break +except: + pass +finally: + if makefile_version and makefile_patchlevel: + version = release = makefile_version + '.' + makefile_patchlevel + else: + version = release = "unknown version" + +# The language for content autogenerated by Sphinx. Refer to documentation +# for a list of supported languages. +# +# This is also used if you do content translation via gettext catalogs. +# Usually you set "language" from the command line for these cases. +language = None + +# There are two options for replacing |today|: either, you set today to some +# non-false value, then it is used: +#today = '' +# Else, today_fmt is used as the format for a strftime call. +#today_fmt = '%B %d, %Y' + +# List of patterns, relative to source directory, that match files and +# directories to ignore when looking for source files. +exclude_patterns = ['output'] + +# The reST default role (used for this markup: `text`) to use for all +# documents. +#default_role = None + +# If true, '()' will be appended to :func: etc. cross-reference text. +#add_function_parentheses = True + +# If true, the current module name will be prepended to all description +# unit titles (such as .. function::). +#add_module_names = True + +# If true, sectionauthor and moduleauthor directives will be shown in the +# output. They are ignored by default. +#show_authors = False + +# The name of the Pygments (syntax highlighting) style to use. +pygments_style = 'sphinx' + +# A list of ignored prefixes for module index sorting. +#modindex_common_prefix = [] + +# If true, keep warnings as "system message" paragraphs in the built documents. +#keep_warnings = False + +# If true, `todo` and `todoList` produce output, else they produce nothing. +todo_include_todos = False + +primary_domain = 'c' +highlight_language = 'none' + +# -- Options for HTML output ---------------------------------------------- + +# The theme to use for HTML and HTML Help pages. See the documentation for +# a list of builtin themes. + +# The Read the Docs theme is available from +# - https://github.com/snide/sphinx_rtd_theme +# - https://pypi.python.org/pypi/sphinx_rtd_theme +# - python-sphinx-rtd-theme package (on Debian) +try: + import sphinx_rtd_theme + html_theme = 'sphinx_rtd_theme' + html_theme_path = [sphinx_rtd_theme.get_html_theme_path()] +except ImportError: + sys.stderr.write('Warning: The Sphinx \'sphinx_rtd_theme\' HTML theme was not found. Make sure you have the theme installed to produce pretty HTML output. Falling back to the default theme.\n') + +# Theme options are theme-specific and customize the look and feel of a theme +# further. For a list of options available for each theme, see the +# documentation. +#html_theme_options = {} + +# Add any paths that contain custom themes here, relative to this directory. +#html_theme_path = [] + +# The name for this set of Sphinx documents. If None, it defaults to +# "<project> v<release> documentation". +#html_title = None + +# A shorter title for the navigation bar. Default is the same as html_title. +#html_short_title = None + +# The name of an image file (relative to this directory) to place at the top +# of the sidebar. +html_logo = '../tools/logos/u-boot_logo.svg' + +# The name of an image file (within the static path) to use as favicon of the +# docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32 +# pixels large. +#html_favicon = None + +# Add any paths that contain custom static files (such as style sheets) here, +# relative to this directory. They are copied after the builtin static files, +# so a file named "default.css" will overwrite the builtin "default.css". + +html_static_path = ['sphinx-static'] + +html_context = { + 'css_files': [ + '_static/theme_overrides.css', + ], +} + +# Add any extra paths that contain custom files (such as robots.txt or +# .htaccess) here, relative to this directory. These files are copied +# directly to the root of the documentation. +#html_extra_path = [] + +# If not '', a 'Last updated on:' timestamp is inserted at every page bottom, +# using the given strftime format. +#html_last_updated_fmt = '%b %d, %Y' + +# If true, SmartyPants will be used to convert quotes and dashes to +# typographically correct entities. +html_use_smartypants = False + +# Custom sidebar templates, maps document names to template names. +#html_sidebars = {} + +# Additional templates that should be rendered to pages, maps page names to +# template names. +#html_additional_pages = {} + +# If false, no module index is generated. +#html_domain_indices = True + +# If false, no index is generated. +#html_use_index = True + +# If true, the index is split into individual pages for each letter. +#html_split_index = False + +# If true, links to the reST sources are added to the pages. +#html_show_sourcelink = True + +# If true, "Created using Sphinx" is shown in the HTML footer. Default is True. +#html_show_sphinx = True + +# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True. +#html_show_copyright = True + +# If true, an OpenSearch description file will be output, and all pages will +# contain a <link> tag referring to it. The value of this option must be the +# base URL from which the finished HTML is served. +#html_use_opensearch = '' + +# This is the file name suffix for HTML files (e.g. ".xhtml"). +#html_file_suffix = None + +# Language to be used for generating the HTML full-text search index. +# Sphinx supports the following languages: +# 'da', 'de', 'en', 'es', 'fi', 'fr', 'h', 'it', 'ja' +# 'nl', 'no', 'pt', 'ro', 'r', 'sv', 'tr' +#html_search_language = 'en' + +# A dictionary with options for the search language support, empty by default. +# Now only 'ja' uses this config value +#html_search_options = {'type': 'default'} + +# The name of a javascript file (relative to the configuration directory) that +# implements a search results scorer. If empty, the default will be used. +#html_search_scorer = 'scorer.js' + +# Output file base name for HTML help builder. +htmlhelp_basename = 'TheUBootdoc' + +# -- Options for LaTeX output --------------------------------------------- + +latex_elements = { +# The paper size ('letterpaper' or 'a4paper'). +'papersize': 'a4paper', + +# The font size ('10pt', '11pt' or '12pt'). +'pointsize': '11pt', + +# Latex figure (float) alignment +#'figure_align': 'htbp', + +# Don't mangle with UTF-8 chars +'inputenc': '', +'utf8extra': '', + +# Additional stuff for the LaTeX preamble. + 'preamble': ''' + % Use some font with UTF-8 support with XeLaTeX + \\usepackage{fontspec} + \\setsansfont{DejaVu Sans} + \\setromanfont{DejaVu Serif} + \\setmonofont{DejaVu Sans Mono} + ''' +} + +# At least one book (translations) may have Asian characters +# with are only displayed if xeCJK is used + +cjk_cmd = check_output(['fc-list', '--format="%{family[0]}\n"']).decode('utf-8', 'ignore') +if cjk_cmd.find("Noto Sans CJK SC") >= 0: + print ("enabling CJK for LaTeX builder") + latex_elements['preamble'] += ''' + % This is needed for translations + \\usepackage{xeCJK} + \\setCJKmainfont{Noto Sans CJK SC} + ''' + +# Fix reference escape troubles with Sphinx 1.4.x +if major == 1 and minor > 3: + latex_elements['preamble'] += '\\renewcommand*{\\DUrole}[2]{ #2 }\n' + +if major == 1 and minor <= 4: + latex_elements['preamble'] += '\\usepackage[margin=0.5in, top=1in, bottom=1in]{geometry}' +elif major == 1 and (minor > 5 or (minor == 5 and patch >= 3)): + latex_elements['sphinxsetup'] = 'hmargin=0.5in, vmargin=1in' + latex_elements['preamble'] += '\\fvset{fontsize=auto}\n' + +# Customize notice background colors on Sphinx < 1.6: +if major == 1 and minor < 6: + latex_elements['preamble'] += ''' + \\usepackage{ifthen} + + % Put notes in color and let them be inside a table + \\definecolor{NoteColor}{RGB}{204,255,255} + \\definecolor{WarningColor}{RGB}{255,204,204} + \\definecolor{AttentionColor}{RGB}{255,255,204} + \\definecolor{ImportantColor}{RGB}{192,255,204} + \\definecolor{OtherColor}{RGB}{204,204,204} + \\newlength{\\mynoticelength} + \\makeatletter\\newenvironment{coloredbox}[1]{% + \\setlength{\\fboxrule}{1pt} + \\setlength{\\fboxsep}{7pt} + \\setlength{\\mynoticelength}{\\linewidth} + \\addtolength{\\mynoticelength}{-2\\fboxsep} + \\addtolength{\\mynoticelength}{-2\\fboxrule} + \\begin{lrbox}{\\@tempboxa}\\begin{minipage}{\\mynoticelength}}{\\end{minipage}\\end{lrbox}% + \\ifthenelse% + {\\equal{\\py@noticetype}{note}}% + {\\colorbox{NoteColor}{\\usebox{\\@tempboxa}}}% + {% + \\ifthenelse% + {\\equal{\\py@noticetype}{warning}}% + {\\colorbox{WarningColor}{\\usebox{\\@tempboxa}}}% + {% + \\ifthenelse% + {\\equal{\\py@noticetype}{attention}}% + {\\colorbox{AttentionColor}{\\usebox{\\@tempboxa}}}% + {% + \\ifthenelse% + {\\equal{\\py@noticetype}{important}}% + {\\colorbox{ImportantColor}{\\usebox{\\@tempboxa}}}% + {\\colorbox{OtherColor}{\\usebox{\\@tempboxa}}}% + }% + }% + }% + }\\makeatother + + \\makeatletter + \\renewenvironment{notice}[2]{% + \\def\\py@noticetype{#1} + \\begin{coloredbox}{#1} + \\bf\\it + \\par\\strong{#2} + \\csname py@noticestart@#1\\endcsname + } + { + \\csname py@noticeend@\\py@noticetype\\endcsname + \\end{coloredbox} + } + \\makeatother + + ''' + +# With Sphinx 1.6, it is possible to change the Bg color directly +# by using: +# \definecolor{sphinxnoteBgColor}{RGB}{204,255,255} +# \definecolor{sphinxwarningBgColor}{RGB}{255,204,204} +# \definecolor{sphinxattentionBgColor}{RGB}{255,255,204} +# \definecolor{sphinximportantBgColor}{RGB}{192,255,204} +# +# However, it require to use sphinx heavy box with: +# +# \renewenvironment{sphinxlightbox} {% +# \\begin{sphinxheavybox} +# } +# \\end{sphinxheavybox} +# } +# +# Unfortunately, the implementation is buggy: if a note is inside a +# table, it isn't displayed well. So, for now, let's use boring +# black and white notes. + +# Grouping the document tree into LaTeX files. List of tuples +# (source start file, target name, title, +# author, documentclass [howto, manual, or own class]). +# Sorted in alphabetical order +latex_documents = [ + ('index', 'u-boot-hacker-manual.tex', 'U-Boot Hacker Manual', + 'The U-Boot development community', 'manual'), +] + +# Add all other index files from Documentation/ subdirectories +for fn in os.listdir('.'): + doc = os.path.join(fn, "index") + if os.path.exists(doc + ".rst"): + has = False + for l in latex_documents: + if l[0] == doc: + has = True + break + if not has: + latex_documents.append((doc, fn + '.tex', + 'U-Boot %s Documentation' % fn.capitalize(), + 'The U-Boot development community', + 'manual')) + +# The name of an image file (relative to this directory) to place at the top of +# the title page. +#latex_logo = None + +# For "manual" documents, if this is true, then toplevel headings are parts, +# not chapters. +#latex_use_parts = False + +# If true, show page references after internal links. +#latex_show_pagerefs = False + +# If true, show URL addresses after external links. +#latex_show_urls = False + +# Documents to append as an appendix to all manuals. +#latex_appendices = [] + +# If false, no module index is generated. +#latex_domain_indices = True + + +# -- Options for manual page output --------------------------------------- + +# One entry per manual page. List of tuples +# (source start file, name, description, authors, manual section). +man_pages = [ + (master_doc, 'dasuboot', 'The U-Boot Documentation', + [author], 1) +] + +# If true, show URL addresses after external links. +#man_show_urls = False + + +# -- Options for Texinfo output ------------------------------------------- + +# Grouping the document tree into Texinfo files. List of tuples +# (source start file, target name, title, author, +# dir menu entry, description, category) +texinfo_documents = [ + (master_doc, 'DasUBoot', 'The U-Boot Documentation', + author, 'DasUBoot', 'One line description of project.', + 'Miscellaneous'), +] + +# Documents to append as an appendix to all manuals. +#texinfo_appendices = [] + +# If false, no module index is generated. +#texinfo_domain_indices = True + +# How to display URL addresses: 'footnote', 'no', or 'inline'. +#texinfo_show_urls = 'footnote' + +# If true, do not generate a @detailmenu in the "Top" node's menu. +#texinfo_no_detailmenu = False + + +# -- Options for Epub output ---------------------------------------------- + +# Bibliographic Dublin Core info. +epub_title = project +epub_author = author +epub_publisher = author +epub_copyright = copyright + +# The basename for the epub file. It defaults to the project name. +#epub_basename = project + +# The HTML theme for the epub output. Since the default themes are not +# optimized for small screen space, using the same theme for HTML and epub +# output is usually not wise. This defaults to 'epub', a theme designed to save +# visual space. +#epub_theme = 'epub' + +# The language of the text. It defaults to the language option +# or 'en' if the language is not set. +#epub_language = '' + +# The scheme of the identifier. Typical schemes are ISBN or URL. +#epub_scheme = '' + +# The unique identifier of the text. This can be a ISBN number +# or the project homepage. +#epub_identifier = '' + +# A unique identification for the text. +#epub_uid = '' + +# A tuple containing the cover image and cover page html template filenames. +#epub_cover = () + +# A sequence of (type, uri, title) tuples for the guide element of content.opf. +#epub_guide = () + +# HTML files that should be inserted before the pages created by sphinx. +# The format is a list of tuples containing the path and title. +#epub_pre_files = [] + +# HTML files that should be inserted after the pages created by sphinx. +# The format is a list of tuples containing the path and title. +#epub_post_files = [] + +# A list of files that should not be packed into the epub file. +epub_exclude_files = ['search.html'] + +# The depth of the table of contents in toc.ncx. +#epub_tocdepth = 3 + +# Allow duplicate toc entries. +#epub_tocdup = True + +# Choose between 'default' and 'includehidden'. +#epub_tocscope = 'default' + +# Fix unsupported image types using the Pillow. +#epub_fix_images = False + +# Scale large images. +#epub_max_image_width = 0 + +# How to display URL addresses: 'footnote', 'no', or 'inline'. +#epub_show_urls = 'inline' + +# If false, no index is generated. +#epub_use_index = True + +#======= +# rst2pdf +# +# Grouping the document tree into PDF files. List of tuples +# (source start file, target name, title, author, options). +# +# See the Sphinx chapter of https://ralsina.me/static/manual.pdf +# +# FIXME: Do not add the index file here; the result will be too big. Adding +# multiple PDF files here actually tries to get the cross-referencing right +# *between* PDF files. +pdf_documents = [ + ('uboot-documentation', u'U-Boot', u'U-Boot', u'J. Random Bozo'), +] + +# kernel-doc extension configuration for running Sphinx directly (e.g. by Read +# the Docs). In a normal build, these are supplied from the Makefile via command +# line arguments. +kerneldoc_bin = '../scripts/kernel-doc' +kerneldoc_srctree = '..' + +# ------------------------------------------------------------------------------ +# Since loadConfig overwrites settings from the global namespace, it has to be +# the last statement in the conf.py file +# ------------------------------------------------------------------------------ +loadConfig(globals()) diff --git a/roms/u-boot/doc/develop/coccinelle.rst b/roms/u-boot/doc/develop/coccinelle.rst new file mode 100644 index 000000000..70274c3f5 --- /dev/null +++ b/roms/u-boot/doc/develop/coccinelle.rst @@ -0,0 +1,505 @@ +.. Copyright 2010 Nicolas Palix <npalix@diku.dk> +.. Copyright 2010 Julia Lawall <julia@diku.dk> +.. Copyright 2010 Gilles Muller <Gilles.Muller@lip6.fr> + +.. highlight:: none + +.. _devtools_coccinelle: + +Coccinelle +========== + +Coccinelle is a tool for pattern matching and text transformation that has +many uses in kernel development, including the application of complex, +tree-wide patches and detection of problematic programming patterns. + +Getting Coccinelle +------------------ + +The semantic patches included in the kernel use features and options +which are provided by Coccinelle version 1.0.0-rc11 and above. +Using earlier versions will fail as the option names used by +the Coccinelle files and coccicheck have been updated. + +Coccinelle is available through the package manager +of many distributions, e.g. : + + - Debian + - Fedora + - Ubuntu + - OpenSUSE + - Arch Linux + - NetBSD + - FreeBSD + +Some distribution packages are obsolete and it is recommended +to use the latest version released from the Coccinelle homepage at +http://coccinelle.lip6.fr/ + +Or from Github at: + +https://github.com/coccinelle/coccinelle + +Once you have it, run the following commands:: + + ./autogen + ./configure + make + +as a regular user, and install it with:: + + sudo make install + +More detailed installation instructions to build from source can be +found at: + +https://github.com/coccinelle/coccinelle/blob/master/install.txt + +Supplemental documentation +-------------------------- + +For supplemental documentation refer to the wiki: + +https://bottest.wiki.kernel.org/coccicheck + +The wiki documentation always refers to the linux-next version of the script. + +For Semantic Patch Language(SmPL) grammar documentation refer to: + +http://coccinelle.lip6.fr/documentation.php + +Using Coccinelle on the Linux kernel +------------------------------------ + +A Coccinelle-specific target is defined in the top level +Makefile. This target is named ``coccicheck`` and calls the ``coccicheck`` +front-end in the ``scripts`` directory. + +Four basic modes are defined: ``patch``, ``report``, ``context``, and +``org``. The mode to use is specified by setting the MODE variable with +``MODE=<mode>``. + +- ``patch`` proposes a fix, when possible. + +- ``report`` generates a list in the following format: + file:line:column-column: message + +- ``context`` highlights lines of interest and their context in a + diff-like style.Lines of interest are indicated with ``-``. + +- ``org`` generates a report in the Org mode format of Emacs. + +Note that not all semantic patches implement all modes. For easy use +of Coccinelle, the default mode is "report". + +Two other modes provide some common combinations of these modes. + +- ``chain`` tries the previous modes in the order above until one succeeds. + +- ``rep+ctxt`` runs successively the report mode and the context mode. + It should be used with the C option (described later) + which checks the code on a file basis. + +Examples +~~~~~~~~ + +To make a report for every semantic patch, run the following command:: + + make coccicheck MODE=report + +To produce patches, run:: + + make coccicheck MODE=patch + + +The coccicheck target applies every semantic patch available in the +sub-directories of ``scripts/coccinelle`` to the entire Linux kernel. + +For each semantic patch, a commit message is proposed. It gives a +description of the problem being checked by the semantic patch, and +includes a reference to Coccinelle. + +As any static code analyzer, Coccinelle produces false +positives. Thus, reports must be carefully checked, and patches +reviewed. + +To enable verbose messages set the V= variable, for example:: + + make coccicheck MODE=report V=1 + +Coccinelle parallelization +-------------------------- + +By default, coccicheck tries to run as parallel as possible. To change +the parallelism, set the J= variable. For example, to run across 4 CPUs:: + + make coccicheck MODE=report J=4 + +As of Coccinelle 1.0.2 Coccinelle uses Ocaml parmap for parallelization, +if support for this is detected you will benefit from parmap parallelization. + +When parmap is enabled coccicheck will enable dynamic load balancing by using +``--chunksize 1`` argument, this ensures we keep feeding threads with work +one by one, so that we avoid the situation where most work gets done by only +a few threads. With dynamic load balancing, if a thread finishes early we keep +feeding it more work. + +When parmap is enabled, if an error occurs in Coccinelle, this error +value is propagated back, the return value of the ``make coccicheck`` +captures this return value. + +Using Coccinelle with a single semantic patch +--------------------------------------------- + +The optional make variable COCCI can be used to check a single +semantic patch. In that case, the variable must be initialized with +the name of the semantic patch to apply. + +For instance:: + + make coccicheck COCCI=<my_SP.cocci> MODE=patch + +or:: + + make coccicheck COCCI=<my_SP.cocci> MODE=report + + +Controlling Which Files are Processed by Coccinelle +--------------------------------------------------- + +By default the entire kernel source tree is checked. + +To apply Coccinelle to a specific directory, ``M=`` can be used. +For example, to check drivers/net/wireless/ one may write:: + + make coccicheck M=drivers/net/wireless/ + +To apply Coccinelle on a file basis, instead of a directory basis, the +following command may be used:: + + make C=1 CHECK="scripts/coccicheck" + +To check only newly edited code, use the value 2 for the C flag, i.e.:: + + make C=2 CHECK="scripts/coccicheck" + +In these modes, which works on a file basis, there is no information +about semantic patches displayed, and no commit message proposed. + +This runs every semantic patch in scripts/coccinelle by default. The +COCCI variable may additionally be used to only apply a single +semantic patch as shown in the previous section. + +The "report" mode is the default. You can select another one with the +MODE variable explained above. + +Debugging Coccinelle SmPL patches +--------------------------------- + +Using coccicheck is best as it provides in the spatch command line +include options matching the options used when we compile the kernel. +You can learn what these options are by using V=1, you could then +manually run Coccinelle with debug options added. + +Alternatively you can debug running Coccinelle against SmPL patches +by asking for stderr to be redirected to stderr, by default stderr +is redirected to /dev/null, if you'd like to capture stderr you +can specify the ``DEBUG_FILE="file.txt"`` option to coccicheck. For +instance:: + + rm -f cocci.err + make coccicheck COCCI=scripts/coccinelle/free/kfree.cocci MODE=report DEBUG_FILE=cocci.err + cat cocci.err + +You can use SPFLAGS to add debugging flags, for instance you may want to +add both --profile --show-trying to SPFLAGS when debugging. For instance +you may want to use:: + + rm -f err.log + export COCCI=scripts/coccinelle/misc/irqf_oneshot.cocci + make coccicheck DEBUG_FILE="err.log" MODE=report SPFLAGS="--profile --show-trying" M=./drivers/mfd/arizona-irq.c + +err.log will now have the profiling information, while stdout will +provide some progress information as Coccinelle moves forward with +work. + +DEBUG_FILE support is only supported when using coccinelle >= 1.0.2. + +.cocciconfig support +-------------------- + +Coccinelle supports reading .cocciconfig for default Coccinelle options that +should be used every time spatch is spawned, the order of precedence for +variables for .cocciconfig is as follows: + +- Your current user's home directory is processed first +- Your directory from which spatch is called is processed next +- The directory provided with the --dir option is processed last, if used + +Since coccicheck runs through make, it naturally runs from the kernel +proper dir, as such the second rule above would be implied for picking up a +.cocciconfig when using ``make coccicheck``. + +``make coccicheck`` also supports using M= targets. If you do not supply +any M= target, it is assumed you want to target the entire kernel. +The kernel coccicheck script has:: + + if [ "$KBUILD_EXTMOD" = "" ] ; then + OPTIONS="--dir $srctree $COCCIINCLUDE" + else + OPTIONS="--dir $KBUILD_EXTMOD $COCCIINCLUDE" + fi + +KBUILD_EXTMOD is set when an explicit target with M= is used. For both cases +the spatch --dir argument is used, as such third rule applies when whether M= +is used or not, and when M= is used the target directory can have its own +.cocciconfig file. When M= is not passed as an argument to coccicheck the +target directory is the same as the directory from where spatch was called. + +If not using the kernel's coccicheck target, keep the above precedence +order logic of .cocciconfig reading. If using the kernel's coccicheck target, +override any of the kernel's .coccicheck's settings using SPFLAGS. + +We help Coccinelle when used against Linux with a set of sensible defaults +options for Linux with our own Linux .cocciconfig. This hints to coccinelle +git can be used for ``git grep`` queries over coccigrep. A timeout of 200 +seconds should suffice for now. + +The options picked up by coccinelle when reading a .cocciconfig do not appear +as arguments to spatch processes running on your system, to confirm what +options will be used by Coccinelle run:: + + spatch --print-options-only + +You can override with your own preferred index option by using SPFLAGS. Take +note that when there are conflicting options Coccinelle takes precedence for +the last options passed. Using .cocciconfig is possible to use idutils, however +given the order of precedence followed by Coccinelle, since the kernel now +carries its own .cocciconfig, you will need to use SPFLAGS to use idutils if +desired. See below section "Additional flags" for more details on how to use +idutils. + +Additional flags +---------------- + +Additional flags can be passed to spatch through the SPFLAGS +variable. This works as Coccinelle respects the last flags +given to it when options are in conflict. :: + + make SPFLAGS=--use-glimpse coccicheck + +Coccinelle supports idutils as well but requires coccinelle >= 1.0.6. +When no ID file is specified coccinelle assumes your ID database file +is in the file .id-utils.index on the top level of the kernel, coccinelle +carries a script scripts/idutils_index.sh which creates the database with:: + + mkid -i C --output .id-utils.index + +If you have another database filename you can also just symlink with this +name. :: + + make SPFLAGS=--use-idutils coccicheck + +Alternatively you can specify the database filename explicitly, for +instance:: + + make SPFLAGS="--use-idutils /full-path/to/ID" coccicheck + +See ``spatch --help`` to learn more about spatch options. + +Note that the ``--use-glimpse`` and ``--use-idutils`` options +require external tools for indexing the code. None of them is +thus active by default. However, by indexing the code with +one of these tools, and according to the cocci file used, +spatch could proceed the entire code base more quickly. + +SmPL patch specific options +--------------------------- + +SmPL patches can have their own requirements for options passed +to Coccinelle. SmPL patch specific options can be provided by +providing them at the top of the SmPL patch, for instance:: + + // Options: --no-includes --include-headers + +SmPL patch Coccinelle requirements +---------------------------------- + +As Coccinelle features get added some more advanced SmPL patches +may require newer versions of Coccinelle. If an SmPL patch requires +at least a version of Coccinelle, this can be specified as follows, +as an example if requiring at least Coccinelle >= 1.0.5:: + + // Requires: 1.0.5 + +Proposing new semantic patches +------------------------------ + +New semantic patches can be proposed and submitted by kernel +developers. For sake of clarity, they should be organized in the +sub-directories of ``scripts/coccinelle/``. + + +Detailed description of the ``report`` mode +------------------------------------------- + +``report`` generates a list in the following format:: + + file:line:column-column: message + +Example +~~~~~~~ + +Running:: + + make coccicheck MODE=report COCCI=scripts/coccinelle/api/err_cast.cocci + +will execute the following part of the SmPL script:: + + <smpl> + @r depends on !context && !patch && (org || report)@ + expression x; + position p; + @@ + + ERR_PTR@p(PTR_ERR(x)) + + @script:python depends on report@ + p << r.p; + x << r.x; + @@ + + msg="ERR_CAST can be used with %s" % (x) + coccilib.report.print_report(p[0], msg) + </smpl> + +This SmPL excerpt generates entries on the standard output, as +illustrated below:: + + /home/user/linux/crypto/ctr.c:188:9-16: ERR_CAST can be used with alg + /home/user/linux/crypto/authenc.c:619:9-16: ERR_CAST can be used with auth + /home/user/linux/crypto/xts.c:227:9-16: ERR_CAST can be used with alg + + +Detailed description of the ``patch`` mode +------------------------------------------ + +When the ``patch`` mode is available, it proposes a fix for each problem +identified. + +Example +~~~~~~~ + +Running:: + + make coccicheck MODE=patch COCCI=scripts/coccinelle/api/err_cast.cocci + +will execute the following part of the SmPL script:: + + <smpl> + @ depends on !context && patch && !org && !report @ + expression x; + @@ + + - ERR_PTR(PTR_ERR(x)) + + ERR_CAST(x) + </smpl> + +This SmPL excerpt generates patch hunks on the standard output, as +illustrated below:: + + diff -u -p a/crypto/ctr.c b/crypto/ctr.c + --- a/crypto/ctr.c 2010-05-26 10:49:38.000000000 +0200 + +++ b/crypto/ctr.c 2010-06-03 23:44:49.000000000 +0200 + @@ -185,7 +185,7 @@ static struct crypto_instance *crypto_ct + alg = crypto_attr_alg(tb[1], CRYPTO_ALG_TYPE_CIPHER, + CRYPTO_ALG_TYPE_MASK); + if (IS_ERR(alg)) + - return ERR_PTR(PTR_ERR(alg)); + + return ERR_CAST(alg); + + /* Block size must be >= 4 bytes. */ + err = -EINVAL; + +Detailed description of the ``context`` mode +-------------------------------------------- + +``context`` highlights lines of interest and their context +in a diff-like style. + + **NOTE**: The diff-like output generated is NOT an applicable patch. The + intent of the ``context`` mode is to highlight the important lines + (annotated with minus, ``-``) and gives some surrounding context + lines around. This output can be used with the diff mode of + Emacs to review the code. + +Example +~~~~~~~ + +Running:: + + make coccicheck MODE=context COCCI=scripts/coccinelle/api/err_cast.cocci + +will execute the following part of the SmPL script:: + + <smpl> + @ depends on context && !patch && !org && !report@ + expression x; + @@ + + * ERR_PTR(PTR_ERR(x)) + </smpl> + +This SmPL excerpt generates diff hunks on the standard output, as +illustrated below:: + + diff -u -p /home/user/linux/crypto/ctr.c /tmp/nothing + --- /home/user/linux/crypto/ctr.c 2010-05-26 10:49:38.000000000 +0200 + +++ /tmp/nothing + @@ -185,7 +185,6 @@ static struct crypto_instance *crypto_ct + alg = crypto_attr_alg(tb[1], CRYPTO_ALG_TYPE_CIPHER, + CRYPTO_ALG_TYPE_MASK); + if (IS_ERR(alg)) + - return ERR_PTR(PTR_ERR(alg)); + + /* Block size must be >= 4 bytes. */ + err = -EINVAL; + +Detailed description of the ``org`` mode +---------------------------------------- + +``org`` generates a report in the Org mode format of Emacs. + +Example +~~~~~~~ + +Running:: + + make coccicheck MODE=org COCCI=scripts/coccinelle/api/err_cast.cocci + +will execute the following part of the SmPL script:: + + <smpl> + @r depends on !context && !patch && (org || report)@ + expression x; + position p; + @@ + + ERR_PTR@p(PTR_ERR(x)) + + @script:python depends on org@ + p << r.p; + x << r.x; + @@ + + msg="ERR_CAST can be used with %s" % (x) + msg_safe=msg.replace("[","@(").replace("]",")") + coccilib.org.print_todo(p[0], msg_safe) + </smpl> + +This SmPL excerpt generates Org entries on the standard output, as +illustrated below:: + + * TODO [[view:/home/user/linux/crypto/ctr.c::face=ovl-face1::linb=188::colb=9::cole=16][ERR_CAST can be used with alg]] + * TODO [[view:/home/user/linux/crypto/authenc.c::face=ovl-face1::linb=619::colb=9::cole=16][ERR_CAST can be used with auth]] + * TODO [[view:/home/user/linux/crypto/xts.c::face=ovl-face1::linb=227::colb=9::cole=16][ERR_CAST can be used with alg]] diff --git a/roms/u-boot/doc/develop/commands.rst b/roms/u-boot/doc/develop/commands.rst new file mode 100644 index 000000000..c72d1b0aa --- /dev/null +++ b/roms/u-boot/doc/develop/commands.rst @@ -0,0 +1,226 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +Implementing shell commands +=========================== + +Command definition +------------------ + +Commands are added to U-Boot by creating a new command structure. +This is done by first including command.h, then using the U_BOOT_CMD() or the +U_BOOT_CMD_COMPLETE macro to fill in a struct cmd_tbl structure. + +.. code-block:: c + + U_BOOT_CMD(name, maxargs, repeatable, command, "usage", "help") + U_BOOT_CMD_COMPLETE(name, maxargs, repeatable, command, "usage, "help", comp) + +name + The name of the command. This is **not** a string. + +maxargs + The maximum number of arguments this function takes including + the command itself. + +repeatable + Either 0 or 1 to indicate if autorepeat is allowed. + +command + Pointer to the command function. This is the function that is + called when the command is issued. + +usage + Short description. This is a string. + +help + Long description. This is a string. The long description is + only available if CONFIG_SYS_LONGHELP is defined. + +comp + Pointer to the completion function. May be NULL. + This function is called if the user hits the TAB key while + entering the command arguments to complete the entry. Command + completion is only available if CONFIG_AUTO_COMPLETE is defined. + +Sub-command definition +---------------------- + +Likewise an array of struct cmd_tbl holding sub-commands can be created using +either of the following macros: + +.. code-block:: c + + U_BOOT_CMD_MKENT(name, maxargs, repeatable, command, "usage", "help") + U_BOOT_CMD_MKENTCOMPLETE(name, maxargs, repeatable, command, "usage, "help", comp) + +This table has to be evaluated in the command function of the main command, e.g. + +.. code-block:: c + + static struct cmd_tbl cmd_sub[] = { + U_BOOT_CMD_MKENT(foo, CONFIG_SYS_MAXARGS, 1, do_foo, "", ""), + U_BOOT_CMD_MKENT(bar, CONFIG_SYS_MAXARGS, 1, do_bar, "", ""), + }; + + static int do_cmd(struct cmd_tbl *cmdtp, int flag, int argc, char *const argv[]) + { + struct cmd_tbl *cp; + + if (argc < 2) + return CMD_RET_USAGE; + + /* drop sub-command argument */ + argc--; + argv++; + + cp = find_cmd_tbl(argv[0], cmd_ut_sub, ARRAY_SIZE(cmd_sub)); + + if (cp) + return cp->cmd(cmdtp, flag, argc, argv); + + return CMD_RET_USAGE; + } + +Command function +---------------- + +The command function pointer has to be of type + +.. code-block:: c + + int (*cmd)(struct cmd_tbl *cmdtp, int flag, int argc, const char *argv[]); + +cmdtp + Table entry describing the command (see above). + +flag + A bitmap which may contain the following bits + + * CMD_FLAG_REPEAT - The last command is repeated. + * CMD_FLAG_BOOTD - The command is called by the bootd command. + * CMD_FLAG_ENV - The command is called by the run command. + +argc + Number of arguments including the command. + +argv + Arguments. + +Allowable return value are: + +CMD_RET_SUCCESS + The command was successfully executed. + +CMD_RET_FAILURE + The command failed. + +CMD_RET_USAGE + The command was called with invalid parameters. This value + leads to the display of the usage string. + +Completion function +------------------- + +The completion function pointer has to be of type + +.. code-block:: c + + int (*complete)(int argc, char *const argv[], char last_char, + int maxv, char *cmdv[]); + +argc + Number of arguments including the command. + +argv + Arguments. + +last_char + The last character in the command line buffer. + +maxv + Maximum number of possible completions that may be returned by + the function. + +cmdv + Used to return possible values for the last argument. The last + possible completion must be followed by NULL. + +The function returns the number of possible completions (without the terminating +NULL value). + +Behind the scene +---------------- + +The structure created is named with a special prefix and placed by +the linker in a special section using the linker lists mechanism +(see include/linker_lists.h) + +This makes it possible for the final link to extract all commands +compiled into any object code and construct a static array so the +command array can be iterated over using the linker lists macros. + +The linker lists feature ensures that the linker does not discard +these symbols when linking full U-Boot even though they are not +referenced in the source code as such. + +If a new board is defined do not forget to define the command section +by writing in u-boot.lds ($(srctree)/board/boardname/u-boot.lds) these +3 lines: + +.. code-block:: c + + .u_boot_list : { + KEEP(*(SORT(.u_boot_list*))); + } + +Writing tests +------------- + +All new commands should have tests. Tests for existing commands are very +welcome. + +It is fairly easy to write a test for a command. Enable it in sandbox, and +then add code that runs the command and checks the output. + +Here is an example: + +.. code-block:: c + + /* Test 'acpi items' command */ + static int dm_test_acpi_cmd_items(struct unit_test_state *uts) + { + struct acpi_ctx ctx; + void *buf; + + buf = malloc(BUF_SIZE); + ut_assertnonnull(buf); + + ctx.current = buf; + ut_assertok(acpi_fill_ssdt(&ctx)); + console_record_reset(); + run_command("acpi items", 0); + ut_assert_nextline("dev 'acpi-test', type 1, size 2"); + ut_assert_nextline("dev 'acpi-test2', type 1, size 2"); + ut_assert_console_end(); + + ctx.current = buf; + ut_assertok(acpi_inject_dsdt(&ctx)); + console_record_reset(); + run_command("acpi items", 0); + ut_assert_nextline("dev 'acpi-test', type 2, size 2"); + ut_assert_nextline("dev 'acpi-test2', type 2, size 2"); + ut_assert_console_end(); + + console_record_reset(); + run_command("acpi items -d", 0); + ut_assert_nextline("dev 'acpi-test', type 2, size 2"); + ut_assert_nextlines_are_dump(2); + ut_assert_nextline("%s", ""); + ut_assert_nextline("dev 'acpi-test2', type 2, size 2"); + ut_assert_nextlines_are_dump(2); + ut_assert_nextline("%s", ""); + ut_assert_console_end(); + + return 0; + } + DM_TEST(dm_test_acpi_cmd_items, UT_TESTF_SCAN_PDATA | UT_TESTF_SCAN_FDT); diff --git a/roms/u-boot/doc/develop/crash_dumps.rst b/roms/u-boot/doc/develop/crash_dumps.rst new file mode 100644 index 000000000..85030b4e3 --- /dev/null +++ b/roms/u-boot/doc/develop/crash_dumps.rst @@ -0,0 +1,124 @@ +.. SPDX-License-Identifier: GPL-2.0+ +.. Copyright (c) 2020 Heinrich Schuchardt + +Analyzing crash dumps +===================== + +When the CPU detects an instruction that it cannot execute it raises an +interrupt. U-Boot then writes a crash dump. This chapter describes how such +dump can be analyzed. + +Creating a crash dump voluntarily +--------------------------------- + +For describing the analysis of a crash dump we need an example. U-Boot comes +with a command 'exception' that comes in handy here. The command is enabled +by:: + + CONFIG_CMD_EXCEPTION=y + +The example output below was recorded when running qemu\_arm64\_defconfig on +QEMU:: + + => exception undefined + "Synchronous Abort" handler, esr 0x02000000 + elr: 00000000000101fc lr : 00000000000214ec (reloc) + elr: 000000007ff291fc lr : 000000007ff3a4ec + x0 : 000000007ffbd7f8 x1 : 0000000000000000 + x2 : 0000000000000001 x3 : 000000007eedce18 + x4 : 000000007ff291fc x5 : 000000007eedce50 + x6 : 0000000000000064 x7 : 000000007eedce10 + x8 : 0000000000000000 x9 : 0000000000000004 + x10: 6db6db6db6db6db7 x11: 000000000000000d + x12: 0000000000000006 x13: 000000000001869f + x14: 000000007edd7dc0 x15: 0000000000000002 + x16: 000000007ff291fc x17: 0000000000000000 + x18: 000000007eed8dc0 x19: 0000000000000000 + x20: 000000007ffbd7f8 x21: 0000000000000000 + x22: 000000007eedce10 x23: 0000000000000002 + x24: 000000007ffd4c80 x25: 0000000000000000 + x26: 0000000000000000 x27: 0000000000000000 + x28: 000000007eedce70 x29: 000000007edd7b40 + + Code: b00003c0 912ad000 940029d6 17ffff52 (e7f7defb) + Resetting CPU ... + + resetting ... + +The first line provides us with the type of interrupt that occurred. +On ARMv8 a synchronous abort is an exception thrown when hitting an unallocated +instruction. The exception syndrome register ESR register contains information +describing the reason for the exception. Bit 25 set here indicates that a 32 bit +instruction led to the exception. + +The second line provides the contents of the elr and the lr register after +subtracting the relocation offset. - U-Boot relocates itself after being +loaded. - The relocation offset can also be displayed using the bdinfo command. + +After the contents of the registers we get a line indicating the machine +code of the instructions preceding the crash and in parentheses the instruction +leading to the dump. + +Analyzing the code location +--------------------------- + +We can convert the instructions in the line starting with 'Code:' into mnemonics +using the objdump command. To make things easier scripts/decodecode is +supplied:: + + $echo 'Code: b00003c0 912ad000 940029d6 17ffff52 (e7f7defb)' | \ + CROSS_COMPILE=aarch64-linux-gnu- ARCH=arm64 scripts/decodecode + Code: b00003c0 912ad000 940029d6 17ffff52 (e7f7defb) + All code + ======== + 0: b00003c0 adrp x0, 0x79000 + 4: 912ad000 add x0, x0, #0xab4 + 8: 940029d6 bl 0xa760 + c: 17ffff52 b 0xfffffffffffffd54 + 10:* e7f7defb .inst 0xe7f7defb ; undefined <-- trapping instruction + + Code starting with the faulting instruction + =========================================== + 0: e7f7defb .inst 0xe7f7defb ; undefined + +Now lets use the locations provided by the elr and lr registers after +subtracting the relocation offset to find out where in the code the crash +occurred and from where it was invoked. + +File u-boot.map contains the memory layout of the U-Boot binary. Here we find +these lines:: + + .text.do_undefined + 0x00000000000101fc 0xc cmd/built-in.o + .text.exception_complete + 0x0000000000010208 0x90 cmd/built-in.o + ... + .text.cmd_process + 0x00000000000213b8 0x164 common/built-in.o + 0x00000000000213b8 cmd_process + .text.cmd_process_error + 0x000000000002151c 0x40 common/built-in.o + 0x000000000002151c cmd_process_error + +So the error occurred at the start of function do\_undefined() and this +function was invoked from somewhere inside function cmd\_process(). + +If we want to dive deeper, we can disassemble the U-Boot binary:: + + $ aarch64-linux-gnu-objdump -S -D u-boot | less + + 00000000000101fc <do_undefined>: + { + /* + * 0xe7f...f. is undefined in ARM mode + * 0xde.. is undefined in Thumb mode + */ + asm volatile (".word 0xe7f7defb\n"); + 101fc: e7f7defb .inst 0xe7f7defb ; undefined + return CMD_RET_FAILURE; + } + 10200: 52800020 mov w0, #0x1 // #1 + 10204: d65f03c0 ret + +This example is based on the ARMv8 architecture but the same procedures can be +used on other architectures as well. diff --git a/roms/u-boot/doc/develop/driver-model/bind.rst b/roms/u-boot/doc/develop/driver-model/bind.rst new file mode 100644 index 000000000..b19661b5f --- /dev/null +++ b/roms/u-boot/doc/develop/driver-model/bind.rst @@ -0,0 +1,49 @@ +.. SPDX-License-Identifier: GPL-2.0+ +.. sectionauthor:: Patrice Chotard <patrice.chotard@foss.st.com> + +Binding/unbinding a driver +========================== + +This document aims to describe the bind and unbind commands. + +For debugging purpose, it should be useful to bind or unbind a driver from +the U-boot command line. + +The unbind command calls the remove device driver callback and unbind the +device from its driver. + +The bind command binds a device to its driver. + +In some cases it can be useful to be able to bind a device to a driver from +the command line. +The obvious example is for versatile devices such as USB gadget. +Another use case is when the devices are not yet ready at startup and +require some setup before the drivers are bound (ex: FPGA which bitsream is +fetched from a mass storage or ethernet) + +usage: + +bind <node path> <driver> +bind <class> <index> <driver> + +unbind <node path> +unbind <class> <index> +unbind <class> <index> <driver> + +Where: + - <node path> is the node's device tree path + - <class> is one of the class available in the list given by the "dm uclass" + command or first column of "dm tree" command. + - <index> is the index of the parent's node (second column of "dm tree" output). + - <driver> is the driver name to bind given by the "dm drivers" command or the by + the fourth column of "dm tree" output. + +example: + +bind usb_dev_generic 0 usb_ether +unbind usb_dev_generic 0 usb_ether +or +unbind eth 1 + +bind /ocp/omap_dwc3@48380000/usb@48390000 usb_ether +unbind /ocp/omap_dwc3@48380000/usb@48390000 diff --git a/roms/u-boot/doc/develop/driver-model/debugging.rst b/roms/u-boot/doc/develop/driver-model/debugging.rst new file mode 100644 index 000000000..bbb279434 --- /dev/null +++ b/roms/u-boot/doc/develop/driver-model/debugging.rst @@ -0,0 +1,62 @@ +.. SPDX-License-Identifier: GPL-2.0+ +.. sectionauthor:: Simon Glass <sjg@chromium.org> + +Debugging driver model +====================== + +This document aims to provide help when you cannot work out why driver model is +not doing what you expect. + + +Useful techniques in general +---------------------------- + +Here are some useful debugging features generally. + + - If you are writing a new feature, consider doing it in sandbox instead of + on your board. Sandbox has no limits, allows easy debugging (e.g. gdb) and + you can write emulators for most common devices. + - Put '#define DEBUG' at the top of a file, to activate all the debug() and + log_debug() statements in that file. + - Where logging is used, change the logging level, e.g. in SPL with + CONFIG_SPL_LOG_MAX_LEVEL=7 (which is LOGL_DEBUG) and + CONFIG_LOG_DEFAULT_LEVEL=7 + - Where logging of return values is implemented with log_msg_ret(), set + CONFIG_LOG_ERROR_RETURN=y to see exactly where the error is happening + - Make sure you have a debug UART enabled - see CONFIG_DEBUG_UART. With this + you can get serial output (printf(), etc.) before the serial driver is + running. + - Use a JTAG emulator to set breakpoints and single-step through code + +Not that most of these increase code/data size somewhat when enabled. + + +Failure to locate a device +-------------------------- + +Let's say you have uclass_first_device_err() and it is not finding anything. + +If it is returning an error, then that gives you a clue. Look up linux/errno.h +to see errors. Common ones are: + + - -ENOMEM which indicates that memory is short. If it happens in SPL or + before relocation in U-Boot, check CONFIG_SPL_SYS_MALLOC_F_LEN and + CONFIG_SYS_MALLOC_F_LEN as they may need to be larger. Add '#define DEBUG' + at the very top of malloc_simple.c to get an idea of where your memory is + going. + - -EINVAL which typically indicates that something was missing or wrong in + the device tree node. Check that everything is correct and look at the + of_to_plat() method in the driver. + +If there is no error, you should check if the device is actually bound. Call +dm_dump_all() just before you locate the device to make sure it exists. + +If it does not exist, check your device tree compatible strings match up with +what the driver expects (in the struct udevice_id array). + +If you are using of-platdata (e.g. CONFIG_SPL_OF_PLATDATA), check that the +driver name is the same as the first compatible string in the device tree (with +invalid-variable characters converted to underscore). + +If you are really stuck, putting '#define LOG_DEBUG' at the top of +drivers/core/lists.c should show you what is going on. diff --git a/roms/u-boot/doc/develop/driver-model/design.rst b/roms/u-boot/doc/develop/driver-model/design.rst new file mode 100644 index 000000000..b0e633703 --- /dev/null +++ b/roms/u-boot/doc/develop/driver-model/design.rst @@ -0,0 +1,1149 @@ +.. 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> + +This has been both simplified and extended into the current implementation +by: + + * 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. + +Driver + some code which talks to a peripheral and presents a higher-level + interface to it. + +Device + an instance of a driver, tied to a particular port or peripheral. + + +How to try it +------------- + +Build U-Boot sandbox and run it:: + + make sandbox_defconfig + make + ./u-boot -d u-boot.dtb + + (type 'reset' to exit U-Boot) + + +There is a uclass called 'demo'. This uclass handles +saying hello, and reporting its status. There are two drivers in this +uclass: + + - simple: Just prints a message for hello, doesn't implement status + - shape: Prints shapes and reports number of characters printed as status + +The demo class is pretty simple, but not trivial. The intention is that it +can be used for testing, so it will implement all driver model features and +provide good code coverage of them. It does have multiple drivers, it +handles parameter data and plat (data which tells the driver how +to operate on a particular platform) and it uses private driver data. + +To try it, see the example session below:: + + =>demo hello 1 + Hello '@' from 07981110: red 4 + =>demo status 2 + Status: 0 + =>demo hello 2 + g + r@ + e@@ + e@@@ + n@@@@ + g@@@@@ + =>demo status 2 + Status: 21 + =>demo hello 4 ^ + y^^^ + e^^^^^ + l^^^^^^^ + l^^^^^^^ + o^^^^^ + w^^^ + =>demo status 4 + Status: 36 + => + + +Running the tests +----------------- + +The intent with driver model is that the core portion has 100% test coverage +in sandbox, and every uclass has its own test. As a move towards this, tests +are provided in test/dm. To run them, try:: + + ./test/py/test.py --bd sandbox --build -k ut_dm -v + +You should see something like this:: + + (venv)$ ./test/py/test.py --bd sandbox --build -k ut_dm -v + +make O=/root/u-boot/build-sandbox -s sandbox_defconfig + +make O=/root/u-boot/build-sandbox -s -j8 + ============================= test session starts ============================== + platform linux2 -- Python 2.7.5, pytest-2.9.0, py-1.4.31, pluggy-0.3.1 -- /root/u-boot/venv/bin/python + cachedir: .cache + rootdir: /root/u-boot, inifile: + collected 199 items + + test/py/tests/test_ut.py::test_ut_dm_init PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_adc_bind] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_adc_multi_channel_conversion] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_adc_multi_channel_shot] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_adc_single_channel_conversion] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_adc_single_channel_shot] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_adc_supply] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_adc_wrong_channel_selection] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_autobind] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_autobind_uclass_pdata_alloc] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_autobind_uclass_pdata_valid] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_autoprobe] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_bus_child_post_bind] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_bus_child_post_bind_uclass] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_bus_child_pre_probe_uclass] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_bus_children] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_bus_children_funcs] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_bus_children_iterators] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_bus_parent_data] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_bus_parent_data_uclass] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_bus_parent_ops] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_bus_parent_platdata] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_bus_parent_platdata_uclass] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_children] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_clk_base] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_clk_periph] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_device_get_uclass_id] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_eth] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_eth_act] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_eth_alias] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_eth_prime] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_eth_rotate] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_fdt] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_fdt_offset] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_fdt_pre_reloc] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_fdt_uclass_seq] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_gpio] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_gpio_anon] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_gpio_copy] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_gpio_leak] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_gpio_phandles] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_gpio_requestf] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_i2c_bytewise] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_i2c_find] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_i2c_offset] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_i2c_offset_len] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_i2c_probe_empty] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_i2c_read_write] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_i2c_speed] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_leak] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_led_base] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_led_gpio] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_led_label] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_lifecycle] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_mmc_base] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_net_retry] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_operations] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_ordering] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_pci_base] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_pci_busnum] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_pci_swapcase] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_platdata] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_power_pmic_get] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_power_pmic_io] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_power_regulator_autoset] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_power_regulator_autoset_list] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_power_regulator_get] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_power_regulator_set_get_current] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_power_regulator_set_get_enable] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_power_regulator_set_get_mode] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_power_regulator_set_get_voltage] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_pre_reloc] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_ram_base] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_regmap_base] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_regmap_syscon] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_remoteproc_base] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_remove] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_reset_base] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_reset_walk] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_rtc_base] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_rtc_dual] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_rtc_reset] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_rtc_set_get] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_spi_find] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_spi_flash] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_spi_xfer] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_syscon_base] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_syscon_by_driver_data] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_timer_base] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_uclass] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_uclass_before_ready] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_uclass_devices_find] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_uclass_devices_find_by_name] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_uclass_devices_get] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_uclass_devices_get_by_name] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_usb_base] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_usb_flash] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_usb_keyb] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_usb_multi] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_usb_remove] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_usb_tree] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_usb_tree_remove] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_usb_tree_reorder] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_video_base] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_video_bmp] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_video_bmp_comp] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_video_chars] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_video_context] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_video_rotation1] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_video_rotation2] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_video_rotation3] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_video_text] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_video_truetype] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_video_truetype_bs] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_video_truetype_scroll] PASSED + + ======================= 84 tests deselected by '-kut_dm' ======================= + ================== 115 passed, 84 deselected in 3.77 seconds =================== + +What is going on? +----------------- + +Let's start at the top. The demo command is in cmd/demo.c. It does +the usual command processing and then: + +.. code-block:: c + + struct udevice *demo_dev; + + ret = uclass_get_device(UCLASS_DEMO, devnum, &demo_dev); + +UCLASS_DEMO means the class of devices which implement 'demo'. Other +classes might be MMC, or GPIO, hashing or serial. The idea is that the +devices in the class all share a particular way of working. The class +presents a unified view of all these devices to U-Boot. + +This function looks up a device for the demo uclass. Given a device +number we can find the device because all devices have registered with +the UCLASS_DEMO uclass. + +The device is automatically activated ready for use by uclass_get_device(). + +Now that we have the device we can do things like: + +.. code-block:: c + + return demo_hello(demo_dev, ch); + +This function is in the demo uclass. It takes care of calling the 'hello' +method of the relevant driver. Bearing in mind that there are two drivers, +this particular device may use one or other of them. + +The code for demo_hello() is in drivers/demo/demo-uclass.c: + +.. code-block:: c + + int demo_hello(struct udevice *dev, int ch) + { + const struct demo_ops *ops = device_get_ops(dev); + + if (!ops->hello) + return -ENOSYS; + + return ops->hello(dev, ch); + } + +As you can see it just calls the relevant driver method. One of these is +in drivers/demo/demo-simple.c: + +.. code-block:: c + + static int simple_hello(struct udevice *dev, int ch) + { + const struct dm_demo_pdata *pdata = dev_get_plat(dev); + + printf("Hello from %08x: %s %d\n", map_to_sysmem(dev), + pdata->colour, pdata->sides); + + return 0; + } + + +So that is a trip from top (command execution) to bottom (driver action) +but it leaves a lot of topics to address. + + +Declaring Drivers +----------------- + +A driver declaration looks something like this (see +drivers/demo/demo-shape.c): + +.. code-block:: c + + static const struct demo_ops shape_ops = { + .hello = shape_hello, + .status = shape_status, + }; + + U_BOOT_DRIVER(demo_shape_drv) = { + .name = "demo_shape_drv", + .id = UCLASS_DEMO, + .ops = &shape_ops, + .priv_data_size = sizeof(struct shape_data), + }; + + +This driver has two methods (hello and status) and requires a bit of +private data (accessible through dev_get_priv(dev) once the driver has +been probed). It is a member of UCLASS_DEMO so will register itself +there. + +In U_BOOT_DRIVER it is also possible to specify special methods for bind +and unbind, and these are called at appropriate times. For many drivers +it is hoped that only 'probe' and 'remove' will be needed. + +The U_BOOT_DRIVER macro creates a data structure accessible from C, +so driver model can find the drivers that are available. + +The methods a device can provide are documented in the device.h header. +Briefly, they are: + + * bind - make the driver model aware of a device (bind it to its driver) + * unbind - make the driver model forget the device + * of_to_plat - convert device tree data to plat - see later + * probe - make a device ready for use + * remove - remove a device so it cannot be used until probed again + +The sequence to get a device to work is bind, of_to_plat (if using +device tree) and probe. + + +Platform Data +------------- + +Note: platform data is the old way of doing things. It is +basically a C structure which is passed to drivers to tell them about +platform-specific settings like the address of its registers, bus +speed, etc. Device tree is now the preferred way of handling this. +Unless you have a good reason not to use device tree (the main one +being you need serial support in SPL and don't have enough SRAM for +the cut-down device tree and libfdt libraries) you should stay away +from platform data. + +Platform data is like Linux platform data, if you are familiar with that. +It provides the board-specific information to start up a device. + +Why is this information not just stored in the device driver itself? The +idea is that the device driver is generic, and can in principle operate on +any board that has that type of device. For example, with modern +highly-complex SoCs it is common for the IP to come from an IP vendor, and +therefore (for example) the MMC controller may be the same on chips from +different vendors. It makes no sense to write independent drivers for the +MMC controller on each vendor's SoC, when they are all almost the same. +Similarly, we may have 6 UARTs in an SoC, all of which are mostly the same, +but lie at different addresses in the address space. + +Using the UART example, we have a single driver and it is instantiated 6 +times by supplying 6 lots of platform data. Each lot of platform data +gives the driver name and a pointer to a structure containing information +about this instance - e.g. the address of the register space. It may be that +one of the UARTS supports RS-485 operation - this can be added as a flag in +the platform data, which is set for this one port and clear for the rest. + +Think of your driver as a generic piece of code which knows how to talk to +a device, but needs to know where it is, any variant/option information and +so on. Platform data provides this link between the generic piece of code +and the specific way it is bound on a particular board. + +Examples of platform data include: + + - The base address of the IP block's register space + - Configuration options, like: + - the SPI polarity and maximum speed for a SPI controller + - the I2C speed to use for an I2C device + - the number of GPIOs available in a GPIO device + +Where does the platform data come from? It is either held in a structure +which is compiled into U-Boot, or it can be parsed from the Device Tree +(see 'Device Tree' below). + +For an example of how it can be compiled in, see demo-pdata.c which +sets up a table of driver names and their associated platform data. +The data can be interpreted by the drivers however they like - it is +basically a communication scheme between the board-specific code and +the generic drivers, which are intended to work on any board. + +Drivers can access their data via dev->info->plat. Here is +the declaration for the platform data, which would normally appear +in the board file. + +.. code-block:: c + + static const struct dm_demo_pdata red_square = { + .colour = "red", + .sides = 4. + }; + + static const struct driver_info info[] = { + { + .name = "demo_shape_drv", + .plat = &red_square, + }, + }; + + demo1 = driver_bind(root, &info[0]); + + +Device Tree +----------- + +While plat is useful, a more flexible way of providing device data is +by using device tree. In U-Boot you should use this where possible. Avoid +sending patches which make use of the U_BOOT_DRVINFO() macro unless strictly +necessary. + +With device tree we replace the above code with the following device tree +fragment: + +.. code-block:: c + + red-square { + compatible = "demo-shape"; + colour = "red"; + sides = <4>; + }; + +This means that instead of having lots of U_BOOT_DRVINFO() declarations in +the board file, we put these in the device tree. This approach allows a lot +more generality, since the same board file can support many types of boards +(e,g. with the same SoC) just by using different device trees. An added +benefit is that the Linux device tree can be used, thus further simplifying +the task of board-bring up either for U-Boot or Linux devs (whoever gets to +the board first!). + +The easiest way to make this work it to add a few members to the driver: + +.. code-block:: c + + .plat_auto = sizeof(struct dm_test_pdata), + .of_to_plat = testfdt_of_to_plat, + +The 'auto' feature allowed space for the plat to be allocated +and zeroed before the driver's of_to_plat() method is called. The +of_to_plat() method, which the driver write supplies, should parse +the device tree node for this device and place it in dev->plat. Thus +when the probe method is called later (to set up the device ready for use) +the platform data will be present. + +Note that both methods are optional. If you provide an of_to_plat +method then it will be called first (during activation). If you provide a +probe method it will be called next. See Driver Lifecycle below for more +details. + +If you don't want to have the plat automatically allocated then you +can leave out plat_auto. In this case you can use malloc +in your of_to_plat (or probe) method to allocate the required memory, +and you should free it in the remove method. + +The driver model tree is intended to mirror that of the device tree. The +root driver is at device tree offset 0 (the root node, '/'), and its +children are the children of the root node. + +In order for a device tree to be valid, the content must be correct with +respect to either device tree specification +(https://www.devicetree.org/specifications/) or the device tree bindings that +are found in the doc/device-tree-bindings directory. When not U-Boot specific +the bindings in this directory tend to come from the Linux Kernel. As such +certain design decisions may have been made already for us in terms of how +specific devices are described and bound. In most circumstances we wish to +retain compatibility without additional changes being made to the device tree +source files. + +Declaring Uclasses +------------------ + +The demo uclass is declared like this: + +.. code-block:: c + + UCLASS_DRIVER(demo) = { + .id = UCLASS_DEMO, + }; + +It is also possible to specify special methods for probe, etc. The uclass +numbering comes from include/dm/uclass-id.h. To add a new uclass, add to the +end of the enum there, then declare your uclass as above. + + +Device Sequence Numbers +----------------------- + +U-Boot numbers devices from 0 in many situations, such as in the command +line for I2C and SPI buses, and the device names for serial ports (serial0, +serial1, ...). Driver model supports this numbering and permits devices +to be locating by their 'sequence'. This numbering uniquely identifies a +device in its uclass, so no two devices within a particular uclass can have +the same sequence number. + +Sequence numbers start from 0 but gaps are permitted. For example, a board +may have I2C buses 1, 4, 5 but no 0, 2 or 3. The choice of how devices are +numbered is up to a particular board, and may be set by the SoC in some +cases. While it might be tempting to automatically renumber the devices +where there are gaps in the sequence, this can lead to confusion and is +not the way that U-Boot works. + +Where a device gets its sequence number is controlled by the DM_SEQ_ALIAS +Kconfig option, which can have a different value in U-Boot proper and SPL. +If this option is not set, aliases are ignored. + +Even if CONFIG_DM_SEQ_ALIAS is enabled, the uclass must still have the +DM_UC_FLAG_SEQ_ALIAS flag set, for its devices to be sequenced by aliases. + +With those options set, devices with an alias (e.g. "serial2") will get that +sequence number (e.g. 2). Other devices get the next available number after all +aliases and all existing numbers. This means that if there is just a single +alias "serial2", unaliased serial devices will be assigned 3 or more, with 0 and +1 being unused. + +If CONFIG_DM_SEQ_ALIAS or DM_UC_FLAG_SEQ_ALIAS are not set, all devices will get +sequence numbers in a simple ordering starting from 0. To find the next number +to allocate, driver model scans through to find the maximum existing number, +then uses the next one. It does not attempt to fill in gaps. + +.. code-block:: none + + aliases { + serial2 = "/serial@22230000"; + }; + +This indicates that in the uclass called "serial", the named node +("/serial@22230000") will be given sequence number 2. Any command or driver +which requests serial device 2 will obtain this device. + +More commonly you can use node references, which expand to the full path: + +.. code-block:: none + + aliases { + serial2 = &serial_2; + }; + ... + serial_2: serial@22230000 { + ... + }; + +The alias resolves to the same string in this case, but this version is +easier to read. + +Device sequence numbers are resolved when a device is bound and the number does +not change for the life of the device. + +There are some situations where the uclass must allocate sequence numbers, +since a strictly increase sequence (with devicetree nodes bound first) is not +suitable. An example of this is the PCI bus. In this case, you can set the +uclass DM_UC_FLAG_NO_AUTO_SEQ flag. With this flag set, only devices with an +alias will be assigned a number by driver model. The rest is left to the uclass +to sort out, e.g. when enumerating the bus. + +Note that changing the sequence number for a device (e.g. in a driver) is not +permitted. If it is felt to be necessary, ask on the mailing list. + +Bus Drivers +----------- + +A common use of driver model is to implement a bus, a device which provides +access to other devices. Example of buses include SPI and I2C. Typically +the bus provides some sort of transport or translation that makes it +possible to talk to the devices on the bus. + +Driver model provides some useful features to help with implementing buses. +Firstly, a bus can request that its children store some 'parent data' which +can be used to keep track of child state. Secondly, the bus can define +methods which are called when a child is probed or removed. This is similar +to the methods the uclass driver provides. Thirdly, per-child platform data +can be provided to specify things like the child's address on the bus. This +persists across child probe()/remove() cycles. + +For consistency and ease of implementation, the bus uclass can specify the +per-child platform data, so that it can be the same for all children of buses +in that uclass. There are also uclass methods which can be called when +children are bound and probed. + +Here an explanation of how a bus fits with a uclass may be useful. Consider +a USB bus with several devices attached to it, each from a different (made +up) uclass:: + + xhci_usb (UCLASS_USB) + eth (UCLASS_ETH) + camera (UCLASS_CAMERA) + flash (UCLASS_FLASH_STORAGE) + +Each of the devices is connected to a different address on the USB bus. +The bus device wants to store this address and some other information such +as the bus speed for each device. + +To achieve this, the bus device can use dev->parent_plat in each of its +three children. This can be auto-allocated if the bus driver (or bus uclass) +has a non-zero value for per_child_plat_auto. If not, then +the bus device or uclass can allocate the space itself before the child +device is probed. + +Also the bus driver can define the child_pre_probe() and child_post_remove() +methods to allow it to do some processing before the child is activated or +after it is deactivated. + +Similarly the bus uclass can define the child_post_bind() method to obtain +the per-child platform data from the device tree and set it up for the child. +The bus uclass can also provide a child_pre_probe() method. Very often it is +the bus uclass that controls these features, since it avoids each driver +having to do the same processing. Of course the driver can still tweak and +override these activities. + +Note that the information that controls this behaviour is in the bus's +driver, not the child's. In fact it is possible that child has no knowledge +that it is connected to a bus. The same child device may even be used on two +different bus types. As an example. the 'flash' device shown above may also +be connected on a SATA bus or standalone with no bus:: + + xhci_usb (UCLASS_USB) + flash (UCLASS_FLASH_STORAGE) - parent data/methods defined by USB bus + + sata (UCLASS_AHCI) + flash (UCLASS_FLASH_STORAGE) - parent data/methods defined by SATA bus + + flash (UCLASS_FLASH_STORAGE) - no parent data/methods (not on a bus) + +Above you can see that the driver for xhci_usb/sata controls the child's +bus methods. In the third example the device is not on a bus, and therefore +will not have these methods at all. Consider the case where the flash +device defines child methods. These would be used for *its* children, and +would be quite separate from the methods defined by the driver for the bus +that the flash device is connetced to. The act of attaching a device to a +parent device which is a bus, causes the device to start behaving like a +bus device, regardless of its own views on the matter. + +The uclass for the device can also contain data private to that uclass. +But note that each device on the bus may be a member of a different +uclass, and this data has nothing to do with the child data for each child +on the bus. It is the bus' uclass that controls the child with respect to +the bus. + + +Driver Lifecycle +---------------- + +Here are the stages that a device goes through in driver model. Note that all +methods mentioned here are optional - e.g. if there is no probe() method for +a device then it will not be called. A simple device may have very few +methods actually defined. + +Bind stage +^^^^^^^^^^ + +U-Boot discovers devices using one of these two methods: + +- Scan the U_BOOT_DRVINFO() definitions. U-Boot looks up the name specified + by each, to find the appropriate U_BOOT_DRIVER() definition. In this case, + there is no path by which driver_data may be provided, but the U_BOOT_DRVINFO() + may provide plat. + +- Scan through the device tree definitions. U-Boot looks at top-level + nodes in the the device tree. It looks at the compatible string in each node + and uses the of_match table of the U_BOOT_DRIVER() structure to find the + right driver for each node. In this case, the of_match table may provide a + driver_data value, but plat cannot be provided until later. + +For each device that is discovered, U-Boot then calls device_bind() to create a +new device, initializes various core fields of the device object such as name, +uclass & driver, initializes any optional fields of the device object that are +applicable such as of_offset, driver_data & plat, and finally calls the +driver's bind() method if one is defined. + +At this point all the devices are known, and bound to their drivers. There +is a 'struct udevice' allocated for all devices. However, nothing has been +activated (except for the root device). Each bound device that was created +from a U_BOOT_DRVINFO() declaration will hold the plat pointer specified +in that declaration. For a bound device created from the device tree, +plat will be NULL, but of_offset will be the offset of the device tree +node that caused the device to be created. The uclass is set correctly for +the device. + +The device's sequence number is assigned, either the requested one or the next +available one (after all aliases are processed) if nothing particular is +requested. + +The device's bind() method is permitted to perform simple actions, but +should not scan the device tree node, not initialise hardware, nor set up +structures or allocate memory. All of these tasks should be left for +the probe() method. + +Note that compared to Linux, U-Boot's driver model has a separate step of +probe/remove which is independent of bind/unbind. This is partly because in +U-Boot it may be expensive to probe devices and we don't want to do it until +they are needed, or perhaps until after relocation. + +Reading ofdata +^^^^^^^^^^^^^^ + +Most devices have data in the device tree which they can read to find out the +base address of hardware registers and parameters relating to driver +operation. This is called 'ofdata' (Open-Firmware data). + +The device's of_to_plat() implemnents allocation and reading of +plat. A parent's ofdata is always read before a child. + +The steps are: + + 1. If priv_auto is non-zero, then the device-private space + is allocated for the device and zeroed. It will be accessible as + dev->priv. The driver can put anything it likes in there, but should use + it for run-time information, not platform data (which should be static + and known before the device is probed). + + 2. If plat_auto is non-zero, then the platform data space + is allocated. This is only useful for device tree operation, since + otherwise you would have to specify the platform data in the + U_BOOT_DRVINFO() declaration. The space is allocated for the device and + zeroed. It will be accessible as dev->plat. + + 3. If the device's uclass specifies a non-zero per_device_auto, + then this space is allocated and zeroed also. It is allocated for and + stored in the device, but it is uclass data. owned by the uclass driver. + It is possible for the device to access it. + + 4. If the device's immediate parent specifies a per_child_auto + then this space is allocated. This is intended for use by the parent + device to keep track of things related to the child. For example a USB + flash stick attached to a USB host controller would likely use this + space. The controller can hold information about the USB state of each + of its children. + + 5. If the driver provides an of_to_plat() method, then this is + called to convert the device tree data into platform data. This should + do various calls like dev_read_u32(dev, ...) to access the node and store + the resulting information into dev->plat. After this point, the device + works the same way whether it was bound using a device tree node or + U_BOOT_DRVINFO() structure. In either case, the platform data is now stored + in the plat structure. Typically you will use the + plat_auto feature to specify the size of the platform data + structure, and U-Boot will automatically allocate and zero it for you before + entry to of_to_plat(). But if not, you can allocate it yourself in + of_to_plat(). Note that it is preferable to do all the device tree + decoding in of_to_plat() rather than in probe(). (Apart from the + ugliness of mixing configuration and run-time data, one day it is possible + that U-Boot will cache platform data for devices which are regularly + de/activated). + + 6. The device is marked 'plat valid'. + +Note that ofdata reading is always done (for a child and all its parents) +before probing starts. Thus devices go through two distinct states when +probing: reading platform data and actually touching the hardware to bring +the device up. + +Having probing separate from ofdata-reading helps deal with of-platdata, where +the probe() method is common to both DT/of-platdata operation, but the +of_to_plat() method is implemented differently. + +Another case has come up where this separate is useful. Generation of ACPI +tables uses the of-platdata but does not want to probe the device. Probing +would cause U-Boot to violate one of its design principles, viz that it +should only probe devices that are used. For ACPI we want to generate a +table for each device, even if U-Boot does not use it. In fact it may not +even be possible to probe the device - e.g. an SD card which is not +present will cause an error on probe, yet we still must tell Linux about +the SD card connector in case it is used while Linux is running. + +It is important that the of_to_plat() method does not actually probe +the device itself. However there are cases where other devices must be probed +in the of_to_plat() method. An example is where a device requires a +GPIO for it to operate. To select a GPIO obviously requires that the GPIO +device is probed. This is OK when used by common, core devices such as GPIO, +clock, interrupts, reset and the like. + +If your device relies on its parent setting up a suitable address space, so +that dev_read_addr() works correctly, then make sure that the parent device +has its setup code in of_to_plat(). If it has it in the probe method, +then you cannot call dev_read_addr() from the child device's +of_to_plat() method. Move it to probe() instead. Buses like PCI can +fall afoul of this rule. + +Activation/probe +^^^^^^^^^^^^^^^^ + +When a device needs to be used, U-Boot activates it, by first reading ofdata +as above and then following these steps (see device_probe()): + + 1. All parent devices are probed. It is not possible to activate a device + unless its predecessors (all the way up to the root device) are activated. + This means (for example) that an I2C driver will require that its bus + be activated. + + 2. The device's probe() method is called. This should do anything that + is required by the device to get it going. This could include checking + that the hardware is actually present, setting up clocks for the + hardware and setting up hardware registers to initial values. The code + in probe() can access: + + - platform data in dev->plat (for configuration) + - private data in dev->priv (for run-time state) + - uclass data in dev->uclass_priv (for things the uclass stores + about this device) + + Note: If you don't use priv_auto then you will need to + allocate the priv space here yourself. The same applies also to + plat_auto. Remember to free them in the remove() method. + + 3. The device is marked 'activated' + + 4. The uclass's post_probe() method is called, if one exists. This may + cause the uclass to do some housekeeping to record the device as + activated and 'known' by the uclass. + +Running stage +^^^^^^^^^^^^^ + +The device is now activated and can be used. From now until it is removed +all of the above structures are accessible. The device appears in the +uclass's list of devices (so if the device is in UCLASS_GPIO it will appear +as a device in the GPIO uclass). This is the 'running' state of the device. + +Removal stage +^^^^^^^^^^^^^ + +When the device is no-longer required, you can call device_remove() to +remove it. This performs the probe steps in reverse: + + 1. The uclass's pre_remove() method is called, if one exists. This may + cause the uclass to do some housekeeping to record the device as + deactivated and no-longer 'known' by the uclass. + + 2. All the device's children are removed. It is not permitted to have + an active child device with a non-active parent. This means that + device_remove() is called for all the children recursively at this point. + + 3. The device's remove() method is called. At this stage nothing has been + deallocated so platform data, private data and the uclass data will all + still be present. This is where the hardware can be shut down. It is + intended that the device be completely inactive at this point, For U-Boot + to be sure that no hardware is running, it should be enough to remove + all devices. + + 4. The device memory is freed (platform data, private data, uclass data, + parent data). + + Note: Because the platform data for a U_BOOT_DRVINFO() is defined with a + static pointer, it is not de-allocated during the remove() method. For + a device instantiated using the device tree data, the platform data will + be dynamically allocated, and thus needs to be deallocated during the + remove() method, either: + + - if the plat_auto is non-zero, the deallocation happens automatically + within the driver model core in the unbind stage; or + + - when plat_auto is 0, both the allocation (in probe() + or preferably of_to_plat()) and the deallocation in remove() + are the responsibility of the driver author. + + 5. The device is marked inactive. Note that it is still bound, so the + device structure itself is not freed at this point. Should the device be + activated again, then the cycle starts again at step 2 above. + +Unbind stage +^^^^^^^^^^^^ + +The device is unbound. This is the step that actually destroys the device. +If a parent has children these will be destroyed first. After this point +the device does not exist and its memory has be deallocated. + + +Special cases for removal +------------------------- + +Some devices need to do clean-up before the OS is called. For example, a USB +driver may want to stop the bus. This can be done in the remove() method. +Some special flags are used to determine whether to remove the device: + + DM_FLAG_OS_PREPARE - indicates that the device needs to get ready for OS + boot. The device will be removed just before the OS is booted + DM_REMOVE_ACTIVE_DMA - indicates that the device uses DMA. This is + effectively the same as DM_FLAG_OS_PREPARE, so the device is removed + before the OS is booted + DM_FLAG_VITAL - indicates that the device is 'vital' to the operation of + other devices. It is possible to remove this device after all regular + devices are removed. This is useful e.g. for a clock, which need to + be active during the device-removal phase. + +The dm_remove_devices_flags() function can be used to remove devices based on +their driver flags. + + +Error codes +----------- + +Driver model tries to use errors codes in a consistent way, as follows: + +\-EAGAIN + Try later, e.g. dependencies not ready + +\-EINVAL + Invalid argument, such as `dev_read_...()` failed or any other + devicetree-related access. Also used when a driver method is passed an + argument it considers invalid or does not support. + +\-EIO + Failed to perform an I/O operation. This is used when a local device + (i.e. part of the SOC) does not work as expected. Use -EREMOTEIO for + failures to talk to a separate device, e.g. over an I2C or SPI + channel. + +\-ENODEV + Do not bind the device. This should not be used to indicate an + error probing the device or for any other purpose, lest driver model get + confused. Using `-ENODEV` inside a driver method makes no sense, since + clearly there is a device. + +\-ENOENT + Entry or object not found. This is used when a device, file or directory + cannot be found (e.g. when looked up by name), It can also indicate a + missing devicetree subnode. + +\-ENOMEM + Out of memory + +\-ENOSPC + Ran out of space (e.g. in a buffer or limited-size array) + +\-ENOSYS + Function not implemented. This is returned by uclasses where the driver does + not implement a particular method. It can also be returned by drivers when + a particular sub-method is not implemented. This is widely checked in the + wider code base, where a feature may or may not be compiled into U-Boot. It + indicates that the feature is not available, but this is often just normal + operation. Please do not use -ENOSUPP. If an incorrect or unknown argument + is provided to a method (e.g. an unknown clock ID), return -EINVAL. + +\-ENXIO + Couldn't find device/address. This is used when a device or address + could not be obtained or is not valid. It is often used to indicate a + different type of problem, if -ENOENT is already used for something else in + the driver. + +\-EPERM + This is -1 so some older code may use it as a generic error. This indicates + that an operation is not permitted, e.g. a security violation or policy + constraint. It is returned internally when binding devices before relocation, + if the device is not marked for pre-relocation use. + +\-EPFNOSUPPORT + Missing uclass. This is deliberately an uncommon error code so that it can + easily be distinguished. If you see this very early in U-Boot, it means that + a device exists with a particular uclass but the uclass does not (mostly + likely because it is not compiled in). Enable DEBUG in uclass.c or lists.c + to see which uclass ID or driver is causing the problem. + +\-EREMOTEIO + This indicates an error in talking to a peripheral over a comms link, such + as I2C or SPI. It might indicate that the device is not present or is not + responding as expected. + +\-ETIMEDOUT + Hardware access or some other operation has timed out. This is used where + there is an expected time of response and that was exceeded by enough of + a margin that there is probably something wrong. + + +Less common ones: + +\-ECOMM + Not widely used, but similar to -EREMOTEIO. Can be useful as a secondary + error to distinguish the problem from -EREMOTEIO. + +\-EKEYREJECTED + Attempt to remove a device which does not match the removal flags. See + device_remove(). + +\-EILSEQ + Devicetree read failure, specifically trying to read a string index which + does not exist, in a string-listg property + +\-ENOEXEC + Attempt to use a uclass method on a device not in that uclass. This is + seldom checked at present, since it is generally a programming error and a + waste of code space. A DEBUG-only check would be useful here. + +\-ENODATA + Devicetree read error, where a property exists but has no data associated + with it + +\-EOVERFLOW + Devicetree read error, where the property is longer than expected + +\-EPROBE_DEFER + Attempt to remove a non-vital device when the removal flags indicate that + only vital devices should be removed + +\-ERANGE + Returned by regmap functions when arguments are out of range. This can be + useful for disinguishing regmap errors from other errors obtained while + probing devices. + +Drivers should use the same conventions so that things function as expected. +In particular, if a driver fails to probe, or a uclass operation fails, the +error code is the primary way to indicate what actually happened. + +Printing error messages in drivers is discouraged due to code size bloat and +since it can result in messages appearing in normal operation. For example, if +a command tries two different devices and uses whichever one probes correctly, +we don't want an error message displayed, even if the command itself might show +a warning or informational message. Ideally, messages in drivers should only be +displayed when debugging, e.g. by using log_debug() although in extreme cases +log_warning() or log_error() may be used. + +Error messages can be logged using `log_msg_ret()`, so that enabling +`CONFIG_LOG` and `CONFIG_LOG_ERROR_RETURN` shows a trace of error codes returned +through the call stack. That can be a handy way of quickly figuring out where +an error occurred. Get into the habit of return errors with +`return log_msg_ret("here", ret)` instead of just `return ret`. The string +just needs to be long enough to find in a single function, since a log record +stores (and can print with `CONFIG_LOGF_FUNC`) the function where it was +generated. + + +Data Structures +--------------- + +Driver model uses a doubly-linked list as the basic data structure. Some +nodes have several lists running through them. Creating a more efficient +data structure might be worthwhile in some rare cases, once we understand +what the bottlenecks are. + + +Changes since v1 +---------------- + +For the record, this implementation uses a very similar approach to the +original patches, but makes at least the following changes: + +- Tried to aggressively remove boilerplate, so that for most drivers there + is little or no 'driver model' code to write. +- Moved some data from code into data structure - e.g. store a pointer to + the driver operations structure in the driver, rather than passing it + to the driver bind function. +- Rename some structures to make them more similar to Linux (struct udevice + instead of struct instance, struct plat, etc.) +- Change the name 'core' to 'uclass', meaning U-Boot class. It seems that + this concept relates to a class of drivers (or a subsystem). We shouldn't + use 'class' since it is a C++ reserved word, so U-Boot class (uclass) seems + better than 'core'. +- Remove 'struct driver_instance' and just use a single 'struct udevice'. + This removes a level of indirection that doesn't seem necessary. +- Built in device tree support, to avoid the need for plat +- Removed the concept of driver relocation, and just make it possible for + the new driver (created after relocation) to access the old driver data. + I feel that relocation is a very special case and will only apply to a few + drivers, many of which can/will just re-init anyway. So the overhead of + dealing with this might not be worth it. +- Implemented a GPIO system, trying to keep it simple + + +Pre-Relocation Support +---------------------- + +For pre-relocation we simply call the driver model init function. Only +drivers marked with DM_FLAG_PRE_RELOC or the device tree 'u-boot,dm-pre-reloc' +property are initialised prior to relocation. This helps to reduce the driver +model overhead. This flag applies to SPL and TPL as well, if device tree is +enabled (CONFIG_OF_CONTROL) there. + +Note when device tree is enabled, the device tree 'u-boot,dm-pre-reloc' +property can provide better control granularity on which device is bound +before relocation. While with DM_FLAG_PRE_RELOC flag of the driver all +devices with the same driver are bound, which requires allocation a large +amount of memory. When device tree is not used, DM_FLAG_PRE_RELOC is the +only way for statically declared devices via U_BOOT_DRVINFO() to be bound +prior to relocation. + +It is possible to limit this to specific relocation steps, by using +the more specialized 'u-boot,dm-spl' and 'u-boot,dm-tpl' flags +in the device tree node. For U-Boot proper you can use 'u-boot,dm-pre-proper' +which means that it will be processed (and a driver bound) in U-Boot proper +prior to relocation, but will not be available in SPL or TPL. + +To reduce the size of SPL and TPL, only the nodes with pre-relocation properties +('u-boot,dm-pre-reloc', 'u-boot,dm-spl' or 'u-boot,dm-tpl') are keept in their +device trees (see README.SPL for details); the remaining nodes are always bound. + +Then post relocation we throw that away and re-init driver model again. +For drivers which require some sort of continuity between pre- and +post-relocation devices, we can provide access to the pre-relocation +device pointers, but this is not currently implemented (the root device +pointer is saved but not made available through the driver model API). + + +SPL Support +----------- + +Driver model can operate in SPL. Its efficient implementation and small code +size provide for a small overhead which is acceptable for all but the most +constrained systems. + +To enable driver model in SPL, define CONFIG_SPL_DM. You might want to +consider the following option also. See the main README for more details. + + - CONFIG_SYS_MALLOC_SIMPLE + - CONFIG_DM_WARN + - CONFIG_DM_DEVICE_REMOVE + - CONFIG_DM_STDIO + + +Enabling Driver Model +--------------------- + +Driver model is being brought into U-Boot gradually. As each subsystems gets +support, a uclass is created and a CONFIG to enable use of driver model for +that subsystem. + +For example CONFIG_DM_SERIAL enables driver model for serial. With that +defined, the old serial support is not enabled, and your serial driver must +conform to driver model. With that undefined, the old serial support is +enabled and driver model is not available for serial. This means that when +you convert a driver, you must either convert all its boards, or provide for +the driver to be compiled both with and without driver model (generally this +is not very hard). + +See the main README for full details of the available driver model CONFIG +options. + + +Things to punt for later +------------------------ + +Uclasses are statically numbered at compile time. It would be possible to +change this to dynamic numbering, but then we would require some sort of +lookup service, perhaps searching by name. This is slightly less efficient +so has been left out for now. One small advantage of dynamic numbering might +be fewer merge conflicts in uclass-id.h. diff --git a/roms/u-boot/doc/develop/driver-model/ethernet.rst b/roms/u-boot/doc/develop/driver-model/ethernet.rst new file mode 100644 index 000000000..cdbccca34 --- /dev/null +++ b/roms/u-boot/doc/develop/driver-model/ethernet.rst @@ -0,0 +1,321 @@ +Ethernet Driver Guide +======================= + +The networking stack in Das U-Boot is designed for multiple network devices +to be easily added and controlled at runtime. This guide is meant for people +who wish to review the net driver stack with an eye towards implementing your +own ethernet device driver. Here we will describe a new pseudo 'APE' driver. + +Most existing drivers do already - and new network driver MUST - use the +U-Boot core driver model. Generic information about this can be found in +doc/driver-model/design.rst, this document will thus focus on the network +specific code parts. +Some drivers are still using the old Ethernet interface, differences between +the two and hints about porting will be handled at the end. + +Driver framework +------------------ + +A network driver following the driver model must declare itself using +the UCLASS_ETH .id field in the U-Boot driver struct: + +.. code-block:: c + + U_BOOT_DRIVER(eth_ape) = { + .name = "eth_ape", + .id = UCLASS_ETH, + .of_match = eth_ape_ids, + .of_to_plat = eth_ape_of_to_plat, + .probe = eth_ape_probe, + .ops = ð_ape_ops, + .priv_auto = sizeof(struct eth_ape_priv), + .plat_auto = sizeof(struct eth_ape_pdata), + .flags = DM_FLAG_ALLOC_PRIV_DMA, + }; + +struct eth_ape_priv contains runtime per-instance data, like buffers, pointers +to current descriptors, current speed settings, pointers to PHY related data +(like struct mii_dev) and so on. Declaring its size in .priv_auto +will let the driver framework allocate it at the right time. +It can be retrieved using a dev_get_priv(dev) call. + +struct eth_ape_pdata contains static platform data, like the MMIO base address, +a hardware variant, the MAC address. ``struct eth_pdata eth_pdata`` +as the first member of this struct helps to avoid duplicated code. +If you don't need any more platform data beside the standard member, +just use sizeof(struct eth_pdata) for the plat_auto. + +PCI devices add a line pointing to supported vendor/device ID pairs: + +.. code-block:: c + + static struct pci_device_id supported[] = { + { PCI_DEVICE(PCI_VENDOR_ID_APE, 0x4223) }, + {} + }; + + U_BOOT_PCI_DEVICE(eth_ape, supported); + +It is also possible to declare support for a whole class of PCI devices:: + + { PCI_DEVICE_CLASS(PCI_CLASS_SYSTEM_SDHCI << 8, 0xffff00) }, + +Device probing and instantiation will be handled by the driver model framework, +so follow the guidelines there. The probe() function would initialise the +platform specific parts of the hardware, like clocks, resets, GPIOs, the MDIO +bus. Also it would take care of any special PHY setup (power rails, enable +bits for internal PHYs, etc.). + +Driver methods +---------------- + +The real work will be done in the driver method functions the driver provides +by defining the members of struct eth_ops: + +.. code-block:: c + + struct eth_ops { + int (*start)(struct udevice *dev); + int (*send)(struct udevice *dev, void *packet, int length); + int (*recv)(struct udevice *dev, int flags, uchar **packetp); + int (*free_pkt)(struct udevice *dev, uchar *packet, int length); + void (*stop)(struct udevice *dev); + int (*mcast)(struct udevice *dev, const u8 *enetaddr, int join); + int (*write_hwaddr)(struct udevice *dev); + int (*read_rom_hwaddr)(struct udevice *dev); + }; + +An up-to-date version of this struct together with more information can be +found in include/net.h. + +Only start, stop, send and recv are required, the rest are optional and are +handled by generic code or ignored if not provided. + +The **start** function initialises the hardware and gets it ready for send/recv +operations. You often do things here such as resetting the MAC +and/or PHY, and waiting for the link to autonegotiate. You should also take +the opportunity to program the device's MAC address with the enetaddr member +of the generic struct eth_pdata (which would be the first member of your +own plat struct). This allows the rest of U-Boot to dynamically change +the MAC address and have the new settings be respected. + +The **send** function does what you think -- transmit the specified packet +whose size is specified by length (in bytes). The packet buffer can (and +will!) be reused for subsequent calls to send(), so it must be no longer +used when the send() function returns. The easiest way to achieve this is +to wait until the transmission is complete. Alternatively, if supported by +the hardware, just waiting for the buffer to be consumed (by some DMA engine) +might be an option as well. +Another way of consuming the buffer could be to copy the data to be send, +then just queue the copied packet (for instance handing it over to a DMA +engine), and return immediately afterwards. +In any case you should leave the state such that the send function can be +called multiple times in a row. + +The **recv** function polls for availability of a new packet. If none is +available, it must return with -EAGAIN. +If a packet has been received, make sure it is accessible to the CPU +(invalidate caches if needed), then write its address to the packetp pointer, +and return the length. If there is an error (receive error, too short or too +long packet), return 0 if you require the packet to be cleaned up normally, +or a negative error code otherwise (cleanup not necessary or already done). +The U-Boot network stack will then process the packet. + +If **free_pkt** is defined, U-Boot will call it after a received packet has +been processed, so the packet buffer can be freed or recycled. Typically you +would hand it back to the hardware to acquire another packet. free_pkt() will +be called after recv(), for the same packet, so you don't necessarily need +to infer the buffer to free from the ``packet`` pointer, but can rely on that +being the last packet that recv() handled. +The common code sets up packet buffers for you already in the .bss +(net_rx_packets), so there should be no need to allocate your own. This doesn't +mean you must use the net_rx_packets array however; you're free to use any +buffer you wish. + +The **stop** function should turn off / disable the hardware and place it back +in its reset state. It can be called at any time (before any call to the +related start() function), so make sure it can handle this sort of thing. + +The (optional) **write_hwaddr** function should program the MAC address stored +in pdata->enetaddr into the Ethernet controller. + +So the call graph at this stage would look something like: + +.. code-block:: c + + (some net operation (ping / tftp / whatever...)) + eth_init() + ops->start() + eth_send() + ops->send() + eth_rx() + ops->recv() + (process packet) + if (ops->free_pkt) + ops->free_pkt() + eth_halt() + ops->stop() + + +CONFIG_PHYLIB / CONFIG_CMD_MII +-------------------------------- + +If your device supports banging arbitrary values on the MII bus (pretty much +every device does), you should add support for the mii command. Doing so is +fairly trivial and makes debugging mii issues a lot easier at runtime. + +In your driver's ``probe()`` function, add a call to mdio_alloc() and +mdio_register() like so: + +.. code-block:: c + + bus = mdio_alloc(); + if (!bus) { + ... + return -ENOMEM; + } + + bus->read = ape_mii_read; + bus->write = ape_mii_write; + mdio_register(bus); + +And then define the mii_read and mii_write functions if you haven't already. +Their syntax is straightforward:: + + int mii_read(struct mii_dev *bus, int addr, int devad, int reg); + int mii_write(struct mii_dev *bus, int addr, int devad, int reg, + u16 val); + +The read function should read the register 'reg' from the phy at address 'addr' +and return the result to its caller. The implementation for the write function +should logically follow. + +................................................................ + +Legacy network drivers +------------------------ + +!!! WARNING !!! + +This section below describes the old way of doing things. No new Ethernet +drivers should be implemented this way. All new drivers should be written +against the U-Boot core driver model, as described above. + +The actual callback functions are fairly similar, the differences are: + +- ``start()`` is called ``init()`` +- ``stop()`` is called ``halt()`` +- The ``recv()`` function must loop until all packets have been received, for + each packet it must call the net_process_received_packet() function, + handing it over the pointer and the length. Afterwards it should free + the packet, before checking for new data. + +For porting an old driver to the new driver model, split the existing recv() +function into the actual new recv() function, just fetching **one** packet, +remove the call to net_process_received_packet(), then move the packet +cleanup into the ``free_pkt()`` function. + +Registering the driver and probing a device is handled very differently, +follow the recommendations in the driver model design documentation for +instructions on how to port this over. For the records, the old way of +initialising a network driver is as follows: + +Old network driver registration +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +When U-Boot initializes, it will call the common function eth_initialize(). +This will in turn call the board-specific board_eth_init() (or if that fails, +the cpu-specific cpu_eth_init()). These board-specific functions can do random +system handling, but ultimately they will call the driver-specific register +function which in turn takes care of initializing that particular instance. + +Keep in mind that you should code the driver to avoid storing state in global +data as someone might want to hook up two of the same devices to one board. +Any such information that is specific to an interface should be stored in a +private, driver-defined data structure and pointed to by eth->priv (see below). + +So the call graph at this stage would look something like: + +.. code-block:: c + + board_init() + eth_initialize() + board_eth_init() / cpu_eth_init() + driver_register() + initialize eth_device + eth_register() + +At this point in time, the only thing you need to worry about is the driver's +register function. The pseudo code would look something like: + +.. code-block:: c + + int ape_register(struct bd_info *bis, int iobase) + { + struct ape_priv *priv; + struct eth_device *dev; + struct mii_dev *bus; + + priv = malloc(sizeof(*priv)); + if (priv == NULL) + return -ENOMEM; + + dev = malloc(sizeof(*dev)); + if (dev == NULL) { + free(priv); + return -ENOMEM; + } + + /* setup whatever private state you need */ + + memset(dev, 0, sizeof(*dev)); + sprintf(dev->name, "APE"); + + /* + * if your device has dedicated hardware storage for the + * MAC, read it and initialize dev->enetaddr with it + */ + ape_mac_read(dev->enetaddr); + + dev->iobase = iobase; + dev->priv = priv; + dev->init = ape_init; + dev->halt = ape_halt; + dev->send = ape_send; + dev->recv = ape_recv; + dev->write_hwaddr = ape_write_hwaddr; + + eth_register(dev); + + #ifdef CONFIG_PHYLIB + bus = mdio_alloc(); + if (!bus) { + free(priv); + free(dev); + return -ENOMEM; + } + + bus->read = ape_mii_read; + bus->write = ape_mii_write; + mdio_register(bus); + #endif + + return 1; + } + +The exact arguments needed to initialize your device are up to you. If you +need to pass more/less arguments, that's fine. You should also add the +prototype for your new register function to include/netdev.h. + +The return value for this function should be as follows: +< 0 - failure (hardware failure, not probe failure) +>=0 - number of interfaces detected + +You might notice that many drivers seem to use xxx_initialize() rather than +xxx_register(). This is the old naming convention and should be avoided as it +causes confusion with the driver-specific init function. + +Other than locating the MAC address in dedicated hardware storage, you should +not touch the hardware in anyway. That step is handled in the driver-specific +init function. Remember that we are only registering the device here, we are +not checking its state or doing random probing. diff --git a/roms/u-boot/doc/develop/driver-model/fdt-fixup.rst b/roms/u-boot/doc/develop/driver-model/fdt-fixup.rst new file mode 100644 index 000000000..974c09031 --- /dev/null +++ b/roms/u-boot/doc/develop/driver-model/fdt-fixup.rst @@ -0,0 +1,132 @@ +.. SPDX-License-Identifier: GPL-2.0+ +.. 2017-01-06, Mario Six <mario.six@gdsys.cc> + +Pre-relocation device tree manipulation +======================================= + +Purpose +------- + +In certain markets, it is beneficial for manufacturers of embedded devices to +offer certain ranges of products, where the functionality of the devices within +one series either don't differ greatly from another, or can be thought of as +"extensions" of each other, where one device only differs from another in the +addition of a small number of features (e.g. an additional output connector). + +To realize this in hardware, one method is to have a motherboard, and several +possible daughter boards that can be attached to this mother board. Different +daughter boards then either offer the slightly different functionality, or the +addition of the daughter board to the device realizes the "extension" of +functionality to the device described previously. + +For the software, we obviously want to reuse components for all these +variations of the device. This means that the software somehow needs to cope +with the situation that certain ICs may or may not be present on any given +system, depending on which daughter boards are connected to the motherboard. + +In the Linux kernel, one possible solution to this problem is to employ the +device tree overlay mechanism: There exists one "base" device tree, which +features only the components guaranteed to exist in all varieties of the +device. At the start of the kernel, the presence and type of the daughter +boards is then detected, and the corresponding device tree overlays are applied +to support the components on the daughter boards. + +Note that the components present on every variety of the board must, of course, +provide a way to find out if and which daughter boards are installed for this +mechanism to work. + +In the U-Boot boot loader, support for device tree overlays has recently been +integrated, and is used on some boards to alter the device tree that is later +passed to Linux. But since U-Boot's driver model, which is device tree-based as +well, is being used in more and more drivers, the same problem of altering the +device tree starts cropping up in U-Boot itself as well. + +An additional problem with the device tree in U-Boot is that it is read-only, +and the current mechanisms don't allow easy manipulation of the device tree +after the driver model has been initialized. While migrating to a live device +tree (at least after the relocation) would greatly simplify the solution of +this problem, it is a non-negligible task to implement it, an a interim +solution is needed to address the problem at least in the medium-term. + +Hence, we propose a solution to this problem by offering a board-specific +call-back function, which is passed a writeable pointer to the device tree. +This function is called before the device tree is relocated, and specifically +before the main U-Boot's driver model is instantiated, hence the main U-Boot +"sees" all modifications to the device tree made in this function. Furthermore, +we have the pre-relocation driver model at our disposal at this stage, which +means that we can query the hardware for the existence and variety of the +components easily. + +Implementation +-------------- + +To take advantage of the pre-relocation device tree manipulation mechanism, +boards have to implement the function board_fix_fdt, which has the following +signature: + +.. code-block:: c + + int board_fix_fdt (void *rw_fdt_blob) + +The passed-in void pointer is a writeable pointer to the device tree, which can +be used to manipulate the device tree using e.g. functions from +include/fdt_support.h. The return value should either be 0 in case of +successful execution of the device tree manipulation or something else for a +failure. Note that returning a non-null value from the function will +unrecoverably halt the boot process, as with any function from init_sequence_f +(in common/board_f.c). + +Furthermore, the Kconfig option OF_BOARD_FIXUP has to be set for the function +to be called:: + + Device Tree Control + -> [*] Board-specific manipulation of Device Tree + ++----------------------------------------------------------+ +| WARNING: The actual manipulation of the device tree has | +| to be the _last_ set of operations in board_fix_fdt! | +| Since the pre-relocation driver model does not adapt to | +| changes made to the device tree either, its references | +| into the device tree will be invalid after manipulating | +| it, and unpredictable behavior might occur when | +| functions that rely on them are executed! | ++----------------------------------------------------------+ + +Hence, the recommended layout of the board_fixup_fdt call-back function is the +following: + +.. code-block:: c + + int board_fix_fdt(void *rw_fdt_blob) + { + /* + * Collect information about device's hardware and store + * them in e.g. local variables + */ + + /* Do device tree manipulation using the values previously collected */ + + /* Return 0 on successful manipulation and non-zero otherwise */ + } + +If this convention is kept, both an "additive" approach, meaning that nodes for +detected components are added to the device tree, as well as a "subtractive" +approach, meaning that nodes for absent components are removed from the tree, +as well as a combination of both approaches should work. + +Example +------- + +The controlcenterdc board (board/gdsys/a38x/controlcenterdc.c) features a +board_fix_fdt function, in which six GPIO expanders (which might be present or +not, since they are on daughter boards) on a I2C bus are queried for, and +subsequently deactivated in the device tree if they are not present. + +Note that the dm_i2c_simple_probe function does not use the device tree, hence +it is safe to call it after the tree has already been manipulated. + +Work to be done +--------------- + +* The application of device tree overlay should be possible in board_fixup_fdt, + but has not been tested at this stage. diff --git a/roms/u-boot/doc/develop/driver-model/fs_firmware_loader.rst b/roms/u-boot/doc/develop/driver-model/fs_firmware_loader.rst new file mode 100644 index 000000000..a44708cb4 --- /dev/null +++ b/roms/u-boot/doc/develop/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/roms/u-boot/doc/develop/driver-model/i2c-howto.rst b/roms/u-boot/doc/develop/driver-model/i2c-howto.rst new file mode 100644 index 000000000..27e7440cd --- /dev/null +++ b/roms/u-boot/doc/develop/driver-model/i2c-howto.rst @@ -0,0 +1,56 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +How to port an I2C driver to driver model +========================================= + +Over half of the I2C drivers have been converted as at November 2016. These +ones remain: + + * adi_i2c + * davinci_i2c + * fti2c010 + * ihs_i2c + * kona_i2c + * lpc32xx_i2c + * pca9564_i2c + * ppc4xx_i2c + * rcar_i2c + * sh_i2c + * soft_i2c + * zynq_i2c + +The deadline for this work is the end of June 2017. If no one steps +forward to convert these, at some point there may come a patch to remove them! + +Here is a suggested approach for converting your I2C driver over to driver +model. Please feel free to update this file with your ideas and suggestions. + +- #ifdef out all your own I2C driver code (#if !CONFIG_IS_ENABLED(DM_I2C)) +- Define CONFIG_DM_I2C for your board, vendor or architecture +- If the board does not already use driver model, you need CONFIG_DM also +- Your board should then build, but will not work fully since there will be + no I2C driver +- Add the U_BOOT_DRIVER piece at the end (e.g. copy tegra_i2c.c for example) +- Add a private struct for the driver data - avoid using static variables +- Implement each of the driver methods, perhaps by calling your old methods +- You may need to adjust the function parameters so that the old and new + implementations can share most of the existing code +- If you convert all existing users of the driver, remove the pre-driver-model + code + +In terms of patches a conversion series typically has these patches: +- clean up / prepare the driver for conversion +- add driver model code +- convert at least one existing board to use driver model serial +- (if no boards remain that don't use driver model) remove the old code + +This may be a good time to move your board to use device tree also. Mostly +this involves these steps: + +- define CONFIG_OF_CONTROL and CONFIG_OF_SEPARATE +- add your device tree files to arch/<arch>/dts +- update the Makefile there +- Add stdout-path to your /chosen device tree node if it is not already there +- build and get u-boot-dtb.bin so you can test it +- Your drivers can now use device tree +- For device tree in SPL, define CONFIG_SPL_OF_CONTROL diff --git a/roms/u-boot/doc/develop/driver-model/index.rst b/roms/u-boot/doc/develop/driver-model/index.rst new file mode 100644 index 000000000..7366ef818 --- /dev/null +++ b/roms/u-boot/doc/develop/driver-model/index.rst @@ -0,0 +1,31 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +Driver Model +============ + +The following holds information on the U-Boot device driver framework: +driver-model, including the design details of itself and several driver +subsystems + +.. toctree:: + :maxdepth: 2 + + bind + debugging + design + ethernet + fdt-fixup + fs_firmware_loader + i2c-howto + livetree + migration + nvme + of-plat + pci-info + pmic-framework + remoteproc-framework + serial-howto + soc-framework + spi-howto + usb-info + virtio diff --git a/roms/u-boot/doc/develop/driver-model/livetree.rst b/roms/u-boot/doc/develop/driver-model/livetree.rst new file mode 100644 index 000000000..9f654f3b8 --- /dev/null +++ b/roms/u-boot/doc/develop/driver-model/livetree.rst @@ -0,0 +1,286 @@ +.. SPDX-License-Identifier: GPL-2.0+ +.. sectionauthor:: Simon Glass <sjg@chromium.org> + +Live Device Tree +================ + + +Introduction +------------ + +Traditionally U-Boot has used a 'flat' device tree. This means that it +reads directly from the device tree binary structure. It is called a flat +device tree because nodes are listed one after the other, with the +hierarchy detected by tags in the format. + +This document describes U-Boot's support for a 'live' device tree, meaning +that the tree is loaded into a hierarchical data structure within U-Boot. + + +Motivation +---------- + +The flat device tree has several advantages: + +- it is the format produced by the device tree compiler, so no translation + is needed + +- it is fairly compact (e.g. there is no need for pointers) + +- it is accessed by the libfdt library, which is well tested and stable + + +However the flat device tree does have some limitations. Adding new +properties can involve copying large amounts of data around to make room. +The overall tree has a fixed maximum size so sometimes the tree must be +rebuilt in a new location to create more space. Even if not adding new +properties or nodes, scanning the tree can be slow. For example, finding +the parent of a node is a slow process. Reading from nodes involves a +small amount parsing which takes a little time. + +Driver model scans the entire device tree sequentially on start-up which +avoids the worst of the flat tree's limitations. But if the tree is to be +modified at run-time, a live tree is much faster. Even if no modification +is necessary, parsing the tree once and using a live tree from then on +seems to save a little time. + + +Implementation +-------------- + +In U-Boot a live device tree ('livetree') is currently supported only +after relocation. Therefore we need a mechanism to specify a device +tree node regardless of whether it is in the flat tree or livetree. + +The 'ofnode' type provides this. An ofnode can point to either a flat tree +node (when the live tree node is not yet set up) or a livetree node. The +caller of an ofnode function does not need to worry about these details. + +The main users of the information in a device tree are drivers. These have +a 'struct udevice \*' which is attached to a device tree node. Therefore it +makes sense to be able to read device tree properties using the +'struct udevice \*', rather than having to obtain the ofnode first. + +The 'dev_read\_...()' interface provides this. It allows properties to be +easily read from the device tree using only a device pointer. Under the +hood it uses ofnode so it works with both flat and live device trees. + + +Enabling livetree +----------------- + +CONFIG_OF_LIVE enables livetree. When this option is enabled, the flat +tree will be used in SPL and before relocation in U-Boot proper. Just +before relocation a livetree is built, and this is used for U-Boot proper +after relocation. + +Most checks for livetree use CONFIG_IS_ENABLED(OF_LIVE). This means that +for SPL, the CONFIG_SPL_OF_LIVE option is checked. At present this does +not exist, since SPL does not support livetree. + + +Porting drivers +--------------- + +Many existing drivers use the fdtdec interface to read device tree +properties. This only works with a flat device tree. The drivers should be +converted to use the dev_read_() interface. + +For example, the old code may be like this: + +.. code-block:: c + + struct udevice *bus; + const void *blob = gd->fdt_blob; + int node = dev_of_offset(bus); + + i2c_bus->regs = (struct i2c_ctlr *)devfdt_get_addr(dev); + plat->frequency = fdtdec_get_int(blob, node, "spi-max-frequency", 500000); + +The new code is: + +.. code-block:: c + + struct udevice *bus; + + i2c_bus->regs = (struct i2c_ctlr *)dev_read_addr(dev); + plat->frequency = dev_read_u32_default(bus, "spi-max-frequency", 500000); + +The dev_read\_...() interface is more convenient and works with both the +flat and live device trees. See include/dm/read.h for a list of functions. + +Where properties must be read from sub-nodes or other nodes, you must fall +back to using ofnode. For example, for old code like this: + +.. code-block:: c + + const void *blob = gd->fdt_blob; + int subnode; + + fdt_for_each_subnode(subnode, blob, dev_of_offset(dev)) { + freq = fdtdec_get_int(blob, node, "spi-max-frequency", 500000); + ... + } + +you should use: + +.. code-block:: c + + ofnode subnode; + + ofnode_for_each_subnode(subnode, dev_ofnode(dev)) { + freq = ofnode_read_u32(node, "spi-max-frequency", 500000); + ... + } + + +Useful ofnode functions +----------------------- + +The internal data structures of the livetree are defined in include/dm/of.h : + + :struct device_node: holds information about a device tree node + :struct property: holds information about a property within a node + +Nodes have pointers to their first property, their parent, their first child +and their sibling. This allows nodes to be linked together in a hierarchical +tree. + +Properties have pointers to the next property. This allows all properties of +a node to be linked together in a chain. + +It should not be necessary to use these data structures in normal code. In +particular, you should refrain from using functions which access the livetree +directly, such as of_read_u32(). Use ofnode functions instead, to allow your +code to work with a flat tree also. + +Some conversion functions are used internally. Generally these are not needed +for driver code. Note that they will not work if called in the wrong context. +For example it is invalid to call ofnode_to_no() when a flat tree is being +used. Similarly it is not possible to call ofnode_to_offset() on a livetree +node. + +ofnode_to_np(): + converts ofnode to struct device_node * +ofnode_to_offset(): + converts ofnode to offset + +no_to_ofnode(): + converts node pointer to ofnode +offset_to_ofnode(): + converts offset to ofnode + + +Other useful functions: + +of_live_active(): + returns true if livetree is in use, false if flat tree +ofnode_valid(): + return true if a given node is valid +ofnode_is_np(): + returns true if a given node is a livetree node +ofnode_equal(): + compares two ofnodes +ofnode_null(): + returns a null ofnode (for which ofnode_valid() returns false) + + +Phandles +-------- + +There is full phandle support for live tree. All functions make use of +struct ofnode_phandle_args, which has an ofnode within it. This supports both +livetree and flat tree transparently. See for example +ofnode_parse_phandle_with_args(). + + +Reading addresses +----------------- + +You should use dev_read_addr() and friends to read addresses from device-tree +nodes. + + +fdtdec +------ + +The existing fdtdec interface will eventually be retired. Please try to avoid +using it in new code. + + +Modifying the livetree +---------------------- + +This is not currently supported. Once implemented it should provide a much +more efficient implementation for modification of the device tree than using +the flat tree. + + +Internal implementation +----------------------- + +The dev_read\_...() functions have two implementations. When +CONFIG_DM_DEV_READ_INLINE is enabled, these functions simply call the ofnode +functions directly. This is useful when livetree is not enabled. The ofnode +functions call ofnode_is_np(node) which will always return false if livetree +is disabled, just falling back to flat tree code. + +This optimisation means that without livetree enabled, the dev_read\_...() and +ofnode interfaces do not noticeably add to code size. + +The CONFIG_DM_DEV_READ_INLINE option defaults to enabled when livetree is +disabled. + +Most livetree code comes directly from Linux and is modified as little as +possible. This is deliberate since this code is fairly stable and does what +we want. Some features (such as get/put) are not supported. Internal macros +take care of removing these features silently. + +Within the of_access.c file there are pointers to the alias node, the chosen +node and the stdout-path alias. + + +Errors +------ + +With a flat device tree, libfdt errors are returned (e.g. -FDT_ERR_NOTFOUND). +For livetree normal 'errno' errors are returned (e.g. -ENOTFOUND). At present +the ofnode and dev_read\_...() functions return either one or other type of +error. This is clearly not desirable. Once tests are added for all the +functions this can be tidied up. + + +Adding new access functions +--------------------------- + +Adding a new function for device-tree access involves the following steps: + + - Add two dev_read() functions: + - inline version in the read.h header file, which calls an ofnode function + - standard version in the read.c file (or perhaps another file), which + also calls an ofnode function + + The implementations of these functions can be the same. The purpose + of the inline version is purely to reduce code size impact. + + - Add an ofnode function. This should call ofnode_is_np() to work out + whether a livetree or flat tree is used. For the livetree it should + call an of\_...() function. For the flat tree it should call an + fdt\_...() function. The livetree version will be optimised out at + compile time if livetree is not enabled. + + - Add an of\_...() function for the livetree implementation. If a similar + function is available in Linux, the implementation should be taken + from there and modified as little as possible (generally not at all). + + +Future work +----------- + +Live tree support was introduced in U-Boot 2017.07. There is still quite a bit +of work to do to flesh this out: + +- tests for all access functions +- support for livetree modification +- addition of more access functions as needed +- support for livetree in SPL and before relocation (if desired) diff --git a/roms/u-boot/doc/develop/driver-model/migration.rst b/roms/u-boot/doc/develop/driver-model/migration.rst new file mode 100644 index 000000000..8d0bb7635 --- /dev/null +++ b/roms/u-boot/doc/develop/driver-model/migration.rst @@ -0,0 +1,109 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +Migration Schedule +================== + +U-Boot has been migrating to a new driver model since its introduction in +2014. This file describes the schedule for deprecation of pre-driver-model +features. + +CONFIG_DM +--------- + +* Status: In progress +* Deadline: 2020.01 + +Starting with the 2010.01 release CONFIG_DM will be enabled for all boards. +This does not concern CONFIG_DM_SPL and CONFIG_DM_TPL. The conversion date for +these configuration items still needs to be defined. + +CONFIG_DM_MMC +------------- + +* Status: In progress +* Deadline: 2019.04 + +The subsystem itself has been converted and maintainers should submit patches +switching over to using CONFIG_DM_MMC and other base driver model options in +time for inclusion in the 2019.04 rerelease. + +CONFIG_DM_USB +------------- + +* Status: In progress +* Deadline: 2019.07 + +The subsystem itself has been converted along with many of the host controller +and maintainers should submit patches switching over to using CONFIG_DM_USB and +other base driver model options in time for inclusion in the 2019.07 rerelease. + +CONFIG_SATA +----------- + +* Status: In progress +* Deadline: 2019.07 + +The subsystem itself has been converted along with many of the host controller +and maintainers should submit patches switching over to using CONFIG_AHCI and +other base driver model options in time for inclusion in the 2019.07 rerelease. + +CONFIG_BLK +---------- + +* Status: In progress +* Deadline: 2019.07 + +In concert with maintainers migrating their block device usage to the +appropriate DM driver, CONFIG_BLK needs to be set as well. The final deadline +here coincides with the final deadline for migration of the various block +subsystems. At this point we will be able to audit and correct the logic in +Kconfig around using CONFIG_PARTITIONS and CONFIG_HAVE_BLOCK_DEVICE and make +use of CONFIG_BLK / CONFIG_SPL_BLK as needed. + +CONFIG_DM_SPI / CONFIG_DM_SPI_FLASH +----------------------------------- + +Board Maintainers should submit the patches for enabling DM_SPI and DM_SPI_FLASH +to move the migration with in the deadline. + +Partially converted:: + + drivers/spi/fsl_espi.c + drivers/spi/mxc_spi.c + drivers/spi/sh_qspi.c + +* Status: In progress +* Deadline: 2019.07 + +CONFIG_DM_PCI +------------- +Deadline: 2019.07 + +The PCI subsystem has supported driver model since mid 2015. Maintainers should +submit patches switching over to using CONFIG_DM_PCI and other base driver +model options in time for inclusion in the 2019.07 release. + + +CONFIG_DM_VIDEO +--------------- +Deadline: 2019.07 + +The video subsystem has supported driver model since early 2016. Maintainers +should submit patches switching over to using CONFIG_DM_VIDEO and other base +driver model options in time for inclusion in the 2019.07 release. + +CONFIG_DM_ETH +------------- +Deadline: 2020.07 + +The network subsystem has supported the driver model since early 2015. +Maintainers should submit patches switching over to using CONFIG_DM_ETH and +other base driver model options in time for inclusion in the 2020.07 release. + +CONFIG_DM_I2C +------------- +Deadline: 2021.10 + +The I2C subsystem has supported the driver model since early 2015. +Maintainers should submit patches switching over to using CONFIG_DM_I2C and +other base driver model options in time for inclusion in the 2021.10 release. diff --git a/roms/u-boot/doc/develop/driver-model/nvme.rst b/roms/u-boot/doc/develop/driver-model/nvme.rst new file mode 100644 index 000000000..736c0a063 --- /dev/null +++ b/roms/u-boot/doc/develop/driver-model/nvme.rst @@ -0,0 +1,97 @@ +.. SPDX-License-Identifier: GPL-2.0+ +.. Copyright (C) 2017 NXP Semiconductors +.. Copyright (C) 2017 Bin Meng <bmeng.cn@gmail.com> + +NVMe Support +============ + +What is NVMe +------------ + +NVM Express (NVMe) is a register level interface that allows host software to +communicate with a non-volatile memory subsystem. This interface is optimized +for enterprise and client solid state drives, typically attached to the PCI +express interface. It is a scalable host controller interface designed to +address the needs of enterprise and client systems that utilize PCI express +based solid state drives (SSD). The interface provides optimized command +submission and completion paths. It includes support for parallel operation by +supporting up to 64K I/O queues with up to 64K commands per I/O queue. + +The device is comprised of some number of controllers, where each controller +is comprised of some number of namespaces, where each namespace is comprised +of some number of logical blocks. A namespace is a quantity of non-volatile +memory that is formatted into logical blocks. An NVMe namespace is equivalent +to a SCSI LUN. Each namespace is operated as an independent "device". + +How it works +------------ +There is an NVMe uclass driver (driver name "nvme"), an NVMe host controller +driver (driver name "nvme") and an NVMe namespace block driver (driver name +"nvme-blk"). The host controller driver is supposed to probe the hardware and +do necessary initialization to put the controller into a ready state at which +it is able to scan all available namespaces attached to it. Scanning namespace +is triggered by the NVMe uclass driver and the actual work is done in the NVMe +namespace block driver. + +Status +------ +It only support basic block read/write functions in the NVMe driver. + +Config options +-------------- +CONFIG_NVME Enable NVMe device support +CONFIG_CMD_NVME Enable basic NVMe commands + +Usage in U-Boot +--------------- +To use an NVMe hard disk from U-Boot shell, a 'nvme scan' command needs to +be executed for all NVMe hard disks attached to the NVMe controller to be +identified. + +To list all of the NVMe hard disks, try: + +.. code-block:: none + + => nvme info + Device 0: Vendor: 0x8086 Rev: 8DV10131 Prod: CVFT535600LS400BGN + Type: Hard Disk + Capacity: 381554.0 MB = 372.6 GB (781422768 x 512) + +and print out detailed information for controller and namespaces via: + +.. code-block:: none + + => nvme detail + +Raw block read/write to can be done via the 'nvme read/write' commands: + +.. code-block:: none + + => nvme read a0000000 0 11000 + + => tftp 80000000 /tftpboot/kernel.itb + => nvme write 80000000 0 11000 + +Of course, file system command can be used on the NVMe hard disk as well: + +.. code-block:: none + + => fatls nvme 0:1 + 32376967 kernel.itb + 22929408 100m + + 2 file(s), 0 dir(s) + + => fatload nvme 0:1 a0000000 /kernel.itb + => bootm a0000000 + +Testing NVMe with QEMU x86 +-------------------------- +QEMU supports NVMe emulation and we can test NVMe driver with QEMU x86 running +U-Boot. Please see README.x86 for how to build u-boot.rom image for QEMU x86. + +Example command line to call QEMU x86 below with emulated NVMe device: + +.. code-block:: bash + + $ ./qemu-system-i386 -drive file=nvme.img,if=none,id=drv0 -device nvme,drive=drv0,serial=QEMUNVME0001 -bios u-boot.rom diff --git a/roms/u-boot/doc/develop/driver-model/of-plat.rst b/roms/u-boot/doc/develop/driver-model/of-plat.rst new file mode 100644 index 000000000..74f193247 --- /dev/null +++ b/roms/u-boot/doc/develop/driver-model/of-plat.rst @@ -0,0 +1,913 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +Compiled-in Device Tree / Platform Data +======================================= + + +Introduction +------------ + +Device tree is the standard configuration method in U-Boot. It is used to +define what devices are in the system and provide configuration information +to these devices. + +The overhead of adding devicetree access to U-Boot is fairly modest, +approximately 3KB on Thumb 2 (plus the size of the DT itself). This means +that in most cases it is best to use devicetree for configuration. + +However there are some very constrained environments where U-Boot needs to +work. These include SPL with severe memory limitations. For example, some +SoCs require a 16KB SPL image which must include a full MMC stack. In this +case the overhead of devicetree access may be too great. + +It is possible to create platform data manually by defining C structures +for it, and reference that data in a `U_BOOT_DRVINFO()` declaration. This +bypasses the use of devicetree completely, effectively creating a parallel +configuration mechanism. But it is an available option for SPL. + +As an alternative, the 'of-platdata' feature is provided. This converts the +devicetree contents into C code which can be compiled into the SPL binary. +This saves the 3KB of code overhead and perhaps a few hundred more bytes due +to more efficient storage of the data. + + +How it works +------------ + +The feature is enabled by CONFIG OF_PLATDATA. This is only available in +SPL/TPL and should be tested with: + +.. code-block:: c + + #if CONFIG_IS_ENABLED(OF_PLATDATA) + +A tool called 'dtoc' converts a devicetree file either into a set of +struct declarations, one for each compatible node, and a set of +`U_BOOT_DRVINFO()` declarations along with the actual platform data for each +device. As an example, consider this MMC node: + +.. code-block:: none + + sdmmc: dwmmc@ff0c0000 { + compatible = "rockchip,rk3288-dw-mshc"; + clock-freq-min-max = <400000 150000000>; + clocks = <&cru HCLK_SDMMC>, <&cru SCLK_SDMMC>, + <&cru SCLK_SDMMC_DRV>, <&cru SCLK_SDMMC_SAMPLE>; + clock-names = "biu", "ciu", "ciu_drv", "ciu_sample"; + fifo-depth = <0x100>; + interrupts = <GIC_SPI 32 IRQ_TYPE_LEVEL_HIGH>; + reg = <0xff0c0000 0x4000>; + bus-width = <4>; + cap-mmc-highspeed; + cap-sd-highspeed; + card-detect-delay = <200>; + disable-wp; + num-slots = <1>; + pinctrl-names = "default"; + pinctrl-0 = <&sdmmc_clk>, <&sdmmc_cmd>, <&sdmmc_cd>, <&sdmmc_bus4>; + vmmc-supply = <&vcc_sd>; + status = "okay"; + u-boot,dm-pre-reloc; + }; + + +Some of these properties are dropped by U-Boot under control of the +CONFIG_OF_SPL_REMOVE_PROPS option. The rest are processed. This will produce +the following C struct declaration: + +.. code-block:: c + + struct dtd_rockchip_rk3288_dw_mshc { + fdt32_t bus_width; + bool cap_mmc_highspeed; + bool cap_sd_highspeed; + fdt32_t card_detect_delay; + fdt32_t clock_freq_min_max[2]; + struct phandle_1_arg clocks[4]; + bool disable_wp; + fdt32_t fifo_depth; + fdt32_t interrupts[3]; + fdt32_t num_slots; + fdt32_t reg[2]; + fdt32_t vmmc_supply; + }; + +and the following device declarations: + +.. code-block:: c + + /* Node /clock-controller@ff760000 index 0 */ + ... + + /* Node /dwmmc@ff0c0000 index 2 */ + static struct dtd_rockchip_rk3288_dw_mshc dtv_dwmmc_at_ff0c0000 = { + .fifo_depth = 0x100, + .cap_sd_highspeed = true, + .interrupts = {0x0, 0x20, 0x4}, + .clock_freq_min_max = {0x61a80, 0x8f0d180}, + .vmmc_supply = 0xb, + .num_slots = 0x1, + .clocks = {{0, 456}, + {0, 68}, + {0, 114}, + {0, 118}}, + .cap_mmc_highspeed = true, + .disable_wp = true, + .bus_width = 0x4, + .u_boot_dm_pre_reloc = true, + .reg = {0xff0c0000, 0x4000}, + .card_detect_delay = 0xc8, + }; + + U_BOOT_DRVINFO(dwmmc_at_ff0c0000) = { + .name = "rockchip_rk3288_dw_mshc", + .plat = &dtv_dwmmc_at_ff0c0000, + .plat_size = sizeof(dtv_dwmmc_at_ff0c0000), + .parent_idx = -1, + }; + +The device is then instantiated at run-time and the platform data can be +accessed using: + +.. code-block:: c + + struct udevice *dev; + struct dtd_rockchip_rk3288_dw_mshc *plat = dev_get_plat(dev); + +This avoids the code overhead of converting the devicetree data to +platform data in the driver. The `of_to_plat()` method should +therefore do nothing in such a driver. + +Note that for the platform data to be matched with a driver, the 'name' +property of the `U_BOOT_DRVINFO()` declaration has to match a driver declared +via `U_BOOT_DRIVER()`. This effectively means that a `U_BOOT_DRIVER()` with a +'name' corresponding to the devicetree 'compatible' string (after converting +it to a valid name for C) is needed, so a dedicated driver is required for +each 'compatible' string. + +In order to make this a bit more flexible, the `DM_DRIVER_ALIAS()` macro can be +used to declare an alias for a driver name, typically a 'compatible' string. +This macro produces no code, but is used by dtoc tool. It must be located in the +same file as its associated driver, ideally just after it. + +The parent_idx is the index of the parent `driver_info` structure within its +linker list (instantiated by the `U_BOOT_DRVINFO()` macro). This is used to +support `dev_get_parent()`. + +During the build process dtoc parses both `U_BOOT_DRIVER()` and +`DM_DRIVER_ALIAS()` to build a list of valid driver names and driver aliases. +If the 'compatible' string used for a device does not not match a valid driver +name, it will be checked against the list of driver aliases in order to get the +right driver name to use. If in this step there is no match found a warning is +issued to avoid run-time failures. + +Where a node has multiple compatible strings, dtoc generates a `#define` to +make them equivalent, e.g.: + +.. code-block:: c + + #define dtd_rockchip_rk3299_dw_mshc dtd_rockchip_rk3288_dw_mshc + + +Converting of-platdata to a useful form +--------------------------------------- + +Of course it would be possible to use the of-platdata directly in your driver +whenever configuration information is required. However this means that the +driver will not be able to support devicetree, since the of-platdata +structure is not available when devicetree is used. It would make no sense +to use this structure if devicetree were available, since the structure has +all the limitations metioned in caveats below. + +Therefore it is recommended that the of-platdata structure should be used +only in the `probe()` method of your driver. It cannot be used in the +`of_to_plat()` method since this is not called when platform data is +already present. + + +How to structure your driver +---------------------------- + +Drivers should always support devicetree as an option. The of-platdata +feature is intended as a add-on to existing drivers. + +Your driver should convert the plat struct in its `probe()` method. The +existing devicetree decoding logic should be kept in the +`of_to_plat()` method and wrapped with `#if`. + +For example: + +.. code-block:: c + + #include <dt-structs.h> + + struct mmc_plat { + #if CONFIG_IS_ENABLED(OF_PLATDATA) + /* Put this first since driver model will copy the data here */ + struct dtd_mmc dtplat; + #endif + /* + * Other fields can go here, to be filled in by decoding from + * the devicetree (or the C structures when of-platdata is used). + */ + int fifo_depth; + }; + + static int mmc_of_to_plat(struct udevice *dev) + { + #if !CONFIG_IS_ENABLED(OF_PLATDATA) + /* Decode the devicetree data */ + struct mmc_plat *plat = dev_get_plat(dev); + const void *blob = gd->fdt_blob; + int node = dev_of_offset(dev); + + plat->fifo_depth = fdtdec_get_int(blob, node, "fifo-depth", 0); + #endif + + return 0; + } + + static int mmc_probe(struct udevice *dev) + { + struct mmc_plat *plat = dev_get_plat(dev); + + #if CONFIG_IS_ENABLED(OF_PLATDATA) + /* Decode the of-platdata from the C structures */ + struct dtd_mmc *dtplat = &plat->dtplat; + + plat->fifo_depth = dtplat->fifo_depth; + #endif + /* Set up the device from the plat data */ + writel(plat->fifo_depth, ...) + } + + static const struct udevice_id mmc_ids[] = { + { .compatible = "vendor,mmc" }, + { } + }; + + U_BOOT_DRIVER(mmc_drv) = { + .name = "mmc_drv", + .id = UCLASS_MMC, + .of_match = mmc_ids, + .of_to_plat = mmc_of_to_plat, + .probe = mmc_probe, + .priv_auto = sizeof(struct mmc_priv), + .plat_auto = sizeof(struct mmc_plat), + }; + + DM_DRIVER_ALIAS(mmc_drv, vendor_mmc) /* matches compatible string */ + +Note that `struct mmc_plat` is defined in the C file, not in a header. This +is to avoid needing to include dt-structs.h in a header file. The idea is to +keep the use of each of-platdata struct to the smallest possible code area. +There is just one driver C file for each struct, that can convert from the +of-platdata struct to the standard one used by the driver. + +In the case where SPL_OF_PLATDATA is enabled, `plat_auto` is +still used to allocate space for the platform data. This is different from +the normal behaviour and is triggered by the use of of-platdata (strictly +speaking it is a non-zero `plat_size` which triggers this). + +The of-platdata struct contents is copied from the C structure data to the +start of the newly allocated area. In the case where devicetree is used, +the platform data is allocated, and starts zeroed. In this case the +`of_to_plat()` method should still set up the platform data (and the +of-platdata struct will not be present). + +SPL must use either of-platdata or devicetree. Drivers cannot use both at +the same time, but they must support devicetree. Supporting of-platdata is +optional. + +The devicetree becomes inaccessible when CONFIG_SPL_OF_PLATDATA is enabled, +since the devicetree access code is not compiled in. A corollary is that +a board can only move to using of-platdata if all the drivers it uses support +it. There would be little point in having some drivers require the device +tree data, since then libfdt would still be needed for those drivers and +there would be no code-size benefit. + + +Build-time instantiation +------------------------ + +Even with of-platdata there is a fair amount of code required in driver model. +It is possible to have U-Boot handle the instantiation of devices at build-time, +so avoiding the need for the `device_bind()` code and some parts of +`device_probe()`. + +The feature is enabled by CONFIG_OF_PLATDATA_INST. + +Here is an example device, as generated by dtoc:: + + /* + * Node /serial index 6 + * driver sandbox_serial parent root_driver + */ + + #include <asm/serial.h> + struct sandbox_serial_plat __attribute__ ((section (".priv_data"))) + _sandbox_serial_plat_serial = { + .dtplat = { + .sandbox_text_colour = "cyan", + }, + }; + #include <asm/serial.h> + u8 _sandbox_serial_priv_serial[sizeof(struct sandbox_serial_priv)] + __attribute__ ((section (".priv_data"))); + #include <serial.h> + u8 _sandbox_serial_uc_priv_serial[sizeof(struct serial_dev_priv)] + __attribute__ ((section (".priv_data"))); + + DM_DEVICE_INST(serial) = { + .driver = DM_DRIVER_REF(sandbox_serial), + .name = "sandbox_serial", + .plat_ = &_sandbox_serial_plat_serial, + .priv_ = _sandbox_serial_priv_serial, + .uclass = DM_UCLASS_REF(serial), + .uclass_priv_ = _sandbox_serial_uc_priv_serial, + .uclass_node = { + .prev = &DM_UCLASS_REF(serial)->dev_head, + .next = &DM_UCLASS_REF(serial)->dev_head, + }, + .child_head = { + .prev = &DM_DEVICE_REF(serial)->child_head, + .next = &DM_DEVICE_REF(serial)->child_head, + }, + .sibling_node = { + .prev = &DM_DEVICE_REF(i2c_at_0)->sibling_node, + .next = &DM_DEVICE_REF(spl_test)->sibling_node, + }, + .seq_ = 0, + }; + +Here is part of the driver, for reference:: + + static const struct udevice_id sandbox_serial_ids[] = { + { .compatible = "sandbox,serial" }, + { } + }; + + U_BOOT_DRIVER(sandbox_serial) = { + .name = "sandbox_serial", + .id = UCLASS_SERIAL, + .of_match = sandbox_serial_ids, + .of_to_plat = sandbox_serial_of_to_plat, + .plat_auto = sizeof(struct sandbox_serial_plat), + .priv_auto = sizeof(struct sandbox_serial_priv), + .probe = sandbox_serial_probe, + .remove = sandbox_serial_remove, + .ops = &sandbox_serial_ops, + .flags = DM_FLAG_PRE_RELOC, + }; + + +The `DM_DEVICE_INST()` macro declares a struct udevice so you can see that the +members are from that struct. The private data is declared immediately above, +as `_sandbox_serial_priv_serial`, so there is no need for run-time memory +allocation. The #include lines are generated as well, since dtoc searches the +U-Boot source code for the definition of `struct sandbox_serial_priv` and adds +the relevant header so that the code will compile without errors. + +The `plat_` member is set to the dtv data which is declared immediately above +the device. This is similar to how it would look without of-platdata-inst, but +node that the `dtplat` member inside is part of the wider +`_sandbox_serial_plat_serial` struct. This is because the driver declares its +own platform data, and the part generated by dtoc can only be a portion of it. +The `dtplat` part is always first in the struct. If the device has no +`.plat_auto` field, then a simple dtv struct can be used as with this example:: + + static struct dtd_sandbox_clk dtv_clk_sbox = { + .assigned_clock_rates = 0x141, + .assigned_clocks = {0x7, 0x3}, + }; + + #include <asm/clk.h> + u8 _sandbox_clk_priv_clk_sbox[sizeof(struct sandbox_clk_priv)] + __attribute__ ((section (".priv_data"))); + + DM_DEVICE_INST(clk_sbox) = { + .driver = DM_DRIVER_REF(sandbox_clk), + .name = "sandbox_clk", + .plat_ = &dtv_clk_sbox, + +Here is part of the driver, for reference:: + + static const struct udevice_id sandbox_clk_ids[] = { + { .compatible = "sandbox,clk" }, + { } + }; + + U_BOOT_DRIVER(sandbox_clk) = { + .name = "sandbox_clk", + .id = UCLASS_CLK, + .of_match = sandbox_clk_ids, + .ops = &sandbox_clk_ops, + .probe = sandbox_clk_probe, + .priv_auto = sizeof(struct sandbox_clk_priv), + }; + + +You can see that `dtv_clk_sbox` just has the devicetree contents and there is +no need for the `dtplat` separation, since the driver has no platform data of +its own, besides that provided by the devicetree (i.e. no `.plat_auto` field). + +The doubly linked lists are handled by explicitly declaring the value of each +node, as you can see with the `.prev` and `.next` values in the example above. +Since dtoc knows the order of devices it can link them into the appropriate +lists correctly. + +One of the features of driver model is the ability for a uclass to have a +small amount of private data for each device in that uclass. This is used to +provide a generic data structure that the uclass can use for all devices, thus +allowing generic features to be implemented in common code. An example is I2C, +which stores the bus speed there. + +Similarly, parent devices can have data associated with each of their children. +This is used to provide information common to all children of a particular bus. +For an I2C bus, this is used to store the I2C address of each child on the bus. + +This is all handled automatically by dtoc:: + + #include <asm/i2c.h> + u8 _sandbox_i2c_priv_i2c_at_0[sizeof(struct sandbox_i2c_priv)] + __attribute__ ((section (".priv_data"))); + #include <i2c.h> + u8 _sandbox_i2c_uc_priv_i2c_at_0[sizeof(struct dm_i2c_bus)] + __attribute__ ((section (".priv_data"))); + + DM_DEVICE_INST(i2c_at_0) = { + .driver = DM_DRIVER_REF(sandbox_i2c), + .name = "sandbox_i2c", + .plat_ = &dtv_i2c_at_0, + .priv_ = _sandbox_i2c_priv_i2c_at_0, + .uclass = DM_UCLASS_REF(i2c), + .uclass_priv_ = _sandbox_i2c_uc_priv_i2c_at_0, + ... + +Part of driver, for reference:: + + static const struct udevice_id sandbox_i2c_ids[] = { + { .compatible = "sandbox,i2c" }, + { } + }; + + U_BOOT_DRIVER(sandbox_i2c) = { + .name = "sandbox_i2c", + .id = UCLASS_I2C, + .of_match = sandbox_i2c_ids, + .ops = &sandbox_i2c_ops, + .priv_auto = sizeof(struct sandbox_i2c_priv), + }; + +Part of I2C uclass, for reference:: + + UCLASS_DRIVER(i2c) = { + .id = UCLASS_I2C, + .name = "i2c", + .flags = DM_UC_FLAG_SEQ_ALIAS, + .post_bind = i2c_post_bind, + .pre_probe = i2c_pre_probe, + .post_probe = i2c_post_probe, + .per_device_auto = sizeof(struct dm_i2c_bus), + .per_child_plat_auto = sizeof(struct dm_i2c_chip), + .child_post_bind = i2c_child_post_bind, + }; + +Here, `_sandbox_i2c_uc_priv_i2c_at_0` is required by the uclass but is declared +in the device, as required by driver model. The required header file is included +so that the code will compile without errors. A similar mechanism is used for +child devices, but is not shown by this example. + +It would not be that useful to avoid binding devices but still need to allocate +uclasses at runtime. So dtoc generates uclass instances as well:: + + struct list_head uclass_head = { + .prev = &DM_UCLASS_REF(serial)->sibling_node, + .next = &DM_UCLASS_REF(clk)->sibling_node, + }; + + DM_UCLASS_INST(clk) = { + .uc_drv = DM_UCLASS_DRIVER_REF(clk), + .sibling_node = { + .prev = &uclass_head, + .next = &DM_UCLASS_REF(i2c)->sibling_node, + }, + .dev_head = { + .prev = &DM_DEVICE_REF(clk_sbox)->uclass_node, + .next = &DM_DEVICE_REF(clk_fixed)->uclass_node, + }, + }; + +At the top is the list head. Driver model uses this on start-up, instead of +creating its own. + +Below that are a set of `DM_UCLASS_INST()` macros, each declaring a +`struct uclass`. The doubly linked lists work as for devices. + +All private data is placed into a `.priv_data` section so that it is contiguous +in the resulting output binary. + + +Indexes +------- + +U-Boot stores drivers, devices and many other things in linker_list structures. +These are sorted by name, so dtoc knows the order that they will appear when +the linker runs. Each driver_info / udevice is referenced by its index in the +linker_list array, called 'idx' in the code. + +When CONFIG_OF_PLATDATA_INST is enabled, idx is the udevice index, otherwise it +is the driver_info index. In either case, indexes are used to reference devices +using device_get_by_ofplat_idx(). This allows phandles to work as expected. + + +Phases +------ + +U-Boot operates in several phases, typically TPL, SPL and U-Boot proper. +The latter does not use dtoc. + +In some rare cases different drivers are used for two phases. For example, +in TPL it may not be necessary to use the full PCI subsystem, so a simple +driver can be used instead. + +This works in the build system simply by compiling in one driver or the +other (e.g. PCI driver + uclass for SPL; simple_bus for TPL). But dtoc has +no way of knowing which code is compiled in for which phase, since it does +not inspect Makefiles or dependency graphs. + +So to make this work for dtoc, we need to be able to explicitly mark +drivers with their phase. This is done by adding a macro to the driver:: + + /* code in tpl.c only compiled into TPL */ + U_BOOT_DRIVER(pci_x86) = { + .name = "pci_x86", + .id = UCLASS_SIMPLE_BUS, + .of_match = of_match_ptr(tpl_fake_pci_ids), + DM_PHASE(tpl) + }; + + + /* code in pci_x86.c compiled into SPL and U-Boot proper */ + U_BOOT_DRIVER(pci_x86) = { + .name = "pci_x86", + .id = UCLASS_PCI, + .of_match = pci_x86_ids, + .ops = &pci_x86_ops, + }; + + +Notice that the second driver has the same name but no DM_PHASE(), so it will be +used for SPL and U-Boot. + +Note also that this only affects the code generated by dtoc. You still need to +make sure that only the required driver is build into each phase. + + +Header files +------------ + +With OF_PLATDATA_INST, dtoc must include the correct header file in the +generated code for any structs that are used, so that the code will compile. +For example, if `struct ns16550_plat` is used, the code must include the +`ns16550.h` header file. + +Typically dtoc can detect the header file needed for a driver by looking +for the structs that it uses. For example, if a driver as a `.priv_auto` +that uses `struct ns16550_plat`, then dtoc can search header files for the +definition of that struct and use the file. + +In some cases, enums are used in drivers, typically with the `.data` field +of `struct udevice_id`. Since dtoc does not support searching for these, +you must use the `DM_HDR()` macro to tell dtoc which header to use. This works +as a macro included in the driver definition:: + + static const struct udevice_id apl_syscon_ids[] = { + { .compatible = "intel,apl-punit", .data = X86_SYSCON_PUNIT }, + { } + }; + + U_BOOT_DRIVER(intel_apl_punit) = { + .name = "intel_apl_punit", + .id = UCLASS_SYSCON, + .of_match = apl_syscon_ids, + .probe = apl_punit_probe, + DM_HEADER(<asm/cpu.h>) /* for X86_SYSCON_PUNIT */ + }; + + + +Caveats +------- + +There are various complications with this feature which mean it should only +be used when strictly necessary, i.e. in SPL with limited memory. Notable +caveats include: + + - Device tree does not describe data types. But the C code must define a + type for each property. These are guessed using heuristics which + are wrong in several fairly common cases. For example an 8-byte value + is considered to be a 2-item integer array, and is byte-swapped. A + boolean value that is not present means 'false', but cannot be + included in the structures since there is generally no mention of it + in the devicetree file. + + - Naming of nodes and properties is automatic. This means that they follow + the naming in the devicetree, which may result in C identifiers that + look a bit strange. + + - It is not possible to find a value given a property name. Code must use + the associated C member variable directly in the code. This makes + the code less robust in the face of devicetree changes. To avoid having + a second struct with similar members and names you need to explicitly + declare it as an alias with `DM_DRIVER_ALIAS()`. + + - The platform data is provided to drivers as a C structure. The driver + must use the same structure to access the data. Since a driver + normally also supports devicetree it must use `#ifdef` to separate + out this code, since the structures are only available in SPL. This could + be fixed fairly easily by making the structs available outside SPL, so + that `IS_ENABLED()` could be used. + + - With CONFIG_OF_PLATDATA_INST all binding happens at build-time, meaning + that (by default) it is not possible to call `device_bind()` from C code. + This means that all devices must have an associated devicetree node and + compatible string. For example if a GPIO device currently creates child + devices in its `bind()` method, it will not work with + CONFIG_OF_PLATDATA_INST. Arguably this is bad practice anyway and the + devicetree binding should be updated to declare compatible strings for + the child devices. It is possible to disable OF_PLATDATA_NO_BIND but this + is not recommended since it increases code size. + + +Internals +--------- + +Generated files +``````````````` + +When enabled, dtoc generates the following five files: + +include/generated/dt-decl.h (OF_PLATDATA_INST only) + Contains declarations for all drivers, devices and uclasses. This allows + any `struct udevice`, `struct driver` or `struct uclass` to be located by its + name + +include/generated/dt-structs-gen.h + Contains the struct definitions for the devicetree nodes that are used. This + is the same as without OF_PLATDATA_INST + +spl/dts/dt-plat.c (only with !OF_PLATDATA_INST) + Contains the `U_BOOT_DRVINFO()` declarations that U-Boot uses to bind devices + at start-up. See above for an example + +spl/dts/dt-device.c (only with OF_PLATDATA_INST) + Contains `DM_DEVICE_INST()` declarations for each device that can be used at + run-time. These are declared in the file along with any private/platform data + that they use. Every device has an idx, as above. Since each device must be + part of a double-linked list, the nodes are declared in the code as well. + +spl/dts/dt-uclass.c (only with OF_PLATDATA_INST) + Contains `DM_UCLASS_INST()` declarations for each uclass that can be used at + run-time. These are declared in the file along with any private data + associated with the uclass itself (the `.priv_auto` member). Since each + uclass must be part of a double-linked list, the nodes are declared in the + code as well. + +The dt-structs.h file includes the generated file +`(include/generated/dt-structs.h`) if CONFIG_SPL_OF_PLATDATA is enabled. +Otherwise (such as in U-Boot proper) these structs are not available. This +prevents them being used inadvertently. All usage must be bracketed with +`#if CONFIG_IS_ENABLED(OF_PLATDATA)`. + +The dt-plat.c file contains the device declarations and is is built in +spl/dt-plat.c. + + +CONFIG options +`````````````` + +Several CONFIG options are used to control the behaviour of of-platdata, all +available for both SPL and TPL: + +OF_PLATDATA + This is the main option which enables the of-platdata feature + +OF_PLATDATA_PARENT + This allows `device_get_parent()` to work. Without this, all devices exist as + direct children of the root node. This option is highly desirable (if not + always absolutely essential) for buses such as I2C. + +OF_PLATDATA_INST + This controls the instantiation of devices at build time. With it disabled, + only `U_BOOT_DRVINFO()` records are created, with U-Boot handling the binding + in `device_bind()` on start-up. With it enabled, only `DM_DEVICE_INST()` and + `DM_UCLASS_INST()` records are created, and `device_bind()` is not needed at + runtime. + +OF_PLATDATA_NO_BIND + This controls whether `device_bind()` is supported. It is enabled by default + with OF_PLATDATA_INST since code-size reduction is really the main point of + the feature. It can be disabled if needed but is not likely to be supported + in the long term. + +OF_PLATDATA_DRIVER_RT + This controls whether the `struct driver_rt` records are used by U-Boot. + Normally when a device is bound, U-Boot stores the device pointer in one of + these records. There is one for every `struct driver_info` in the system, + i.e. one for every device that is bound from those records. It provides a + way to locate a device in the code and is used by + `device_get_by_ofplat_idx()`. This option is always enabled with of-platdata, + provided OF_PLATDATA_INST is not. In that case the records are useless since + we don't have any `struct driver_info` records. + +OF_PLATDATA_RT + This controls whether the `struct udevice_rt` records are used by U-Boot. + It moves the updatable fields from `struct udevice` (currently only `flags`) + into a separate structure, allowing the records to be kept in read-only + memory. It is generally enabled if OF_PLATDATA_INST is enabled. This option + also controls whether the private data is used in situ, or first copied into + an allocated region. Again this is to allow the private data declared by + dtoc-generated code to be in read-only memory. Note that access to private + data must be done via accessor functions, such as `dev_get_priv()`, so that + the relocation is handled. + +READ_ONLY + This indicates that the data generated by dtoc should not be modified. Only + a few fields actually do get changed in U-Boot, such as device flags. This + option causes those to move into an allocated space (see OF_PLATDATA_RT). + Also, since updating doubly linked lists is generally impossible when some of + the nodes cannot be updated, OF_PLATDATA_NO_BIND is enabled. + +Data structures +``````````````` + +A few extra data structures are used with of-platdata: + +`struct udevice_rt` + Run-time information for devices. When OF_PLATDATA_RT is enabled, this holds + the flags for each device, so that `struct udevice` can remain unchanged by + U-Boot, and potentially reside in read-only memory. Access to flags is then + via functions like `dev_get_flags()` and `dev_or_flags()`. This data + structure is allocated on start-up, where the private data is also copied. + All flags values start at 0 and any changes are handled by `dev_or_flags()` + and `dev_bic_flags()`. It would be more correct for the flags to be set to + `DM_FLAG_BOUND`, or perhaps `DM_FLAG_BOUND | DM_FLAG_ALLOC_PDATA`, but since + there is no code to bind/unbind devices and no code to allocate/free + private data / platform data, it doesn't matter. + +`struct driver_rt` + Run-time information for `struct driver_info` records. When + OF_PLATDATA_DRIVER_RT is enabled, this holds a pointer to the device + created by each record. This is needed so that is it possible to locate a + device from C code. Specifically, the code can use `DM_DRVINFO_GET(name)` to + get a reference to a particular `struct driver_info`, with `name` being the + name of the devicetree node. This is very convenient. It is also fast, since + no searching or string comparison is needed. This data structure is + allocated on start-up, filled out by `device_bind()` and used by + `device_get_by_ofplat_idx()`. + +Other changes +````````````` + +Some other changes are made with of-platdata: + +Accessor functions + Accessing private / platform data via functions such as `dev_get_priv()` has + always been encouraged. With OF_PLATDATA_RT this is essential, since the + `priv_` and `plat_` (etc.) values point to the data generated by dtoc, not + the read-write copy that is sometimes made on start-up. Changing the + private / platform data pointers has always been discouraged (the API is + marked internal) but with OF_PLATDATA_RT this is not currently supported in + general, since it assumes that all such pointers point to the relocated data. + Note also that the renaming of struct members to have a trailing underscore + was partly done to make people aware that they should not be accessed + directly. + +`gd->uclass_root_s` + Normally U-Boot sets up the head of the uclass list here and makes + `gd->uclass_root` point to it. With OF_PLATDATA_INST, dtoc generates a + declaration of `uclass_head` in `dt-uclass.c` since it needs to link the + head node into the list. In that case, `gd->uclass_root_s` is not used and + U-Boot just makes `gd->uclass_root` point to `uclass_head`. + +`gd->dm_driver_rt` + This holds a pointer to a list of `struct driver_rt` records, one for each + `struct driver_info`. The list is in alphabetical order by the name used + in `U_BOOT_DRVINFO(name)` and indexed by idx, with the first record having + an index of 0. It is only used if OF_PLATDATA_INST is not enabled. This is + accessed via macros so that it can be used inside IS_ENABLED(), rather than + requiring #ifdefs in the C code when it is not present. + +`gd->dm_udevice_rt` + This holds a pointer to a list of `struct udevice_rt` records, one for each + `struct udevice`. The list is in alphabetical order by the name used + in `DM_DEVICE_INST(name)` (a C version of the devicetree node) and indexed by + idx, with the first record having an index of 0. It is only used if + OF_PLATDATA_INST is enabled. This is accessed via macros so that it can be + used inside `IS_ENABLED()`, rather than requiring #ifdefs in the C code when + it is not present. + +`gd->dm_priv_base` + When OF_PLATDATA_RT is enabled, the private/platform data for each device is + copied into an allocated region by U-Boot on start-up. This points to that + region. All calls to accessor functions (e.g. `dev_get_priv()`) then + translate from the pointer provided by the caller (assumed to lie between + `__priv_data_start` and `__priv_data_end`) to the new allocated region. This + member is accessed via macros so that it can be used inside IS_ENABLED(), + rather than required #ifdefs in the C code when it is not present. + +`struct udevice->flags_` + When OF_PLATDATA_RT is enabled, device flags are no-longer part of + `struct udevice`, but are instead kept in `struct udevice_rt`, as described + above. Flags are accessed via functions, such as `dev_get_flags()` and + `dev_or_flags()`. + +`struct udevice->node_` + When OF_PLATDATA is enabled, there is no devicetree at runtime, so no need + for this field. It is removed, just to save space. + +`DM_PHASE` + This macro is used to indicate which phase of U-Boot a driver is intended + for. See above for details. + +`DM_HDR` + This macro is used to indicate which header file dtoc should use to allow + a driver declaration to compile correctly. See above for details. + +`device_get_by_ofplat_idx()` + There used to be a function called `device_get_by_driver_info()` which + looked up a `struct driver_info` pointer and returned the `struct udevice` + that was created from it. It was only available for use with of-platdata. + This has been removed in favour of `device_get_by_ofplat_idx()` which uses + `idx`, the index of the `struct driver_info` or `struct udevice` in the + linker_list. Similarly, the `struct phandle_0_arg` (etc.) structs have been + updated to use this index instead of a pointer to `struct driver_info`. + +`DM_DRVINFO_GET` + This has been removed since we now use indexes to obtain a driver from + `struct phandle_0_arg` and the like. + +Two-pass binding + The original of-platdata tried to order `U_BOOT_DRVINFO()` in the generated + files so as to have parents declared ahead of children. This was convenient + as it avoided any special code in U-Boot. With OF_PLATDATA_INST this does + not work as the idx value relies on using alphabetical order for everything, + so that dtoc and U-Boot's linker_lists agree on the idx value. Devices are + then bound in order of idx, having no regard to parent/child relationships. + For this reason, device binding now hapens in multiple passes, with parents + being bound before their children. This is important so that children can + find their parents in the bind() method if needed. + +Root device + The root device is generally bound by U-Boot but with OF_PLATDATA_INST it + cannot be, since binding needs to be done at build time. So in this case + dtoc sets up a root device using `DM_DEVICE_INST()` in `dt-device.c` and + U-Boot makes use of that. When OF_PLATDATA_INST is not enabled, U-Boot + generally ignores the root node and does not create a `U_BOOT_DRVINFO()` + record for it. This means that the idx numbers used by `struct driver_info` + (when OF_PLATDATA_INST is disabled) and the idx numbers used by + `struct udevice` (when OF_PLATDATA_INST is enabled) differ, since one has a + root node and the other does not. This does not actually matter, since only + one of them is actually used for any particular build, but it is worth + keeping in mind if comparing index values and switching OF_PLATDATA_INST on + and off. + +`__priv_data_start` and `__priv_data_end` + The private/platform data declared by dtoc is all collected together in + a linker section and these symbols mark the start and end of it. This allows + U-Boot to relocate the area to a new location if needed (with + OF_PLATDATA_RT) + +`dm_priv_to_rw()` + This function converts a private- or platform-data pointer value generated by + dtoc into one that can be used by U-Boot. It is a NOP unless OF_PLATDATA_RT + is enabled, in which case it translates the address to the relocated + region. See above for more information. + +The dm_populate_phandle_data() function that was previous needed has now been +removed, since dtoc can address the drivers directly from dt-plat.c and does +not need to fix up things at runtime. + +The pylibfdt Python module is used to access the devicetree. + + +Credits +------- + +This is an implementation of an idea by Tom Rini <trini@konsulko.com>. + + +Future work +----------- +- Consider programmatically reading binding files instead of devicetree + contents +- Allow IS_ENABLED() to be used in the C code instead of #if + + +.. Simon Glass <sjg@chromium.org> +.. Google, Inc +.. 6/6/16 +.. Updated Independence Day 2016 +.. Updated 1st October 2020 +.. Updated 5th February 2021 diff --git a/roms/u-boot/doc/develop/driver-model/pci-info.rst b/roms/u-boot/doc/develop/driver-model/pci-info.rst new file mode 100644 index 000000000..251601a51 --- /dev/null +++ b/roms/u-boot/doc/develop/driver-model/pci-info.rst @@ -0,0 +1,172 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +PCI with Driver Model +===================== + +How busses are scanned +---------------------- + +Any config read will end up at pci_read_config(). This uses +uclass_get_device_by_seq() to get the PCI bus for a particular bus number. +Bus number 0 will need to be requested first, and the alias in the device +tree file will point to the correct device:: + + aliases { + pci0 = &pcic; + }; + + pcic: pci@0 { + compatible = "sandbox,pci"; + ... + }; + + +If there is no alias the devices will be numbered sequentially in the device +tree. + +The call to uclass_get_device() will cause the PCI bus to be probed. +This does a scan of the bus to locate available devices. These devices are +bound to their appropriate driver if available. If there is no driver, then +they are bound to a generic PCI driver which does nothing. + +After probing a bus, the available devices will appear in the device tree +under that bus. + +Note that this is all done on a lazy basis, as needed, so until something is +touched on PCI (eg: a call to pci_find_devices()) it will not be probed. + +PCI devices can appear in the flattened device tree. If they do, their node +often contains extra information which cannot be derived from the PCI IDs or +PCI class of the device. Each PCI device node must have a <reg> property, as +defined by the IEEE Std 1275-1994 PCI bus binding document v2.1. Compatible +string list is optional and generally not needed, since PCI is discoverable +bus, albeit there are justified exceptions. If the compatible string is +present, matching on it takes precedence over PCI IDs and PCI classes. + +Note we must describe PCI devices with the same bus hierarchy as the +hardware, otherwise driver model cannot detect the correct parent/children +relationship during PCI bus enumeration thus PCI devices won't be bound to +their drivers accordingly. A working example like below:: + + pci { + #address-cells = <3>; + #size-cells = <2>; + compatible = "pci-x86"; + u-boot,dm-pre-reloc; + ranges = <0x02000000 0x0 0x40000000 0x40000000 0 0x80000000 + 0x42000000 0x0 0xc0000000 0xc0000000 0 0x20000000 + 0x01000000 0x0 0x2000 0x2000 0 0xe000>; + + pcie@17,0 { + #address-cells = <3>; + #size-cells = <2>; + compatible = "pci-bridge"; + u-boot,dm-pre-reloc; + reg = <0x0000b800 0x0 0x0 0x0 0x0>; + + topcliff@0,0 { + #address-cells = <3>; + #size-cells = <2>; + compatible = "pci-bridge"; + u-boot,dm-pre-reloc; + reg = <0x00010000 0x0 0x0 0x0 0x0>; + + pciuart0: uart@a,1 { + compatible = "pci8086,8811.00", + "pci8086,8811", + "pciclass,070002", + "pciclass,0700", + "x86-uart"; + u-boot,dm-pre-reloc; + reg = <0x00025100 0x0 0x0 0x0 0x0 + 0x01025110 0x0 0x0 0x0 0x0>; + ...... + }; + + ...... + }; + }; + + ...... + }; + +In this example, the root PCI bus node is the "/pci" which matches "pci-x86" +driver. It has a subnode "pcie@17,0" with driver "pci-bridge". "pcie@17,0" +also has subnode "topcliff@0,0" which is a "pci-bridge" too. Under that bridge, +a PCI UART device "uart@a,1" is described. This exactly reflects the hardware +bus hierarchy: on the root PCI bus, there is a PCIe root port which connects +to a downstream device Topcliff chipset. Inside Topcliff chipset, it has a +PCIe-to-PCI bridge and all the chipset integrated devices like the PCI UART +device are on the PCI bus. Like other devices in the device tree, if we want +to bind PCI devices before relocation, "u-boot,dm-pre-reloc" must be declared +in each of these nodes. + +If PCI devices are not listed in the device tree, U_BOOT_PCI_DEVICE can be used +to specify the driver to use for the device. The device tree takes precedence +over U_BOOT_PCI_DEVICE. Please note with U_BOOT_PCI_DEVICE, only drivers with +DM_FLAG_PRE_RELOC will be bound before relocation. If neither device tree nor +U_BOOT_PCI_DEVICE is provided, the built-in driver (either pci_bridge_drv or +pci_generic_drv) will be used. + + +Sandbox +------- + +With sandbox we need a device emulator for each device on the bus since there +is no real PCI bus. This works by looking in the device tree node for an +emulator driver. For example:: + + pci@1f,0 { + compatible = "pci-generic"; + reg = <0xf800 0 0 0 0>; + sandbox,emul = <&emul_1f>; + }; + pci-emul { + compatible = "sandbox,pci-emul-parent"; + emul_1f: emul@1f,0 { + compatible = "sandbox,swap-case"; + #emul-cells = <0>; + }; + }; + +This means that there is a 'sandbox,swap-case' driver at that bus position. +Note that the first cell in the 'reg' value is the bus/device/function. See +PCI_BDF() for the encoding (it is also specified in the IEEE Std 1275-1994 +PCI bus binding document, v2.1) + +The pci-emul node should go outside the pci bus node, since otherwise it will +be scanned as a PCI device, causing confusion. + +When this bus is scanned we will end up with something like this:: + + `- * pci@0 @ 05c660c8, 0 + `- pci@1f,0 @ 05c661c8, 63488 + `- emul@1f,0 @ 05c662c8 + +When accesses go to the pci@1f,0 device they are forwarded to its emulator. + +The sandbox PCI drivers also support dynamic driver binding, allowing device +driver to declare the driver binding information via U_BOOT_PCI_DEVICE(), +eliminating the need to provide any device tree node under the host controller +node. It is required a "sandbox,dev-info" property must be provided in the +host controller node for this functionality to work. + +.. code-block:: none + + pci1: pci@1 { + compatible = "sandbox,pci"; + ... + sandbox,dev-info = <0x08 0x00 0x1234 0x5678 + 0x0c 0x00 0x1234 0x5678>; + }; + +The "sandbox,dev-info" property specifies all dynamic PCI devices on this bus. +Each dynamic PCI device is encoded as 4 cells a group. The first and second +cells are PCI device number and function number respectively. The third and +fourth cells are PCI vendor ID and device ID respectively. + +When this bus is scanned we will end up with something like this:: + + pci [ + ] pci_sandbo |-- pci1 + pci_emul [ ] sandbox_sw | |-- sandbox_swap_case_emul + pci_emul [ ] sandbox_sw | `-- sandbox_swap_case_emul diff --git a/roms/u-boot/doc/develop/driver-model/pmic-framework.rst b/roms/u-boot/doc/develop/driver-model/pmic-framework.rst new file mode 100644 index 000000000..d24a1badd --- /dev/null +++ b/roms/u-boot/doc/develop/driver-model/pmic-framework.rst @@ -0,0 +1,143 @@ +.. 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 +==================================== + +Introduction +------------ +This is an introduction to driver-model multi uclass PMIC IC's support. +At present it's based on two uclass types: + +UCLASS_PMIC: + basic uclass type for PMIC I/O, which provides common + read/write interface. +UCLASS_REGULATOR: + additional uclass type for specific PMIC features, which are + Voltage/Current regulators. + +New files: + +UCLASS_PMIC: + - drivers/power/pmic/pmic-uclass.c + - include/power/pmic.h +UCLASS_REGULATOR: + - drivers/power/regulator/regulator-uclass.c + - include/power/regulator.h + +Commands: +- common/cmd_pmic.c +- common/cmd_regulator.c + +How doees it work +----------------- +The Power Management Integrated Circuits (PMIC) are used in embedded systems +to provide stable, precise and specific voltage power source with over-voltage +and thermal protection circuits. + +The single PMIC can provide various functions by single or multiple interfaces, +like in the example below:: + + -- SoC + | + | ______________________________________ + | BUS 0 | Multi interface PMIC IC |--> LDO out 1 + | e.g.I2C0 | |--> LDO out N + |-----------|---- PMIC device 0 (READ/WRITE ops) | + | or SPI0 | |_ REGULATOR device (ldo/... ops) |--> BUCK out 1 + | | |_ CHARGER device (charger ops) |--> BUCK out M + | | |_ MUIC device (microUSB con ops) | + | BUS 1 | |_ ... |---> BATTERY + | e.g.I2C1 | | + |-----------|---- PMIC device 1 (READ/WRITE ops) |---> USB in 1 + . or SPI1 | |_ RTC device (rtc ops) |---> USB in 2 + . |______________________________________|---> USB out + . + +Since U-Boot provides driver model features for I2C and SPI bus drivers, +the PMIC devices should also support this. By the pmic and regulator API's, +PMIC drivers can simply provide a common functions, for multi-interface and +and multi-instance device support. + +Basic design assumptions: + +- Common I/O API: + UCLASS_PMIC. For the multi-function PMIC devices, this can be used as + parent I/O device for each IC's interface. Then, each children uses the + same dev for read/write. + +- Common regulator API: + UCLASS_REGULATOR. For driving the regulator attributes, auto setting + function or command line interface, based on kernel-style regulator device + tree constraints. + +For simple implementations, regulator drivers are not required, so the code can +use pmic read/write directly. + +Pmic uclass +----------- +The basic information: + +* Uclass: 'UCLASS_PMIC' +* Header: 'include/power/pmic.h' +* Core: 'drivers/power/pmic/pmic-uclass.c' (config 'CONFIG_DM_PMIC') +* Command: 'common/cmd_pmic.c' (config 'CONFIG_CMD_PMIC') +* Example: 'drivers/power/pmic/max77686.c' + +For detailed API description, please refer to the header file. + +As an example of the pmic driver, please refer to the MAX77686 driver. + +Please pay attention for the driver's bind() method. Exactly the function call: +'pmic_bind_children()', which is used to bind the regulators by using the array +of regulator's node, compatible prefixes. + +The 'pmic; command also supports the new API. So the pmic command can be enabled +by adding CONFIG_CMD_PMIC. +The new pmic command allows to: +- list pmic devices +- choose the current device (like the mmc command) +- read or write the pmic register +- dump all pmic registers + +This command can use only UCLASS_PMIC devices, since this uclass is designed +for pmic I/O operations only. + +For more information, please refer to the core file. + +Regulator uclass +---------------- +The basic information: + +* Uclass: 'UCLASS_REGULATOR' + +* Header: 'include/power/regulator.h' + +* Core: 'drivers/power/regulator/regulator-uclass.c' + (config 'CONFIG_DM_REGULATOR') + +* Binding: 'doc/device-tree-bindings/regulator/regulator.txt' + +* Command: 'common/cmd_regulator.c' (config 'CONFIG_CMD_REGULATOR') + +* Example: 'drivers/power/regulator/max77686.c' + 'drivers/power/pmic/max77686.c' (required I/O driver for the above) + +* Example: 'drivers/power/regulator/fixed.c' + (config 'CONFIG_DM_REGULATOR_FIXED') + +For detailed API description, please refer to the header file. + +For the example regulator driver, please refer to the MAX77686 regulator driver, +but this driver can't operate without pmic's example driver, which provides an +I/O interface for MAX77686 regulator. + +The second example is a fixed Voltage/Current regulator for a common use. + +The 'regulator' command also supports the new API. The command allow: +- list regulator devices +- choose the current device (like the mmc command) +- do all regulator-specific operations + +For more information, please refer to the command file. diff --git a/roms/u-boot/doc/develop/driver-model/remoteproc-framework.rst b/roms/u-boot/doc/develop/driver-model/remoteproc-framework.rst new file mode 100644 index 000000000..566495a21 --- /dev/null +++ b/roms/u-boot/doc/develop/driver-model/remoteproc-framework.rst @@ -0,0 +1,169 @@ +.. SPDX-License-Identifier: GPL-2.0+ +.. (C) Copyright 2015 +.. Texas Instruments Incorporated - http://www.ti.com/ + +Remote Processor Framework +========================== + +Introduction +------------ + +This is an introduction to driver-model for Remote Processors found +on various System on Chip(SoCs). The term remote processor is used to +indicate that this is not the processor on which U-Boot is operating +on, instead is yet another processing entity that may be controlled by +the processor on which we are functional. + +The simplified model depends on a single UCLASS - UCLASS_REMOTEPROC + +UCLASS_REMOTEPROC: + - drivers/remoteproc/rproc-uclass.c + - include/remoteproc.h + +Commands: + - common/cmd_remoteproc.c + +Configuration: + - CONFIG_REMOTEPROC is selected by drivers as needed + - CONFIG_CMD_REMOTEPROC for the commands if required. + +How does it work - The driver +----------------------------- + +Overall, the driver statemachine transitions are typically as follows:: + + (entry) + +-------+ + +---+ init | + | | | <---------------------+ + | +-------+ | + | | + | | + | +--------+ | + Load| | reset | | + | | | <----------+ | + | +--------+ | | + | |Load | | + | | | | + | +----v----+ reset | | + +-> | | (opt) | | + | Loaded +-----------+ | + | | | + +----+----+ | + | Start | + +---v-----+ (opt) | + +->| Running | Stop | + Ping +- | +--------------------+ + (opt) +---------+ + +(is_running does not change state) +opt: Optional state transition implemented by driver. + +NOTE: It depends on the remote processor as to the exact behavior +of the statemachine, remoteproc core does not intent to implement +statemachine logic. Certain processors may allow start/stop without +reloading the image in the middle, certain other processors may only +allow us to start the processor(image from a EEPROM/OTP) etc. + +It is hence the responsibility of the driver to handle the requisite +state transitions of the device as necessary. + +Basic design assumptions: + +Remote processor can operate on a certain firmware that maybe loaded +and released from reset. + +The driver follows a standard UCLASS DM. + +in the bare minimum form: + +.. code-block:: c + + static const struct dm_rproc_ops sandbox_testproc_ops = { + .load = sandbox_testproc_load, + .start = sandbox_testproc_start, + }; + + static const struct udevice_id sandbox_ids[] = { + {.compatible = "sandbox,test-processor"}, + {} + }; + + U_BOOT_DRIVER(sandbox_testproc) = { + .name = "sandbox_test_proc", + .of_match = sandbox_ids, + .id = UCLASS_REMOTEPROC, + .ops = &sandbox_testproc_ops, + .probe = sandbox_testproc_probe, + }; + +This allows for the device to be probed as part of the "init" command +or invocation of 'rproc_init()' function as the system dependencies define. + +The driver is expected to maintain it's own statemachine which is +appropriate for the device it maintains. It must, at the very least +provide a load and start function. We assume here that the device +needs to be loaded and started, else, there is no real purpose of +using the remoteproc framework. + +Describing the device using platform data +----------------------------------------- + +*IMPORTANT* NOTE: THIS SUPPORT IS NOT MEANT FOR USE WITH NEWER PLATFORM +SUPPORT. THIS IS ONLY FOR LEGACY DEVICES. THIS MODE OF INITIALIZATION +*WILL* BE EVENTUALLY REMOVED ONCE ALL NECESSARY PLATFORMS HAVE MOVED +TO DM/FDT. + +Considering that many platforms are yet to move to device-tree model, +a simplified definition of a device is as follows: + +.. code-block:: c + + struct dm_rproc_uclass_pdata proc_3_test = { + .name = "proc_3_legacy", + .mem_type = RPROC_INTERNAL_MEMORY_MAPPED, + .driver_plat_data = &mydriver_data; + }; + + U_BOOT_DRVINFO(proc_3_demo) = { + .name = "sandbox_test_proc", + .plat = &proc_3_test, + }; + +There can be additional data that may be desired depending on the +remoteproc driver specific needs (for example: SoC integration +details such as clock handle or something similar). See appropriate +documentation for specific remoteproc driver for further details. +These are passed via driver_plat_data. + +Describing the device using device tree +--------------------------------------- + +.. code-block: none + + / { + ... + aliases { + ... + remoteproc0 = &rproc_1; + remoteproc1 = &rproc_2; + + }; + ... + + rproc_1: rproc@1 { + compatible = "sandbox,test-processor"; + remoteproc-name = "remoteproc-test-dev1"; + }; + + rproc_2: rproc@2 { + compatible = "sandbox,test-processor"; + internal-memory-mapped; + remoteproc-name = "remoteproc-test-dev2"; + }; + ... + }; + +aliases usage is optional, but it is usually recommended to ensure the +users have a consistent usage model for a platform. +the compatible string used here is specific to the remoteproc driver involved. diff --git a/roms/u-boot/doc/develop/driver-model/serial-howto.rst b/roms/u-boot/doc/develop/driver-model/serial-howto.rst new file mode 100644 index 000000000..146913112 --- /dev/null +++ b/roms/u-boot/doc/develop/driver-model/serial-howto.rst @@ -0,0 +1,46 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +How to port a serial driver to driver model +=========================================== + +Almost all of the serial drivers have been converted as at January 2016. These +ones remain: + + * serial_bfin.c + * serial_pxa.c + +The deadline for this work was the end of January 2016. If no one steps +forward to convert these, at some point there may come a patch to remove them! + +Here is a suggested approach for converting your serial driver over to driver +model. Please feel free to update this file with your ideas and suggestions. + +- #ifdef out all your own serial driver code (#ifndef CONFIG_DM_SERIAL) +- Define CONFIG_DM_SERIAL for your board, vendor or architecture +- If the board does not already use driver model, you need CONFIG_DM also +- Your board should then build, but will not boot since there will be no serial + driver +- Add the U_BOOT_DRIVER piece at the end (e.g. copy serial_s5p.c for example) +- Add a private struct for the driver data - avoid using static variables +- Implement each of the driver methods, perhaps by calling your old methods +- You may need to adjust the function parameters so that the old and new + implementations can share most of the existing code +- If you convert all existing users of the driver, remove the pre-driver-model + code + +In terms of patches a conversion series typically has these patches: +- clean up / prepare the driver for conversion +- add driver model code +- convert at least one existing board to use driver model serial +- (if no boards remain that don't use driver model) remove the old code + +This may be a good time to move your board to use device tree also. Mostly +this involves these steps: + +- define CONFIG_OF_CONTROL and CONFIG_OF_SEPARATE +- add your device tree files to arch/<arch>/dts +- update the Makefile there +- Add stdout-path to your /chosen device tree node if it is not already there +- build and get u-boot-dtb.bin so you can test it +- Your drivers can now use device tree +- For device tree in SPL, define CONFIG_SPL_OF_CONTROL diff --git a/roms/u-boot/doc/develop/driver-model/soc-framework.rst b/roms/u-boot/doc/develop/driver-model/soc-framework.rst new file mode 100644 index 000000000..2609fda64 --- /dev/null +++ b/roms/u-boot/doc/develop/driver-model/soc-framework.rst @@ -0,0 +1,68 @@ +.. SPDX-License-Identifier: GPL-2.0+ +.. (C) Copyright 2020 +.. Texas Instruments Incorporated - http://www.ti.com/ + +SOC ID Framework +================ + +Introduction +------------ + +The driver-model SOC ID framework is able to provide identification +information about a specific SoC in use at runtime, and also provide matching +from a set of identification information from an array. This can be useful for +enabling small quirks in drivers that exist between SoC variants that are +impractical to implement using device tree flags. It is based on UCLASS_SOC. + +UCLASS_SOC: + - drivers/soc/soc-uclass.c + - include/soc.h + +Configuration: + - CONFIG_SOC_DEVICE is selected by drivers as needed. + +Implementing a UCLASS_SOC provider +---------------------------------- + +The purpose of this framework is to allow UCLASS_SOC provider drivers to supply +identification information about the SoC in use at runtime. The framework +allows drivers to define soc_ops that return identification strings. All +soc_ops need not be defined and can be left as NULL, in which case the +framework will return -ENOSYS and not consider the value when doing an +soc_device_match. + +It is left to the driver implementor to decide how the information returned is +determined, but in general the same SOC should always return the same set of +identifying information. Information returned must be in the form of a NULL +terminated string. + +See include/soc.h for documentation of the available soc_ops and the intended +meaning of the values that can be returned. See drivers/soc/soc_sandbox.c for +an example UCLASS_SOC provider driver. + +Using a UCLASS_SOC driver +------------------------- + +The framework provides the ability to retrieve and use the identification +strings directly. It also has the ability to return a match from a list of +different sets of SoC data using soc_device_match. + +An array of 'struct soc_attr' can be defined, each containing ID information +for a specific SoC, and when passed to soc_device_match, the identifier values +for each entry in the list will be compared against the values provided by the +UCLASS_SOC driver that is in use. The first entry in the list that matches all +non-null values will be returned by soc_device_match. + +An example of various uses of the framework can be found at test/dm/soc.c. + +Describing the device using device tree +--------------------------------------- + +.. code-block:: none + + chipid: chipid { + compatible = "sandbox,soc"; + }; + +All that is required in a DT node is a compatible for a corresponding +UCLASS_SOC driver. diff --git a/roms/u-boot/doc/develop/driver-model/spi-howto.rst b/roms/u-boot/doc/develop/driver-model/spi-howto.rst new file mode 100644 index 000000000..97fbf750c --- /dev/null +++ b/roms/u-boot/doc/develop/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_of_to_plat(struct udevice *dev) + { + return -ENODEV; + } + + static int exynos_spi_probe(struct udevice *dev) + { + return -ENODEV; + } + + static int exynos_spi_remove(struct udevice *dev) + { + return -ENODEV; + } + + static int exynos_spi_claim_bus(struct udevice *dev) + { + + return -ENODEV; + } + + static int exynos_spi_release_bus(struct udevice *dev) + { + + return -ENODEV; + } + + static int exynos_spi_xfer(struct udevice *dev, unsigned int bitlen, + const void *dout, void *din, unsigned long flags) + { + + return -ENODEV; + } + + static int exynos_spi_set_speed(struct udevice *dev, uint speed) + { + return -ENODEV; + } + + static int exynos_spi_set_mode(struct udevice *dev, uint mode) + { + return -ENODEV; + } + + static int exynos_cs_info(struct udevice *bus, uint cs, + struct spi_cs_info *info) + { + return -EINVAL; + } + + static const struct dm_spi_ops exynos_spi_ops = { + .claim_bus = exynos_spi_claim_bus, + .release_bus = exynos_spi_release_bus, + .xfer = exynos_spi_xfer, + .set_speed = exynos_spi_set_speed, + .set_mode = exynos_spi_set_mode, + .cs_info = exynos_cs_info, + }; + + static const struct udevice_id exynos_spi_ids[] = { + { .compatible = "samsung,exynos-spi" }, + { } + }; + + U_BOOT_DRIVER(exynos_spi) = { + .name = "exynos_spi", + .id = UCLASS_SPI, + .of_match = exynos_spi_ids, + .ops = &exynos_spi_ops, + .of_to_plat = exynos_spi_of_to_plat, + .probe = exynos_spi_probe, + .remove = exynos_spi_remove, + }; + + +Replace 'exynos' in the above code with your driver name +-------------------------------------------------------- + + +#ifdef out all of the code in your driver except for the above +-------------------------------------------------------------- + +This will allow you to get it building, which means you can work +incrementally. Since all the methods return an error initially, there is +less chance that you will accidentally leave something in. + +Also, even though your conversion is basically a rewrite, it might help +reviewers if you leave functions in the same place in the file, +particularly for large drivers. + + +Add some includes +----------------- + +Add these includes to your driver: + +.. code-block:: c + + #include <dm.h> + #include <errno.h> + + +Build +----- + +At this point you should be able to build U-Boot for your board with the +empty SPI driver. You still have empty methods in your driver, but we will +write these one by one. + +Set up your platform data structure +----------------------------------- + +This will hold the information your driver to operate, like its hardware +address or maximum frequency. + +You may already have a struct like this, or you may need to create one +from some of the #defines or global variables in the driver. + +Note that this information is not the run-time information. It should not +include state that changes. It should be fixed throughout the live of +U-Boot. Run-time information comes later. + +Here is what was in the exynos spi driver: + +.. code-block:: c + + struct spi_bus { + enum periph_id periph_id; + s32 frequency; /* Default clock frequency, -1 for none */ + struct exynos_spi *regs; + int inited; /* 1 if this bus is ready for use */ + int node; + uint deactivate_delay_us; /* Delay to wait after deactivate */ + }; + +Of these, inited is handled by DM and node is the device tree node, which +DM tells you. The name is not quite right. So in this case we would use: + +.. code-block:: c + + struct exynos_spi_plat { + enum periph_id periph_id; + s32 frequency; /* Default clock frequency, -1 for none */ + struct exynos_spi *regs; + uint deactivate_delay_us; /* Delay to wait after deactivate */ + }; + + +Write of_to_plat() [for device tree only] +------------------------------------------------- + +This method will convert information in the device tree node into a C +structure in your driver (called platform data). If you are not using +device tree, go to 8b. + +DM will automatically allocate the struct for us when we are using device +tree, but we need to tell it the size: + +.. code-block:: c + + U_BOOT_DRIVER(spi_exynos) = { + ... + .plat_auto = sizeof(struct exynos_spi_plat), + + +Here is a sample function. It gets a pointer to the platform data and +fills in the fields from device tree. + +.. code-block:: c + + static int exynos_spi_of_to_plat(struct udevice *bus) + { + struct exynos_spi_plat *plat = bus->plat; + const void *blob = gd->fdt_blob; + int node = dev_of_offset(bus); + + plat->regs = (struct exynos_spi *)fdtdec_get_addr(blob, node, "reg"); + plat->periph_id = pinmux_decode_periph_id(blob, node); + + if (plat->periph_id == PERIPH_ID_NONE) { + debug("%s: Invalid peripheral ID %d\n", __func__, + plat->periph_id); + return -FDT_ERR_NOTFOUND; + } + + /* Use 500KHz as a suitable default */ + plat->frequency = fdtdec_get_int(blob, node, "spi-max-frequency", + 500000); + plat->deactivate_delay_us = fdtdec_get_int(blob, node, + "spi-deactivate-delay", 0); + debug("%s: regs=%p, periph_id=%d, max-frequency=%d, deactivate_delay=%d\n", + __func__, plat->regs, plat->periph_id, plat->frequency, + plat->deactivate_delay_us); + + return 0; + } + + +Add the platform data [non-device-tree only] +-------------------------------------------- + +Specify this data in a U_BOOT_DRVINFO() declaration in your board file: + +.. code-block:: c + + struct exynos_spi_plat platdata_spi0 = { + .periph_id = ... + .frequency = ... + .regs = ... + .deactivate_delay_us = ... + }; + + U_BOOT_DRVINFO(board_spi0) = { + .name = "exynos_spi", + .plat = &platdata_spi0, + }; + +You will unfortunately need to put the struct definition into a header file +in this case so that your board file can use it. + + +Add the device private data +--------------------------- + +Most devices have some private data which they use to keep track of things +while active. This is the run-time information and needs to be stored in +a structure. There is probably a structure in the driver that includes a +'struct spi_slave', so you can use that. + +.. code-block:: c + + struct exynos_spi_slave { + struct spi_slave slave; + struct exynos_spi *regs; + unsigned int freq; /* Default frequency */ + unsigned int mode; + enum periph_id periph_id; /* Peripheral ID for this device */ + unsigned int fifo_size; + int skip_preamble; + struct spi_bus *bus; /* Pointer to our SPI bus info */ + ulong last_transaction_us; /* Time of last transaction end */ + }; + + +We should rename this to make its purpose more obvious, and get rid of +the slave structure, so we have: + +.. code-block:: c + + struct exynos_spi_priv { + struct exynos_spi *regs; + unsigned int freq; /* Default frequency */ + unsigned int mode; + enum periph_id periph_id; /* Peripheral ID for this device */ + unsigned int fifo_size; + int skip_preamble; + ulong last_transaction_us; /* Time of last transaction end */ + }; + + +DM can auto-allocate this also: + +.. code-block:: c + + U_BOOT_DRIVER(spi_exynos) = { + ... + .priv_auto = sizeof(struct exynos_spi_priv), + + +Note that this is created before the probe method is called, and destroyed +after the remove method is called. It will be zeroed when the probe +method is called. + + +Add the probe() and remove() methods +------------------------------------ + +Note: It's a good idea to build repeatedly as you are working, to avoid a +huge amount of work getting things compiling at the end. + +The probe method is supposed to set up the hardware. U-Boot used to use +spi_setup_slave() to do this. So take a look at this function and see +what you can copy out to set things up. + +.. code-block:: c + + static int exynos_spi_probe(struct udevice *bus) + { + struct exynos_spi_plat *plat = dev_get_plat(bus); + struct exynos_spi_priv *priv = dev_get_priv(bus); + + priv->regs = plat->regs; + if (plat->periph_id == PERIPH_ID_SPI1 || + plat->periph_id == PERIPH_ID_SPI2) + priv->fifo_size = 64; + else + priv->fifo_size = 256; + + priv->skip_preamble = 0; + priv->last_transaction_us = timer_get_us(); + priv->freq = plat->frequency; + priv->periph_id = plat->periph_id; + + return 0; + } + +This implementation doesn't actually touch the hardware, which is somewhat +unusual for a driver. In this case we will do that when the device is +claimed by something that wants to use the SPI bus. + +For remove we could shut down the clocks, but in this case there is +nothing to do. DM frees any memory that it allocated, so we can just +remove exynos_spi_remove() and its reference in U_BOOT_DRIVER. + + +Implement set_speed() +--------------------- + +This should set up clocks so that the SPI bus is running at the right +speed. With the old API spi_claim_bus() would normally do this and several +of the following functions, so let's look at that function: + +.. code-block:: c + + int spi_claim_bus(struct spi_slave *slave) + { + struct exynos_spi_slave *spi_slave = to_exynos_spi(slave); + struct exynos_spi *regs = spi_slave->regs; + u32 reg = 0; + int ret; + + ret = set_spi_clk(spi_slave->periph_id, + spi_slave->freq); + if (ret < 0) { + debug("%s: Failed to setup spi clock\n", __func__); + return ret; + } + + exynos_pinmux_config(spi_slave->periph_id, PINMUX_FLAG_NONE); + + spi_flush_fifo(slave); + + reg = readl(®s->ch_cfg); + reg &= ~(SPI_CH_CPHA_B | SPI_CH_CPOL_L); + + if (spi_slave->mode & SPI_CPHA) + reg |= SPI_CH_CPHA_B; + + if (spi_slave->mode & SPI_CPOL) + reg |= SPI_CH_CPOL_L; + + writel(reg, ®s->ch_cfg); + writel(SPI_FB_DELAY_180, ®s->fb_clk); + + return 0; + } + + +It sets up the speed, mode, pinmux, feedback delay and clears the FIFOs. +With DM these will happen in separate methods. + + +Here is an example for the speed part: + +.. code-block:: c + + static int exynos_spi_set_speed(struct udevice *bus, uint speed) + { + struct exynos_spi_plat *plat = bus->plat; + struct exynos_spi_priv *priv = dev_get_priv(bus); + int ret; + + if (speed > plat->frequency) + speed = plat->frequency; + ret = set_spi_clk(priv->periph_id, speed); + if (ret) + return ret; + priv->freq = speed; + debug("%s: regs=%p, speed=%d\n", __func__, priv->regs, priv->freq); + + return 0; + } + + +Implement set_mode() +-------------------- + +This should adjust the SPI mode (polarity, etc.). Again this code probably +comes from the old spi_claim_bus(). Here is an example: + +.. code-block:: c + + static int exynos_spi_set_mode(struct udevice *bus, uint mode) + { + struct exynos_spi_priv *priv = dev_get_priv(bus); + uint32_t reg; + + reg = readl(&priv->regs->ch_cfg); + reg &= ~(SPI_CH_CPHA_B | SPI_CH_CPOL_L); + + if (mode & SPI_CPHA) + reg |= SPI_CH_CPHA_B; + + if (mode & SPI_CPOL) + reg |= SPI_CH_CPOL_L; + + writel(reg, &priv->regs->ch_cfg); + priv->mode = mode; + debug("%s: regs=%p, mode=%d\n", __func__, priv->regs, priv->mode); + + return 0; + } + + +Implement claim_bus() +--------------------- + +This is where a client wants to make use of the bus, so claims it first. +At this point we need to make sure everything is set up ready for data +transfer. Note that this function is wholly internal to the driver - at +present the SPI uclass never calls it. + +Here again we look at the old claim function and see some code that is +needed. It is anything unrelated to speed and mode: + +.. code-block:: c + + static int exynos_spi_claim_bus(struct udevice *bus) + { + struct exynos_spi_priv *priv = dev_get_priv(bus); + + exynos_pinmux_config(priv->periph_id, PINMUX_FLAG_NONE); + spi_flush_fifo(priv->regs); + + writel(SPI_FB_DELAY_180, &priv->regs->fb_clk); + + return 0; + } + +The spi_flush_fifo() function is in the removed part of the code, so we +need to expose it again (perhaps with an #endif before it and '#if 0' +after it). It only needs access to priv->regs which is why we have +passed that in: + +.. code-block:: c + + /** + * Flush spi tx, rx fifos and reset the SPI controller + * + * @param regs Pointer to SPI registers + */ + static void spi_flush_fifo(struct exynos_spi *regs) + { + clrsetbits_le32(®s->ch_cfg, SPI_CH_HS_EN, SPI_CH_RST); + clrbits_le32(®s->ch_cfg, SPI_CH_RST); + setbits_le32(®s->ch_cfg, SPI_TX_CH_ON | SPI_RX_CH_ON); + } + + +Implement release_bus() +----------------------- + +This releases the bus - in our example the old code in spi_release_bus() +is a call to spi_flush_fifo, so we add: + +.. code-block:: c + + static int exynos_spi_release_bus(struct udevice *bus) + { + struct exynos_spi_priv *priv = dev_get_priv(bus); + + spi_flush_fifo(priv->regs); + + return 0; + } + + +Implement xfer() +---------------- + +This is the final method that we need to create, and it is where all the +work happens. The method parameters are the same as the old spi_xfer() with +the addition of a 'struct udevice' so conversion is pretty easy. Start +by copying the contents of spi_xfer() to your new xfer() method and proceed +from there. + +If (flags & SPI_XFER_BEGIN) is non-zero then xfer() normally calls an +activate function, something like this: + +.. code-block:: c + + void spi_cs_activate(struct spi_slave *slave) + { + struct exynos_spi_slave *spi_slave = to_exynos_spi(slave); + + /* If it's too soon to do another transaction, wait */ + if (spi_slave->bus->deactivate_delay_us && + spi_slave->last_transaction_us) { + ulong delay_us; /* The delay completed so far */ + delay_us = timer_get_us() - spi_slave->last_transaction_us; + if (delay_us < spi_slave->bus->deactivate_delay_us) + udelay(spi_slave->bus->deactivate_delay_us - delay_us); + } + + clrbits_le32(&spi_slave->regs->cs_reg, SPI_SLAVE_SIG_INACT); + debug("Activate CS, bus %d\n", spi_slave->slave.bus); + spi_slave->skip_preamble = spi_slave->mode & SPI_PREAMBLE; + } + +The new version looks like this: + +.. code-block:: c + + static void spi_cs_activate(struct udevice *dev) + { + struct udevice *bus = dev->parent; + struct exynos_spi_plat *pdata = dev_get_plat(bus); + struct exynos_spi_priv *priv = dev_get_priv(bus); + + /* If it's too soon to do another transaction, wait */ + if (pdata->deactivate_delay_us && + priv->last_transaction_us) { + ulong delay_us; /* The delay completed so far */ + delay_us = timer_get_us() - priv->last_transaction_us; + if (delay_us < pdata->deactivate_delay_us) + udelay(pdata->deactivate_delay_us - delay_us); + } + + clrbits_le32(&priv->regs->cs_reg, SPI_SLAVE_SIG_INACT); + debug("Activate CS, bus '%s'\n", bus->name); + priv->skip_preamble = priv->mode & SPI_PREAMBLE; + } + +All we have really done here is change the pointers and print the device name +instead of the bus number. Other local static functions can be treated in +the same way. + + +Set up the per-child data and child pre-probe function +------------------------------------------------------ + +To minimise the pain and complexity of the SPI subsystem while the driver +model change-over is in place, struct spi_slave is used to reference a +SPI bus slave, even though that slave is actually a struct udevice. In fact +struct spi_slave is the device's child data. We need to make sure this space +is available. It is possible to allocate more space that struct spi_slave +needs, but this is the minimum. + +.. code-block:: c + + U_BOOT_DRIVER(exynos_spi) = { + ... + .per_child_auto = sizeof(struct spi_slave), + } + + +Optional: Set up cs_info() if you want it +----------------------------------------- + +Sometimes it is useful to know whether a SPI chip select is valid, but this +is not obvious from outside the driver. In this case you can provide a +method for cs_info() to deal with this. If you don't provide it, then the +device tree will be used to determine what chip selects are valid. + +Return -EINVAL if the supplied chip select is invalid, or 0 if it is valid. +If you don't provide the cs_info() method, 0 is assumed for all chip selects +that do not appear in the device tree. + + +Test it +------- + +Now that you have the code written and it compiles, try testing it using +the 'sf test' command. You may need to enable CONFIG_CMD_SF_TEST for your +board. + + +Prepare patches and send them to the mailing lists +-------------------------------------------------- + +You can use 'tools/patman/patman' to prepare, check and send patches for +your work. See tools/patman/README for details. + +A little note about SPI uclass features +--------------------------------------- + +The SPI uclass keeps some information about each device 'dev' on the bus: + + struct dm_spi_slave_plat: + This is device_get_parent_plat(dev). + This is where the chip select number is stored, along with + the default bus speed and mode. It is automatically read + from the device tree in spi_child_post_bind(). It must not + be changed at run-time after being set up because platform + data is supposed to be immutable at run-time. + struct spi_slave: + This is device_get_parentdata(dev). + Already mentioned above. It holds run-time information about + the device. + +There are also some SPI uclass methods that get called behind the scenes: + + spi_post_bind(): + Called when a new bus is bound. + This scans the device tree for devices on the bus, and binds + each one. This in turn causes spi_child_post_bind() to be + called for each, which reads the device tree information + into the parent (per-child) platform data. + spi_child_post_bind(): + Called when a new child is bound. + As mentioned above this reads the device tree information + into the per-child platform data + spi_child_pre_probe(): + Called before a new child is probed. + This sets up the mode and speed in struct spi_slave by + copying it from the parent's platform data for this child. + It also sets the 'dev' pointer, needed to permit passing + 'struct spi_slave' around the place without needing a + separate 'struct udevice' pointer. + +The above housekeeping makes it easier to write your SPI driver. diff --git a/roms/u-boot/doc/develop/driver-model/usb-info.rst b/roms/u-boot/doc/develop/driver-model/usb-info.rst new file mode 100644 index 000000000..24d1e81a6 --- /dev/null +++ b/roms/u-boot/doc/develop/driver-model/usb-info.rst @@ -0,0 +1,423 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +How USB works with driver model +=============================== + +Introduction +------------ + +Driver model USB support makes use of existing features but changes how +drivers are found. This document provides some information intended to help +understand how things work with USB in U-Boot when driver model is enabled. + + +Enabling driver model for USB +----------------------------- + +A new CONFIG_DM_USB option is provided to enable driver model for USB. This +causes the USB uclass to be included, and drops the equivalent code in +usb.c. In particular the usb_init() function is then implemented by the +uclass. + + +Support for EHCI and XHCI +------------------------- + +So far OHCI is not supported. Both EHCI and XHCI drivers should be declared +as drivers in the USB uclass. For example: + +.. code-block:: c + + static const struct udevice_id ehci_usb_ids[] = { + { .compatible = "nvidia,tegra20-ehci", .data = USB_CTLR_T20 }, + { .compatible = "nvidia,tegra30-ehci", .data = USB_CTLR_T30 }, + { .compatible = "nvidia,tegra114-ehci", .data = USB_CTLR_T114 }, + { } + }; + + U_BOOT_DRIVER(usb_ehci) = { + .name = "ehci_tegra", + .id = UCLASS_USB, + .of_match = ehci_usb_ids, + .of_to_plat = ehci_usb_of_to_plat, + .probe = tegra_ehci_usb_probe, + .remove = tegra_ehci_usb_remove, + .ops = &ehci_usb_ops, + .plat_auto = sizeof(struct usb_plat), + .priv_auto = sizeof(struct fdt_usb), + .flags = DM_FLAG_ALLOC_PRIV_DMA, + }; + +Here ehci_usb_ids is used to list the controllers that the driver supports. +Each has its own data value. Controllers must be in the UCLASS_USB uclass. + +The of_to_plat() method allows the controller driver to grab any +necessary settings from the device tree. + +The ops here are ehci_usb_ops. All EHCI drivers will use these same ops in +most cases, since they are all EHCI-compatible. For EHCI there are also some +special operations that can be overridden when calling ehci_register(). + +The driver can use priv_auto to set the size of its private data. +This can hold run-time information needed by the driver for operation. It +exists when the device is probed (not when it is bound) and is removed when +the driver is removed. + +Note that usb_plat is currently only used to deal with setting up a bus +in USB device mode (OTG operation). It can be omitted if that is not +supported. + +The driver's probe() method should do the basic controller init and then +call ehci_register() to register itself as an EHCI device. It should call +ehci_deregister() in the remove() method. Registering a new EHCI device +does not by itself cause the bus to be scanned. + +The old ehci_hcd_init() function is no-longer used. Nor is it necessary to +set up the USB controllers from board init code. When 'usb start' is used, +each controller will be probed and its bus scanned. + +XHCI works in a similar way. + + +Data structures +--------------- + +The following primary data structures are in use: + +- struct usb_device: + This holds information about a device on the bus. All devices have + this structure, even the root hub. The controller itself does not + have this structure. You can access it for a device 'dev' with + dev_get_parent_priv(dev). It matches the old structure except that the + parent and child information is not present (since driver model + handles that). Once the device is set up, you can find the device + descriptor and current configuration descriptor in this structure. + +- struct usb_plat: + This holds platform data for a controller. So far this is only used + as a work-around for controllers which can act as USB devices in OTG + mode, since the gadget framework does not use driver model. + +- struct usb_dev_plat: + This holds platform data for a device. You can access it for a + device 'dev' with dev_get_parent_plat(dev). It holds the device + address and speed - anything that can be determined before the device + driver is actually set up. When probing the bus this structure is + used to provide essential information to the device driver. + +- struct usb_bus_priv: + This is private information for each controller, maintained by the + controller uclass. It is mostly used to keep track of the next + device address to use. + +Of these, only struct usb_device was used prior to driver model. + + +USB buses +--------- + +Given a controller, you know the bus - it is the one attached to the +controller. Each controller handles exactly one bus. Every controller has a +root hub attached to it. This hub, which is itself a USB device, can provide +one or more 'ports' to which additional devices can be attached. It is +possible to power up a hub and find out which of its ports have devices +attached. + +Devices are given addresses starting at 1. The root hub is always address 1, +and from there the devices are numbered in sequence. The USB uclass takes +care of this numbering automatically during enumeration. + +USB devices are enumerated by finding a device on a particular hub, and +setting its address to the next available address. The USB bus stretches out +in a tree structure, potentially with multiple hubs each with several ports +and perhaps other hubs. Some hubs will have their own power since otherwise +the 5V 500mA power supplied by the controller will not be sufficient to run +very many devices. + +Enumeration in U-Boot takes a long time since devices are probed one at a +time, and each is given sufficient time to wake up and announce itself. The +timeouts are set for the slowest device. + +Up to 127 devices can be on each bus. USB has four bus speeds: low +(1.5Mbps), full (12Mbps), high (480Mbps) which is only available with USB2 +and newer (EHCI), and super (5Gbps) which is only available with USB3 and +newer (XHCI). If you connect a super-speed device to a high-speed hub, you +will only get high-speed. + + +USB operations +-------------- + +As before driver model, messages can be sent using submit_bulk_msg() and the +like. These are now implemented by the USB uclass and route through the +controller drivers. Note that messages are not sent to the driver of the +device itself - i.e. they don't pass down the stack to the controller. +U-Boot simply finds the controller to which the device is attached, and sends +the message there with an appropriate 'pipe' value so it can be addressed +properly. Having said that, the USB device which should receive the message +is passed in to the driver methods, for use by sandbox. This design decision +is open for review and the code impact of changing it is small since the +methods are typically implemented by the EHCI and XHCI stacks. + +Controller drivers (in UCLASS_USB) themselves provide methods for sending +each message type. For XHCI an additional alloc_device() method is provided +since XHCI needs to allocate a device context before it can even read the +device's descriptor. + +These methods use a 'pipe' which is a collection of bit fields used to +describe the type of message, direction of transfer and the intended +recipient (device number). + + +USB Devices +----------- + +USB devices are found using a simple algorithm which works through the +available hubs in a depth-first search. Devices can be in any uclass, but +are attached to a parent hub (or controller in the case of the root hub) and +so have parent data attached to them (this is struct usb_device). + +By the time the device's probe() method is called, it is enumerated and is +ready to talk to the host. + +The enumeration process needs to work out which driver to attach to each USB +device. It does this by examining the device class, interface class, vendor +ID, product ID, etc. See struct usb_driver_entry for how drivers are matched +with USB devices - you can use the USB_DEVICE() macro to declare a USB +driver. For example, usb_storage.c defines a USB_DEVICE() to handle storage +devices, and it will be used for all USB devices which match. + + + +Technical details on enumeration flow +------------------------------------- + +It is useful to understand precisely how a USB bus is enumerating to avoid +confusion when dealing with USB devices. + +Device initialisation happens roughly like this: + +- At some point the 'usb start' command is run +- This calls usb_init() which works through each controller in turn +- The controller is probed(). This does no enumeration. +- Then usb_scan_bus() is called. This calls usb_scan_device() to scan the + (only) device that is attached to the controller - a root hub +- usb_scan_device() sets up a fake struct usb_device and calls + usb_setup_device(), passing the port number to be scanned, in this case + port 0 +- usb_setup_device() first calls usb_prepare_device() to set the device + address, then usb_select_config() to select the first configuration +- at this point the device is enumerated but we do not have a real struct + udevice for it. But we do have the descriptor in struct usb_device so we can + use this to figure out what driver to use +- back in usb_scan_device(), we call usb_find_child() to try to find an + existing device which matches the one we just found on the bus. This can + happen if the device is mentioned in the device tree, or if we previously + scanned the bus and so the device was created before +- if usb_find_child() does not find an existing device, we call + usb_find_and_bind_driver() which tries to bind one +- usb_find_and_bind_driver() searches all available USB drivers (declared + with USB_DEVICE()). If it finds a match it binds that driver to create a + new device. +- If it does not, it binds a generic driver. A generic driver is good enough + to allow access to the device (sending it packets, etc.) but all + functionality will need to be implemented outside the driver model. +- in any case, when usb_find_child() and/or usb_find_and_bind_driver() are + done, we have a device with the correct uclass. At this point we want to + probe the device +- first we store basic information about the new device (address, port, + speed) in its parent platform data. We cannot store it its private data + since that will not exist until the device is probed. +- then we call device_probe() which probes the device +- the first probe step is actually the USB controller's (or USB hubs's) + child_pre_probe() method. This gets called before anything else and is + intended to set up a child device ready to be used with its parent bus. For + USB this calls usb_child_pre_probe() which grabs the information that was + stored in the parent platform data and stores it in the parent private data + (which is struct usb_device, a real one this time). It then calls + usb_select_config() again to make sure that everything about the device is + set up +- note that we have called usb_select_config() twice. This is inefficient + but the alternative is to store additional information in the platform data. + The time taken is minimal and this way is simpler +- at this point the device is set up and ready for use so far as the USB + subsystem is concerned +- the device's probe() method is then called. It can send messages and do + whatever else it wants to make the device work. + +Note that the first device is always a root hub, and this must be scanned to +find any devices. The above steps will have created a hub (UCLASS_USB_HUB), +given it address 1 and set the configuration. + +For hubs, the hub uclass has a post_probe() method. This means that after +any hub is probed, the uclass gets to do some processing. In this case +usb_hub_post_probe() is called, and the following steps take place: + +- usb_hub_post_probe() calls usb_hub_scan() to scan the hub, which in turn + calls usb_hub_configure() +- hub power is enabled +- we loop through each port on the hub, performing the same steps for each +- first, check if there is a device present. This happens in + usb_hub_port_connect_change(). If so, then usb_scan_device() is called to + scan the device, passing the appropriate port number. +- you will recognise usb_scan_device() from the steps above. It sets up the + device ready for use. If it is a hub, it will scan that hub before it + continues here (recursively, depth-first) +- once all hub ports are scanned in this way, the hub is ready for use and + all of its downstream devices also +- additional controllers are scanned in the same way + +The above method has some nice properties: + +- the bus enumeration happens by virtue of driver model's natural device flow +- most logic is in the USB controller and hub uclasses; the actual device + drivers do not need to know they are on a USB bus, at least so far as + enumeration goes +- hub scanning happens automatically after a hub is probed + + +Hubs +---- + +USB hubs are scanned as in the section above. While hubs have their own +uclass, they share some common elements with controllers: + +- they both attach private data to their children (struct usb_device, + accessible for a child with dev_get_parent_priv(child)) +- they both use usb_child_pre_probe() to set up their children as proper USB + devices + + +Example - Mass Storage +---------------------- + +As an example of a USB device driver, see usb_storage.c. It uses its own +uclass and declares itself as follows: + +.. code-block:: c + + U_BOOT_DRIVER(usb_mass_storage) = { + .name = "usb_mass_storage", + .id = UCLASS_MASS_STORAGE, + .of_match = usb_mass_storage_ids, + .probe = usb_mass_storage_probe, + }; + + static const struct usb_device_id mass_storage_id_table[] = { + { .match_flags = USB_DEVICE_ID_MATCH_INT_CLASS, + .bInterfaceClass = USB_CLASS_MASS_STORAGE}, + { } /* Terminating entry */ + }; + + USB_DEVICE(usb_mass_storage, mass_storage_id_table); + +The USB_DEVICE() macro attaches the given table of matching information to +the given driver. Note that the driver is declared in U_BOOT_DRIVER() as +'usb_mass_storage' and this must match the first parameter of USB_DEVICE. + +When usb_find_and_bind_driver() is called on a USB device with the +bInterfaceClass value of USB_CLASS_MASS_STORAGE, it will automatically find +this driver and use it. + + +Counter-example: USB Ethernet +----------------------------- + +As an example of the old way of doing things, see usb_ether.c. When the bus +is scanned, all Ethernet devices will be created as generic USB devices (in +uclass UCLASS_USB_DEV_GENERIC). Then, when the scan is completed, +usb_host_eth_scan() will be called. This looks through all the devices on +each bus and manually figures out which are Ethernet devices in the ways of +yore. + +In fact, usb_ether should be moved to driver model. Each USB Ethernet driver +(e.g drivers/usb/eth/asix.c) should include a USB_DEVICE() declaration, so +that it will be found as part of normal USB enumeration. Then, instead of a +generic USB driver, a real (driver-model-aware) driver will be used. Since +Ethernet now supports driver model, this should be fairly easy to achieve, +and then usb_ether.c and the usb_host_eth_scan() will melt away. + + +Sandbox +------- + +All driver model uclasses must have tests and USB is no exception. To +achieve this, a sandbox USB controller is provided. This can make use of +emulation drivers which pretend to be USB devices. Emulations are provided +for a hub and a flash stick. These are enough to create a pretend USB bus +(defined by the sandbox device tree sandbox.dts) which can be scanned and +used. + +Tests in test/dm/usb.c make use of this feature. It allows much of the USB +stack to be tested without real hardware being needed. + +Here is an example device tree fragment: + +.. code-block:: none + + usb@1 { + compatible = "sandbox,usb"; + hub { + compatible = "usb-hub"; + usb,device-class = <USB_CLASS_HUB>; + hub-emul { + compatible = "sandbox,usb-hub"; + #address-cells = <1>; + #size-cells = <0>; + flash-stick { + reg = <0>; + compatible = "sandbox,usb-flash"; + sandbox,filepath = "flash.bin"; + }; + }; + }; + }; + +This defines a single controller, containing a root hub (which is required). +The hub is emulated by a hub emulator, and the emulated hub has a single +flash stick to emulate on one of its ports. + +When 'usb start' is used, the following 'dm tree' output will be available:: + + usb [ + ] `-- usb@1 + usb_hub [ + ] `-- hub + usb_emul [ + ] |-- hub-emul + usb_emul [ + ] | `-- flash-stick + usb_mass_st [ + ] `-- usb_mass_storage + + +This may look confusing. Most of it mirrors the device tree, but the +'usb_mass_storage' device is not in the device tree. This is created by +usb_find_and_bind_driver() based on the USB_DRIVER in usb_storage.c. While +'flash-stick' is the emulation device, 'usb_mass_storage' is the real U-Boot +USB device driver that talks to it. + + +Future work +----------- + +It is pretty uncommon to have a large USB bus with lots of hubs on an +embedded system. In fact anything other than a root hub is uncommon. Still +it would be possible to speed up enumeration in two ways: + +- breadth-first search would allow devices to be reset and probed in + parallel to some extent +- enumeration could be lazy, in the sense that we could enumerate just the + root hub at first, then only progress to the next 'level' when a device is + used that we cannot find. This could be made easier if the devices were + statically declared in the device tree (which is acceptable for production + boards where the same, known, things are on each bus). + +But in common cases the current algorithm is sufficient. + +Other things that need doing: +- Convert usb_ether to use driver model as described above +- Test that keyboards work (and convert to driver model) +- Move the USB gadget framework to driver model +- Implement OHCI in driver model +- Implement USB PHYs in driver model +- Work out a clever way to provide lazy init for USB devices + + +.. Simon Glass <sjg@chromium.org> +.. 23-Mar-15 diff --git a/roms/u-boot/doc/develop/driver-model/virtio.rst b/roms/u-boot/doc/develop/driver-model/virtio.rst new file mode 100644 index 000000000..8ac9c94ca --- /dev/null +++ b/roms/u-boot/doc/develop/driver-model/virtio.rst @@ -0,0 +1,287 @@ +.. SPDX-License-Identifier: GPL-2.0+ +.. sectionauthor:: Bin Meng <bmeng.cn@gmail.com> + +VirtIO Support +============== + +This document describes the information about U-Boot support for VirtIO_ +devices, including supported boards, build instructions, driver details etc. + +What's VirtIO? +-------------- +VirtIO is a virtualization standard for network and disk device drivers where +just the guest's device driver "knows" it is running in a virtual environment, +and cooperates with the hypervisor. This enables guests to get high performance +network and disk operations, and gives most of the performance benefits of +paravirtualization. In the U-Boot case, the guest is U-Boot itself, while the +virtual environment are normally QEMU_ targets like ARM, RISC-V and x86. + +Status +------ +VirtIO can use various different buses, aka transports as described in the +spec. While VirtIO devices are commonly implemented as PCI devices on x86, +embedded devices models like ARM/RISC-V, which does not normally come with +PCI support might use simple memory mapped device (MMIO) instead of the PCI +device. The memory mapped virtio device behaviour is based on the PCI device +specification. Therefore most operations including device initialization, +queues configuration and buffer transfers are nearly identical. Both MMIO +and PCI transport options are supported in U-Boot. + +The VirtIO spec defines a lots of VirtIO device types, however at present only +network and block device, the most two commonly used devices, are supported. + +The following QEMU targets are supported. + + - qemu_arm_defconfig + - qemu_arm64_defconfig + - qemu-riscv32_defconfig + - qemu-riscv64_defconfig + - qemu-x86_defconfig + - qemu-x86_64_defconfig + +Note ARM and RISC-V targets are configured with VirtIO MMIO transport driver, +and on x86 it's the PCI transport driver. + +Build Instructions +------------------ +Building U-Boot for pre-configured QEMU targets is no different from others. +For example, we can do the following with the CROSS_COMPILE environment +variable being properly set to a working toolchain for ARM: + +.. code-block:: bash + + $ make qemu_arm_defconfig + $ make + +You can even create a QEMU ARM target with VirtIO devices showing up on both +MMIO and PCI buses. In this case, you can enable the PCI transport driver +from 'make menuconfig': + +.. code-block:: none + + Device Drivers ---> + ... + VirtIO Drivers ---> + ... + [*] PCI driver for virtio devices + +Other drivers are at the same location and can be tuned to suit the needs. + +Requirements +------------ +It is required that QEMU v2.5.0+ should be used to test U-Boot VirtIO support +on QEMU ARM and x86, and v2.12.0+ on QEMU RISC-V. + +Testing +------- +The following QEMU command line is used to get U-Boot up and running with +VirtIO net and block devices on ARM. + +.. code-block:: bash + + $ qemu-system-arm -nographic -machine virt -bios u-boot.bin \ + -netdev tap,ifname=tap0,id=net0 \ + -device virtio-net-device,netdev=net0 \ + -drive if=none,file=test.img,format=raw,id=hd0 \ + -device virtio-blk-device,drive=hd0 + +On x86, command is slightly different to create PCI VirtIO devices. + +.. code-block:: bash + + $ qemu-system-i386 -nographic -bios u-boot.rom \ + -netdev tap,ifname=tap0,id=net0 \ + -device virtio-net-pci,netdev=net0 \ + -drive if=none,file=test.img,format=raw,id=hd0 \ + -device virtio-blk-pci,drive=hd0 + +Additional net and block devices can be created by appending more '-device' +parameters. It is also possible to specify both MMIO and PCI VirtIO devices. +For example, the following commnad creates 3 VirtIO devices, with 1 on MMIO +and 2 on PCI bus. + +.. code-block:: bash + + $ qemu-system-arm -nographic -machine virt -bios u-boot.bin \ + -netdev tap,ifname=tap0,id=net0 \ + -device virtio-net-pci,netdev=net0 \ + -drive if=none,file=test0.img,format=raw,id=hd0 \ + -device virtio-blk-device,drive=hd0 \ + -drive if=none,file=test1.img,format=raw,id=hd1 \ + -device virtio-blk-pci,drive=hd1 + +By default QEMU creates VirtIO legacy devices by default. To create non-legacy +(aka modern) devices, pass additional device property/value pairs like below: + +.. code-block:: bash + + $ qemu-system-i386 -nographic -bios u-boot.rom \ + -netdev tap,ifname=tap0,id=net0 \ + -device virtio-net-pci,netdev=net0,disable-legacy=true,disable-modern=false \ + -drive if=none,file=test.img,format=raw,id=hd0 \ + -device virtio-blk-pci,drive=hd0,disable-legacy=true,disable-modern=false + +A 'virtio' command is provided in U-Boot shell. + +.. code-block:: none + + => virtio + virtio - virtio block devices sub-system + + Usage: + virtio scan - initialize virtio bus + virtio info - show all available virtio block devices + virtio device [dev] - show or set current virtio block device + virtio part [dev] - print partition table of one or all virtio block devices + virtio read addr blk# cnt - read `cnt' blocks starting at block + `blk#' to memory address `addr' + virtio write addr blk# cnt - write `cnt' blocks starting at block + `blk#' from memory address `addr' + +To probe all the VirtIO devices, type: + +.. code-block:: none + + => virtio scan + +Then we can show the connected block device details by: + +.. code-block:: none + + => virtio info + Device 0: QEMU VirtIO Block Device + Type: Hard Disk + Capacity: 4096.0 MB = 4.0 GB (8388608 x 512) + +And list the directories and files on the disk by: + +.. code-block:: none + + => ls virtio 0 / + <DIR> 4096 . + <DIR> 4096 .. + <DIR> 16384 lost+found + <DIR> 4096 dev + <DIR> 4096 proc + <DIR> 4096 sys + <DIR> 4096 var + <DIR> 4096 etc + <DIR> 4096 usr + <SYM> 7 bin + <SYM> 8 sbin + <SYM> 7 lib + <SYM> 9 lib64 + <DIR> 4096 run + <DIR> 4096 boot + <DIR> 4096 home + <DIR> 4096 media + <DIR> 4096 mnt + <DIR> 4096 opt + <DIR> 4096 root + <DIR> 4096 srv + <DIR> 4096 tmp + 0 .autorelabel + +Driver Internals +---------------- +There are 3 level of drivers in the VirtIO driver family. + +.. code-block:: none + + +---------------------------------------+ + | virtio device drivers | + | +-------------+ +------------+ | + | | virtio-net | | virtio-blk | | + | +-------------+ +------------+ | + +---------------------------------------+ + +---------------------------------------+ + | virtio transport drivers | + | +-------------+ +------------+ | + | | virtio-mmio | | virtio-pci | | + | +-------------+ +------------+ | + +---------------------------------------+ + +----------------------+ + | virtio uclass driver | + +----------------------+ + +The root one is the virtio uclass driver (virtio-uclass.c), which does lots of +common stuff for the transport drivers (virtio_mmio.c, virtio_pci.c). The real +virtio device is discovered in the transport driver's probe() method, and its +device ID is saved in the virtio uclass's private data of the transport device. +Then in the virtio uclass's post_probe() method, the real virtio device driver +(virtio_net.c, virtio_blk.c) is bound if there is a match on the device ID. + +The child_post_bind(), child_pre_probe() and child_post_probe() methods of the +virtio uclass driver help bring the virtio device driver online. They do things +like acknowledging device, feature negotiation, etc, which are really common +for all virtio devices. + +The transport drivers provide a set of ops (struct dm_virtio_ops) for the real +virtio device driver to call. These ops APIs's parameter is designed to remind +the caller to pass the correct 'struct udevice' id of the virtio device, eg: + +.. code-block:: C + + int virtio_get_status(struct udevice *vdev, u8 *status) + +So the parameter 'vdev' indicates the device should be the real virtio device. +But we also have an API like: + +.. code-block:: C + + struct virtqueue *vring_create_virtqueue(unsigned int index, unsigned int num, + unsigned int vring_align, + struct udevice *udev) + +Here the parameter 'udev' indicates the device should be the transport device. +Similar naming is applied in other functions that are even not APIs, eg: + +.. code-block:: C + + static int virtio_uclass_post_probe(struct udevice *udev) + static int virtio_uclass_child_pre_probe(struct udevice *vdev) + +So it's easy to tell which device these functions are operating on. + +Development Flow +---------------- +At present only VirtIO network card (device ID 1) and block device (device +ID 2) are supported. If you want to develop new driver for new devices, +please follow the guideline below. + +1. add new device ID in virtio.h + +.. code-block:: C + + #define VIRTIO_ID_XXX X + +2. update VIRTIO_ID_MAX_NUM to be the largest device ID plus 1 + +3. add new driver name string in virtio.h + +.. code-block:: C + + #define VIRTIO_XXX_DRV_NAME "virtio-xxx" + +4. create a new driver with name set to the name string above + +.. code-block:: C + + U_BOOT_DRIVER(virtio_xxx) = { + .name = VIRTIO_XXX_DRV_NAME, + ... + .remove = virtio_reset, + .flags = DM_FLAG_ACTIVE_DMA, + } + +Note the driver needs to provide the remove method and normally this can be +hooked to virtio_reset(). The driver flags should contain DM_FLAG_ACTIVE_DMA +for the remove method to be called before jumping to OS. + +5. provide bind() method in the driver, where virtio_driver_features_init() + should be called for driver to negotiate feature support with the device. + +6. do funny stuff with the driver + +.. _VirtIO: http://docs.oasis-open.org/virtio/virtio/v1.0/virtio-v1.0.pdf +.. _QEMU: https://www.qemu.org diff --git a/roms/u-boot/doc/develop/global_data.rst b/roms/u-boot/doc/develop/global_data.rst new file mode 100644 index 000000000..230ebcd86 --- /dev/null +++ b/roms/u-boot/doc/develop/global_data.rst @@ -0,0 +1,55 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +Global data +=========== + +Globally required fields are held in the global data structure. A pointer to the +structure is available as symbol gd. The symbol is made available by the macro +%DECLARE_GLOBAL_DATA_PTR. + +Register pointing to global data +-------------------------------- + +On most architectures the global data pointer is stored in a register. + ++------------+----------+ +| ARC | r25 | ++------------+----------+ +| ARM 32bit | r9 | ++------------+----------+ +| ARM 64bit | x18 | ++------------+----------+ +| M68000 | d7 | ++------------+----------+ +| MicroBlaze | r31 | ++------------+----------+ +| NDS32 | r10 | ++------------+----------+ +| Nios II | gp | ++------------+----------+ +| PowerPC | r2 | ++------------+----------+ +| RISC-V | gp (x3) | ++------------+----------+ +| SuperH | r13 | ++------------+----------+ +| x86 32bit | fs | ++------------+----------+ + +The sandbox, x86_64, and Xtensa are notable exceptions. + +Clang for ARM does not support assigning a global register. When using Clang +gd is defined as an inline function using assembly code. This adds a few bytes +to the code size. + +Binaries called by U-Boot are not aware of the register usage and will not +conserve gd. UEFI binaries call the API provided by U-Boot and may return to +U-Boot. The value of gd has to be saved every time U-Boot is left and restored +whenever U-Boot is reentered. This is also relevant for the implementation of +function tracing. For setting the value of gd function set_gd() can be used. + +Global data structure +--------------------- + +.. kernel-doc:: include/asm-generic/global_data.h + :internal: diff --git a/roms/u-boot/doc/develop/index.rst b/roms/u-boot/doc/develop/index.rst new file mode 100644 index 000000000..3edffbc63 --- /dev/null +++ b/roms/u-boot/doc/develop/index.rst @@ -0,0 +1,47 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +Develop U-Boot +============== + +Implementation +-------------- + +.. toctree:: + :maxdepth: 1 + + commands + driver-model/index + global_data + logging + menus + uefi/index + version + +Debugging +--------- + +.. toctree:: + :maxdepth: 1 + + crash_dumps + trace + +Packaging +--------- + +.. toctree:: + :maxdepth: 1 + + package/index + +Testing +------- + +.. toctree:: + :maxdepth: 1 + + coccinelle + testing + py_testing + tests_writing + tests_sandbox diff --git a/roms/u-boot/doc/develop/logging.rst b/roms/u-boot/doc/develop/logging.rst new file mode 100644 index 000000000..f4e925048 --- /dev/null +++ b/roms/u-boot/doc/develop/logging.rst @@ -0,0 +1,319 @@ +.. SPDX-License-Identifier: GPL-2.0+ +.. Copyright (c) 2017 Simon Glass <sjg@chromium.org> + +Logging in U-Boot +================= + +Introduction +------------ + +U-Boot's internal operation involves many different steps and actions. From +setting up the board to displaying a start-up screen to loading an Operating +System, there are many component parts each with many actions. + +Most of the time this internal detail is not useful. Displaying it on the +console would delay booting (U-Boot's primary purpose) and confuse users. + +But for digging into what is happening in a particular area, or for debugging +a problem it is often useful to see what U-Boot is doing in more detail than +is visible from the basic console output. + +U-Boot's logging feature aims to satisfy this goal for both users and +developers. + +Logging levels +-------------- + +There are a number logging levels available. + +See enum :c:type:`log_level_t` + +Logging category +---------------- + +Logging can come from a wide variety of places within U-Boot. Each log message +has a category which is intended to allow messages to be filtered according to +their source. + +See enum :c:type:`log_category_t` + +Enabling logging +---------------- + +The following options are used to enable logging at compile time: + +* CONFIG_LOG - Enables the logging system +* CONFIG_LOG_MAX_LEVEL - Max log level to build (anything higher is compiled + out) +* CONFIG_LOG_CONSOLE - Enable writing log records to the console + +If CONFIG_LOG is not set, then no logging will be available. + +The above have SPL and TPL versions also, e.g. CONFIG_SPL_LOG_MAX_LEVEL and +CONFIG_TPL_LOG_MAX_LEVEL. + +Temporary logging within a single file +-------------------------------------- + +Sometimes it is useful to turn on logging just in one file. You can use this + +.. code-block:: c + + #define LOG_DEBUG + +to enable building in of all logging statements in a single file. Put it at +the top of the file, before any #includes. + +To actually get U-Boot to output this you need to also set the default logging +level - e.g. set CONFIG_LOG_DEFAULT_LEVEL to 7 (:c:data:`LOGL_DEBUG`) or more. +Otherwise debug output is suppressed and will not be generated. + +Using DEBUG +----------- + +U-Boot has traditionally used a #define called DEBUG to enable debugging on a +file-by-file basis. The debug() macro compiles to a printf() statement if +DEBUG is enabled, and an empty statement if not. + +With logging enabled, debug() statements are interpreted as logging output +with a level of LOGL_DEBUG and a category of LOGC_NONE. + +The logging facilities are intended to replace DEBUG, but if DEBUG is defined +at the top of a file, then it takes precedence. This means that debug() +statements will result in output to the console and this output will not be +logged. + +Logging statements +------------------ + +The main logging function is: + +.. code-block:: c + + log(category, level, format_string, ...) + +Also debug() and error() will generate log records - these use LOG_CATEGORY +as the category, so you should #define this right at the top of the source +file to ensure the category is correct. + +Generally each log format_string ends with a newline. If it does not, then the +next log statement will have the LOGRECF_CONT flag set. This can be used to +continue the statement on the same line as the previous one without emitting +new header information (such as category/level). This behaviour is implemented +with log_console. Here is an example that prints a list all on one line with +the tags at the start: + +.. code-block:: c + + log_debug("Here is a list:"); + for (i = 0; i < count; i++) + log_debug(" item %d", i); + log_debug("\n"); + +Also see the special category LOGL_CONT and level LOGC_CONT. + +You can also define CONFIG_LOG_ERROR_RETURN to enable the log_ret() macro. This +can be used whenever your function returns an error value: + +.. code-block:: c + + return log_ret(uclass_first_device_err(UCLASS_MMC, &dev)); + +This will write a log record when an error code is detected (a value < 0). This +can make it easier to trace errors that are generated deep in the call stack. + +The log_msg_ret() variant will print a short string if CONFIG_LOG_ERROR_RETURN +is enabled. So long as the string is unique within the function you can normally +determine exactly which call failed: + +.. code-block:: c + + ret = gpio_request_by_name(dev, "cd-gpios", 0, &desc, GPIOD_IS_IN); + if (ret) + return log_msg_ret("gpio", ret); + +Some functions return 0 for success and any other value is an error. For these, +log_retz() and log_msg_retz() are available. + +Convenience functions +~~~~~~~~~~~~~~~~~~~~~ + +A number of convenience functions are available to shorten the code needed +for logging: + +* log_err(_fmt...) +* log_warning(_fmt...) +* log_notice(_fmt...) +* log_info(_fmt...) +* log_debug(_fmt...) +* log_content(_fmt...) +* log_io(_fmt...) + +With these the log level is implicit in the name. The category is set by +LOG_CATEGORY, which you can only define once per file, above all #includes, e.g. + +.. code-block:: c + + #define LOG_CATEGORY LOGC_ALLOC + +or + +.. code-block:: c + + #define LOG_CATEGORY UCLASS_SPI + +Remember that all uclasses IDs are log categories too. + +Logging destinations +-------------------- + +If logging information goes nowhere then it serves no purpose. U-Boot provides +several possible determinations for logging information, all of which can be +enabled or disabled independently: + +* console - goes to stdout +* syslog - broadcast RFC 3164 messages to syslog servers on UDP port 514 + +The syslog driver sends the value of environmental variable 'log_hostname' as +HOSTNAME if available. + +Filters +------- + +Filters are attached to log drivers to control what those drivers emit. FIlters +can either allow or deny a log message when they match it. Only records which +are allowed by a filter make it to the driver. + +Filters can be based on several criteria: + +* minimum or maximum log level +* in a set of categories +* in a set of files + +If no filters are attached to a driver then a default filter is used, which +limits output to records with a level less than CONFIG_MAX_LOG_LEVEL. + +Log command +----------- + +The 'log' command provides access to several features: + +* level - list log levels or set the default log level +* categories - list log categories +* drivers - list log drivers +* filter-list - list filters +* filter-add - add a new filter +* filter-remove - remove filters +* format - access the console log format +* rec - output a log record + +Type 'help log' for details. + +Log format +~~~~~~~~~~ + +You can control the log format using the 'log format' command. The basic +format is:: + + LEVEL.category,file.c:123-func() message + +In the above, file.c:123 is the filename where the log record was generated and +func() is the function name. By default ('log format default') only the message +is displayed on the console. You can control which fields are present, but not +the field order. + +Adding Filters +~~~~~~~~~~~~~~ + +To add new filters at runtime, use the 'log filter-add' command. For example, to +suppress messages from the SPI and MMC subsystems, run:: + + log filter-add -D -c spi -c mmc + +You will also need to add another filter to allow other messages (because the +default filter no longer applies):: + + log filter-add -A -l info + +Log levels may be either symbolic names (like above) or numbers. For example, to +disable all debug and above (log level 7) messages from ``drivers/core/lists.c`` +and ``drivers/core/ofnode.c``, run:: + + log filter-add -D -f drivers/core/lists.c,drivers/core/ofnode.c -L 7 + +To view active filters, use the 'log filter-list' command. Some example output +is:: + + => log filter-list + num policy level categories files + 2 deny >= DEBUG drivers/core/lists.c,drivers/core/ofnode.c + 0 deny <= IO spi + mmc + 1 allow <= INFO + +Note that filters are processed in-order from top to bottom, not in the order of +their filter number. Filters are added to the top of the list if they deny when +they match, and to the bottom if they allow when they match. For more +information, consult the usage of the 'log' command, by running 'help log'. + +Code size +--------- + +Code size impact depends largely on what is enabled. The following numbers are +generated by 'buildman -S' for snow, which is a Thumb-2 board (all units in +bytes):: + + This series: adds bss +20.0 data +4.0 rodata +4.0 text +44.0 + CONFIG_LOG: bss -52.0 data +92.0 rodata -635.0 text +1048.0 + CONFIG_LOG_MAX_LEVEL=7: bss +188.0 data +4.0 rodata +49183.0 text +98124.0 + +The last option turns every debug() statement into a logging call, which +bloats the code hugely. The advantage is that it is then possible to enable +all logging within U-Boot. + +To Do +----- + +There are lots of useful additions that could be made. None of the below is +implemented! If you do one, please add a test in test/log/log_test.c +log filter-add -D -f drivers/core/lists.c,drivers/core/ofnode.c -l 6 +Convenience functions to support setting the category: + +* log_arch(level, format_string, ...) - category LOGC_ARCH +* log_board(level, format_string, ...) - category LOGC_BOARD +* log_core(level, format_string, ...) - category LOGC_CORE +* log_dt(level, format_string, ...) - category LOGC_DT + +More logging destinations: + +* device - goes to a device (e.g. serial) +* buffer - recorded in a memory buffer + +Convert debug() statements in the code to log() statements + +Support making printf() emit log statements at L_INFO level + +Convert error() statements in the code to log() statements + +Figure out what to do with BUG(), BUG_ON() and warn_non_spl() + +Add a way to browse log records + +Add a way to record log records for browsing using an external tool + +Add commands to add and remove log devices + +Allow sharing of printf format strings in log records to reduce storage size +for large numbers of log records + +Consider making log() calls emit an automatic newline, perhaps with a logn() +function to avoid that + +Passing log records through to linux (e.g. via device tree /chosen) + +Provide a command to access the number of log records generated, and the +number dropped due to them being generated before the log system was ready. + +Add a printf() format string pragma so that log statements are checked properly + +Add a command to delete existing log records. diff --git a/roms/u-boot/doc/develop/menus.rst b/roms/u-boot/doc/develop/menus.rst new file mode 100644 index 000000000..dda8f963f --- /dev/null +++ b/roms/u-boot/doc/develop/menus.rst @@ -0,0 +1,131 @@ +.. SPDX-License-Identifier: GPL-2.0+ +.. Copyright 2010-2011 Calxeda, Inc. + +Menus +===== + +U-Boot provides a set of interfaces for creating and using simple, text +based menus. Menus are displayed as lists of labeled entries on the +console, and an entry can be selected by entering its label. + +To use the menu code, enable CONFIG_MENU, and include "menu.h" where +the interfaces should be available. + +Menus are composed of items. Each item has a key used to identify it in +the menu, and an opaque pointer to data controlled by the consumer. + +If you want to show a menu, instead starting the shell, define +CONFIG_AUTOBOOT_MENU_SHOW. You have to code the int menu_show(int bootdelay) +function, which handle your menu. This function returns the remaining +bootdelay. + +Interfaces +---------- + +.. code-block:: c + + #include "menu.h" + + /* + * Consumers of the menu interfaces will use a struct menu * as the + * handle for a menu. struct menu is only fully defined in menu.c, + * preventing consumers of the menu interfaces from accessing its + * contents directly. + */ + struct menu; + + /* + * NOTE: See comments in common/menu.c for more detailed documentation on + * these interfaces. + */ + + /* + * menu_create() - Creates a menu handle with default settings + */ + struct menu *menu_create(char *title, int timeout, int prompt, + void (*item_data_print)(void *), + char *(*item_choice)(void *), + void *item_choice_data); + + /* + * menu_item_add() - Adds or replaces a menu item + */ + int menu_item_add(struct menu *m, char *item_key, void *item_data); + + /* + * menu_default_set() - Sets the default choice for the menu + */ + int menu_default_set(struct menu *m, char *item_key); + + /* + * menu_default_choice() - Set *choice to point to the default item's data + */ + int menu_default_choice(struct menu *m, void **choice); + + /* + * menu_get_choice() - Returns the user's selected menu entry, or the + * default if the menu is set to not prompt or the timeout expires. + */ + int menu_get_choice(struct menu *m, void **choice); + + /* + * menu_destroy() - frees the memory used by a menu and its items. + */ + int menu_destroy(struct menu *m); + + /* + * menu_display_statusline(struct menu *m); + * shows a statusline for every menu_display call. + */ + void menu_display_statusline(struct menu *m); + +Example Code +------------ + +This example creates a menu that always prompts, and allows the user +to pick from a list of tools. The item key and data are the same. + +.. code-block:: c + + #include "menu.h" + + char *tools[] = { + "Hammer", + "Screwdriver", + "Nail gun", + NULL + }; + + char *pick_a_tool(void) + { + struct menu *m; + int i; + char *tool = NULL; + + m = menu_create("Tools", 0, 1, NULL); + + for(i = 0; tools[i]; i++) { + if (menu_item_add(m, tools[i], tools[i]) != 1) { + printf("failed to add item!"); + menu_destroy(m); + return NULL; + } + } + + if (menu_get_choice(m, (void **)&tool) != 1) + printf("Problem picking tool!\n"); + + menu_destroy(m); + + return tool; + } + + void caller(void) + { + char *tool = pick_a_tool(); + + if (tool) { + printf("picked a tool: %s\n", tool); + use_tool(tool); + } + } diff --git a/roms/u-boot/doc/develop/package/binman.rst b/roms/u-boot/doc/develop/package/binman.rst new file mode 120000 index 000000000..2e26e84b7 --- /dev/null +++ b/roms/u-boot/doc/develop/package/binman.rst @@ -0,0 +1 @@ +../../../tools/binman/binman.rst
\ No newline at end of file diff --git a/roms/u-boot/doc/develop/package/entries.rst b/roms/u-boot/doc/develop/package/entries.rst new file mode 120000 index 000000000..ecedcebaa --- /dev/null +++ b/roms/u-boot/doc/develop/package/entries.rst @@ -0,0 +1 @@ +../../../tools/binman/entries.rst
\ No newline at end of file diff --git a/roms/u-boot/doc/develop/package/index.rst b/roms/u-boot/doc/develop/package/index.rst new file mode 100644 index 000000000..9374be2e6 --- /dev/null +++ b/roms/u-boot/doc/develop/package/index.rst @@ -0,0 +1,19 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +Package U-Boot +============== + +U-Boot uses Flat Image Tree (FIT) as a standard file format for packaging +images that it it reads and boots. Documentation about FIT is available at +doc/uImage.FIT + +U-Boot also provides binman for cases not covered by FIT. Examples include +initial execution (since FIT itself does not have an executable header) and +dealing with device boundaries, such as the read-only/read-write separation in +SPI flash. + + +.. toctree:: + :maxdepth: 2 + + binman diff --git a/roms/u-boot/doc/develop/py_testing.rst b/roms/u-boot/doc/develop/py_testing.rst new file mode 100644 index 000000000..c4cecc0a0 --- /dev/null +++ b/roms/u-boot/doc/develop/py_testing.rst @@ -0,0 +1,427 @@ +U-Boot pytest suite +=================== + +Introduction +------------ + +This tool aims to test U-Boot by executing U-Boot shell commands using the +console interface. A single top-level script exists to execute or attach to the +U-Boot console, run the entire script of tests against it, and summarize the +results. Advantages of this approach are: + +- Testing is performed in the same way a user or script would interact with + U-Boot; there can be no disconnect. +- There is no need to write or embed test-related code into U-Boot itself. + It is asserted that writing test-related code in Python is simpler and more + flexible than writing it all in C. But see :doc:`tests_writing` for caveats + and more discussion / analysis. +- It is reasonably simple to interact with U-Boot in this way. + +Requirements +------------ + +The test suite is implemented using pytest. Interaction with the U-Boot console +involves executing some binary and interacting with its stdin/stdout. You will +need to implement various "hook" scripts that are called by the test suite at +the appropriate time. + +In order to run the test suite at a minimum we require that both Python 3 and +pip for Python 3 are installed. All of the required python modules are +described in the requirements.txt file in the /test/py/ directory and can be +installed via the command + +.. code-block:: bash + + pip install -r requirements.txt + +In order to execute certain tests on their supported platforms other tools +will be required. The following is an incomplete list: + +* gdisk +* dfu-util +* dtc +* openssl +* sudo OR guestmount +* e2fsprogs +* util-linux +* coreutils +* dosfstools +* efitools +* mount +* mtools +* sbsigntool +* udisks2 + +Please use the appropriate commands for your distribution to match these tools +up with the package that provides them. + +The test script supports either: + +- Executing a sandbox port of U-Boot on the local machine as a sub-process, + and interacting with it over stdin/stdout. +- Executing an external "hook" scripts to flash a U-Boot binary onto a + physical board, attach to the board's console stream, and reset the board. + Further details are described later. + +Using `virtualenv` to provide requirements +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The recommended way to run the test suite, in order to ensure reproducibility +is to use `virtualenv` to set up the necessary environment. This can be done +via the following commands: + + +.. code-block:: console + + $ cd /path/to/u-boot + $ sudo apt-get install python3 python3-virtualenv + $ virtualenv -p /usr/bin/python3 venv + $ . ./venv/bin/activate + $ pip install -r test/py/requirements.txt + +Testing sandbox +--------------- + +To run the test suite on the sandbox port (U-Boot built as a native user-space +application), simply execute: + +.. code-block:: bash + + ./test/py/test.py --bd sandbox --build + +The `--bd` option tells the test suite which board type is being tested. This +lets the test suite know which features the board has, and hence exactly what +can be tested. + +The `--build` option tells U-Boot to compile U-Boot. Alternatively, you may +omit this option and build U-Boot yourself, in whatever way you choose, before +running the test script. + +The test script will attach to U-Boot, execute all valid tests for the board, +then print a summary of the test process. A complete log of the test session +will be written to `${build_dir}/test-log.html`. This is best viewed in a web +browser, but may be read directly as plain text, perhaps with the aid of the +`html2text` utility. + +Testing under a debugger +~~~~~~~~~~~~~~~~~~~~~~~~ + +If you need to run sandbox under a debugger, you may pass the command-line +option `--gdbserver COMM`. This causes two things to happens: + +- Instead of running U-Boot directly, it will be run under gdbserver, with + debug communication via the channel `COMM`. You can attach a debugger to the + sandbox process in order to debug it. See `man gdbserver` and the example + below for details of valid values for `COMM`. +- All timeouts in tests are disabled, allowing U-Boot an arbitrary amount of + time to execute commands. This is useful if U-Boot is stopped at a breakpoint + during debugging. + +A usage example is: + +Window 1: + +.. code-block:: bash + + ./test/py/test.py --bd sandbox --gdbserver localhost:1234 + +Window 2: + +.. code-block:: bash + + gdb ./build-sandbox/u-boot -ex 'target remote localhost:1234' + +Alternatively, you could leave off the `-ex` option and type the command +manually into gdb once it starts. + +You can use any debugger you wish, as long as it speaks the gdb remote +protocol, or any graphical wrapper around gdb. + +Some tests deliberately cause the sandbox process to exit, e.g. to test the +reset command, or sandbox's CTRL-C handling. When this happens, you will need +to attach the debugger to the new sandbox instance. If these tests are not +relevant to your debugging session, you can skip them using pytest's -k +command-line option; see the next section. + +Command-line options +-------------------- + +--board-type, --bd, -B + set the type of the board to be tested. For example, `sandbox` or `seaboard`. + +--board-identity`, --id + sets the identity of the board to be tested. This allows differentiation + between multiple instances of the same type of physical board that are + attached to the same host machine. This parameter is not interpreted by th + test script in any way, but rather is simply passed to the hook scripts + described below, and may be used in any site-specific way deemed necessary. + +--build + indicates that the test script should compile U-Boot itself before running + the tests. If using this option, make sure that any environment variables + required by the build process are already set, such as `$CROSS_COMPILE`. + +--buildman + indicates that `--build` should use buildman to build U-Boot. There is no need + to set $CROSS_COMPILE` in this case since buildman handles it. + +--build-dir + sets the directory containing the compiled U-Boot binaries. If omitted, this + is `${source_dir}/build-${board_type}`. + +--result-dir + sets the directory to write results, such as log files, into. + If omitted, the build directory is used. + +--persistent-data-dir + sets the directory used to store persistent test data. This is test data that + may be re-used across test runs, such as file-system images. + +`pytest` also implements a number of its own command-line options. Commonly used +options are mentioned below. Please see `pytest` documentation for complete +details. Execute `py.test --version` for a brief summary. Note that U-Boot's +test.py script passes all command-line arguments directly to `pytest` for +processing. + +-k + selects which tests to run. The default is to run all known tests. This + option takes a single argument which is used to filter test names. Simple + logical operators are supported. For example: + + - `'-k ums'` runs only tests with "ums" in their name. + - `'-k ut_dm'` runs only tests with "ut_dm" in their name. Note that in this + case, "ut_dm" is a parameter to a test rather than the test name. The full + test name is e.g. "test_ut[ut_dm_leak]". + - `'-k not reset'` runs everything except tests with "reset" in their name. + - `'-k ut or hush'` runs only tests with "ut" or "hush" in their name. + - `'-k not (ut or hush)'` runs everything except tests with "ut" or "hush" in + their name. + +-s + prevents pytest from hiding a test's stdout. This allows you to see + U-Boot's console log in real time on pytest's stdout. + +Testing real hardware +--------------------- + +The tools and techniques used to interact with real hardware will vary +radically between different host and target systems, and the whims of the user. +For this reason, the test suite does not attempt to directly interact with real +hardware in any way. Rather, it executes a standardized set of "hook" scripts +via `$PATH`. These scripts implement certain actions on behalf of the test +suite. This keeps the test suite simple and isolated from system variances +unrelated to U-Boot features. + +Hook scripts +~~~~~~~~~~~~ + +Environment variables +''''''''''''''''''''' + +The following environment variables are set when running hook scripts: + +- `UBOOT_BOARD_TYPE` the board type being tested. +- `UBOOT_BOARD_IDENTITY` the board identity being tested, or `na` if none was + specified. +- `UBOOT_SOURCE_DIR` the U-Boot source directory. +- `UBOOT_TEST_PY_DIR` the full path to `test/py/` in the source directory. +- `UBOOT_BUILD_DIR` the U-Boot build directory. +- `UBOOT_RESULT_DIR` the test result directory. +- `UBOOT_PERSISTENT_DATA_DIR` the test persistent data directory. + +u-boot-test-console +''''''''''''''''''' + +This script provides access to the U-Boot console. The script's stdin/stdout +should be connected to the board's console. This process should continue to run +indefinitely, until killed. The test suite will run this script in parallel +with all other hooks. + +This script may be implemented e.g. by executing `cu`, `kermit`, `conmux`, etc. +via exec(). + +If you are able to run U-Boot under a hardware simulator such as QEMU, then +you would likely spawn that simulator from this script. However, note that +`u-boot-test-reset` may be called multiple times per test script run, and must +cause U-Boot to start execution from scratch each time. Hopefully your +simulator includes a virtual reset button! If not, you can launch the +simulator from `u-boot-test-reset` instead, while arranging for this console +process to always communicate with the current simulator instance. + +u-boot-test-flash +''''''''''''''''' + +Prior to running the test suite against a board, some arrangement must be made +so that the board executes the particular U-Boot binary to be tested. Often +this involves writing the U-Boot binary to the board's flash ROM. The test +suite calls this hook script for that purpose. + +This script should perform the entire flashing process synchronously; the +script should only exit once flashing is complete, and a board reset will +cause the newly flashed U-Boot binary to be executed. + +It is conceivable that this script will do nothing. This might be useful in +the following cases: + +- Some other process has already written the desired U-Boot binary into the + board's flash prior to running the test suite. +- The board allows U-Boot to be downloaded directly into RAM, and executed + from there. Use of this feature will reduce wear on the board's flash, so + may be preferable if available, and if cold boot testing of U-Boot is not + required. If this feature is used, the `u-boot-test-reset` script should + perform this download, since the board could conceivably be reset multiple + times in a single test run. + +It is up to the user to determine if those situations exist, and to code this +hook script appropriately. + +This script will typically be implemented by calling out to some SoC- or +board-specific vendor flashing utility. + +u-boot-test-reset +''''''''''''''''' + +Whenever the test suite needs to reset the target board, this script is +executed. This is guaranteed to happen at least once, prior to executing the +first test function. If any test fails, the test infra-structure will execute +this script again to restore U-Boot to an operational state before running the +next test function. + +This script will likely be implemented by communicating with some form of +relay or electronic switch attached to the board's reset signal. + +The semantics of this script require that when it is executed, U-Boot will +start running from scratch. If the U-Boot binary to be tested has been written +to flash, pulsing the board's reset signal is likely all this script needs to +do. However, in some scenarios, this script may perform other actions. For +example, it may call out to some SoC- or board-specific vendor utility in order +to download the U-Boot binary directly into RAM and execute it. This would +avoid the need for `u-boot-test-flash` to actually write U-Boot to flash, thus +saving wear on the flash chip(s). + +Examples +'''''''' + +https://source.denx.de/u-boot/u-boot-test-hooks contains some working example hook +scripts, and may be useful as a reference when implementing hook scripts for +your platform. These scripts are not considered part of U-Boot itself. + +Board-type-specific configuration +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Each board has a different configuration and behaviour. Many of these +differences can be automatically detected by parsing the `.config` file in the +build directory. However, some differences can't yet be handled automatically. + +For each board, an optional Python module `u_boot_board_${board_type}` may exist +to provide board-specific information to the test script. Any global value +defined in these modules is available for use by any test function. The data +contained in these scripts must be purely derived from U-Boot source code. +Hence, these configuration files are part of the U-Boot source tree too. + +Execution environment configuration +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Each user's hardware setup may enable testing different subsets of the features +implemented by a particular board's configuration of U-Boot. For example, a +U-Boot configuration may support USB device mode and USB Mass Storage, but this +can only be tested if a USB cable is connected between the board and the host +machine running the test script. + +For each board, optional Python modules `u_boot_boardenv_${board_type}` and +`u_boot_boardenv_${board_type}_${board_identity}` may exist to provide +board-specific and board-identity-specific information to the test script. Any +global value defined in these modules is available for use by any test +function. The data contained in these is specific to a particular user's +hardware configuration. Hence, these configuration files are not part of the +U-Boot source tree, and should be installed outside of the source tree. Users +should set `$PYTHONPATH` prior to running the test script to allow these +modules to be loaded. + +Board module parameter usage +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The test scripts rely on the following variables being defined by the board +module: + +- none at present + +U-Boot `.config` feature usage +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The test scripts rely on various U-Boot `.config` features, either directly in +order to test those features, or indirectly in order to query information from +the running U-Boot instance in order to test other features. + +One example is that testing of the `md` command requires knowledge of a RAM +address to use for the test. This data is parsed from the output of the +`bdinfo` command, and hence relies on CONFIG_CMD_BDI being enabled. + +For a complete list of dependencies, please search the test scripts for +instances of: + +- `buildconfig.get(...` +- `@pytest.mark.buildconfigspec(...` +- `@pytest.mark.notbuildconfigspec(...` + +Complete invocation example +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Assuming that you have installed the hook scripts into $HOME/ubtest/bin, and +any required environment configuration Python modules into $HOME/ubtest/py, +then you would likely invoke the test script as follows: + +If U-Boot has already been built: + +.. code-block:: bash + + PATH=$HOME/ubtest/bin:$PATH \ + PYTHONPATH=${HOME}/ubtest/py/${HOSTNAME}:${PYTHONPATH} \ + ./test/py/test.py --bd seaboard + +If you want the test script to compile U-Boot for you too, then you likely +need to set `$CROSS_COMPILE` to allow this, and invoke the test script as +follows: + +.. code-block:: bash + + CROSS_COMPILE=arm-none-eabi- \ + PATH=$HOME/ubtest/bin:$PATH \ + PYTHONPATH=${HOME}/ubtest/py/${HOSTNAME}:${PYTHONPATH} \ + ./test/py/test.py --bd seaboard --build + +or, using buildman to handle it: + +.. code-block:: bash + + PATH=$HOME/ubtest/bin:$PATH \ + PYTHONPATH=${HOME}/ubtest/py/${HOSTNAME}:${PYTHONPATH} \ + ./test/py/test.py --bd seaboard --build --buildman + +Writing tests +------------- + +Please refer to the pytest documentation for details of writing pytest tests. +Details specific to the U-Boot test suite are described below. + +A test fixture named `u_boot_console` should be used by each test function. This +provides the means to interact with the U-Boot console, and retrieve board and +environment configuration information. + +The function `u_boot_console.run_command()` executes a shell command on the +U-Boot console, and returns all output from that command. This allows +validation or interpretation of the command output. This function validates +that certain strings are not seen on the U-Boot console. These include shell +error messages and the U-Boot sign-on message (in order to detect unexpected +board resets). See the source of `u_boot_console_base.py` for a complete list of +"bad" strings. Some test scenarios are expected to trigger these strings. Use +`u_boot_console.disable_check()` to temporarily disable checking for specific +strings. See `test_unknown_cmd.py` for an example. + +Board- and board-environment configuration values may be accessed as sub-fields +of the `u_boot_console.config` object, for example +`u_boot_console.config.ram_base`. + +Build configuration values (from `.config`) may be accessed via the dictionary +`u_boot_console.config.buildconfig`, with keys equal to the Kconfig variable +names. diff --git a/roms/u-boot/doc/develop/testing.rst b/roms/u-boot/doc/develop/testing.rst new file mode 100644 index 000000000..ced13ac8b --- /dev/null +++ b/roms/u-boot/doc/develop/testing.rst @@ -0,0 +1,126 @@ +Testing in U-Boot +================= + +U-Boot has a large amount of code. This file describes how this code is +tested and what tests you should write when adding a new feature. + + +Running tests +------------- + +To run most tests on sandbox, type this:: + + make check + +in the U-Boot directory. Note that only the pytest suite is run using this +command. + +Some tests take ages to run and are marked with @pytest.mark.slow. To run just +the quick ones, type this:: + + make qcheck + +It is also possible to run just the tests for tools (patman, binman, etc.). +Such tests are included with those tools, i.e. no actual U-Boot unit tests are +run. Type this:: + + make tcheck + +All of the above use the test/run script with a paremeter to select which tests +are run. + + +Sandbox +------- +U-Boot can be built as a user-space application (e.g. for Linux). This +allows test to be executed without needing target hardware. The 'sandbox' +target provides this feature and it is widely used in tests. + +See :doc:`tests_sandbox` for more information. + +Pytest Suite +------------ + +Many tests are available using the pytest suite, in test/py. This can run +either on sandbox or on real hardware. It relies on the U-Boot console to +inject test commands and check the result. It is slower to run than C code, +but provides the ability to unify lots of tests and summarise their results. + +You can run the tests on sandbox with:: + + ./test/py/test.py --bd sandbox --build + +This will produce HTML output in build-sandbox/test-log.html + +Some tests run with other versions of sandbox. For example sandbox_flattree +runs the tests with livetree (the hierachical devicetree) disabled. You can +also select particular tests with -k:: + + ./test/py/test.py --bd sandbox_flattree --build -k hello + +There are some special tests that run in SPL. For this you need the sandbox_spl +build:: + + ./test/py/test.py --bd sandbox_spl --build -k test_spl + +See test/py/README.md for more information about the pytest suite. + +See :doc:`tests_sandbox` for how to run tests directly (not through pytest). + + +tbot +---- + +Tbot provides a way to execute tests on target hardware. It is intended for +trying out both U-Boot and Linux (and potentially other software) on a +number of boards automatically. It can be used to create a continuous test +environment. See http://www.tbot.tools for more information. + + +Ad-hoc tests +------------ + +There are several ad-hoc tests which run outside the pytest environment: + +test/fs + File system test (shell script) +test/image + FIT and legacy image tests (shell script and Python) +test/stdint + A test that stdint.h can be used in U-Boot (shell script) +trace + Test for the tracing feature (shell script) + +TODO: Move these into pytest. + + +When to write tests +------------------- + +If you add code to U-Boot without a test you are taking a risk. Even if you +perform thorough manual testing at the time of submission, it may break when +future changes are made to U-Boot. It may even break when applied to mainline, +if other changes interact with it. A good mindset is that untested code +probably doesn't work and should be deleted. + +You can assume that the Pytest suite will be run before patches are accepted +to mainline, so this provides protection against future breakage. + +On the other hand there is quite a bit of code that is not covered with tests, +or is covered sparingly. So here are some suggestions: + +- If you are adding a new uclass, add a sandbox driver and a test that uses it +- If you are modifying code covered by an existing test, add a new test case + to cover your changes +- If the code you are modifying has not tests, consider writing one. Even a + very basic test is useful, and may be picked up and enhanced by others. It + is much easier to add onto a test - writing a new large test can seem + daunting to most contributors. + +See doc:`tests_writing` for how to write tests. + + +Future work +----------- + +Converting existing shell scripts into pytest tests. diff --git a/roms/u-boot/doc/develop/tests_sandbox.rst b/roms/u-boot/doc/develop/tests_sandbox.rst new file mode 100644 index 000000000..84608dcb8 --- /dev/null +++ b/roms/u-boot/doc/develop/tests_sandbox.rst @@ -0,0 +1,209 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +Sandbox tests +============= + +Test Design +----------- + +Most uclasses and many functions of U-Boot have sandbox tests. This allows much +of the code to be checked in an developer-friendly environment. + +Sandbox provides a way to write and run unit tests. The traditional approach to +unit tests is to build lots of little executables, one for each test or +category of tests. With sandbox, so far as possible, all the tests share a +small number of executables (e.g. 'u-boot' for sandbox, 'u-boot-spl' and +'u-boot' for sandbox_spl) and can be run very quickly. The vast majority of +tests can run on the 'sandbox' build, + +Available tests +--------------- + +Some of the available tests are: + + - command_ut: Unit tests for command parsing and handling + - compression: Unit tests for U-Boot's compression algorithms, useful for + security checking. It supports gzip, bzip2, lzma and lzo. + - image: Unit tests for images: + + - test/image/test-imagetools.sh - multi-file images + - test/py/tests/test-fit.py - FIT images + - tracing: test/trace/test-trace.sh tests the tracing system (see + README.trace) + - verified boot: test/py/tests/test_vboot.py + +If you change or enhance any U-Boot subsystem, you should write or expand a +test and include it with your patch series submission. Test coverage in some +older areas of U-Boot is still somewhat limited and we need to work to improve +it. + +Note that many of these tests are implemented as commands which you can +run natively on your board if desired (and enabled). + +To run all tests, use 'make check'. + + +Running sandbox tests directly +------------------------------ + +Typically tests are run using the pytest suite. Running pytests on sandbox is +easy and always gets things right. For example some tests require files to be +set up before they can work. + +But it is also possible to run some sandbox tests directly. For example, this +runs the dm_test_gpio() test which you can find in test/dm/gpio.c:: + + $ ./u-boot -T -c "ut dm gpio" + + + U-Boot 2021.01 + + Model: sandbox + DRAM: 128 MiB + WDT: Started with servicing (60s timeout) + MMC: mmc2: 2 (SD), mmc1: 1 (SD), mmc0: 0 (SD) + In: serial + Out: vidconsole + Err: vidconsole + Model: sandbox + SCSI: + Net: eth0: eth@10002000, eth5: eth@10003000, eth3: sbe5, eth6: eth@10004000 + Test: dm_test_gpio: gpio.c + Test: dm_test_gpio: gpio.c (flat tree) + Failures: 0 + +The -T option tells the U-Boot sandbox to run with the 'test' devicetree +(test.dts) instead of -D which selects the normal sandbox.dts - this is +necessary because many tests rely on nodes or properties in the test devicetree. +If you try running tests without -T then you may see failures, like:: + + $ ./u-boot -c "ut dm gpio" + + + U-Boot 2021.01 + + DRAM: 128 MiB + WDT: Not found! + MMC: + In: serial + Out: serial + Err: serial + SCSI: + Net: No ethernet found. + Please run with test device tree: + ./u-boot -d arch/sandbox/dts/test.dtb + Test: dm_test_gpio: gpio.c + test/dm/gpio.c:37, dm_test_gpio(): 0 == gpio_lookup_name("b4", &dev, &offset, &gpio): Expected 0x0 (0), got 0xffffffea (-22) + Test: dm_test_gpio: gpio.c (flat tree) + test/dm/gpio.c:37, dm_test_gpio(): 0 == gpio_lookup_name("b4", &dev, &offset, &gpio): Expected 0x0 (0), got 0xffffffea (-22) + Failures: 2 + +The message above should provide a hint if you forget to use the -T flag. Even +running with -D will produce different results. + +You can easily use gdb on these tests, without needing --gdbserver:: + + $ gdb u-boot --args -T -c "ut dm gpio" + ... + (gdb) break dm_test_gpio + Breakpoint 1 at 0x1415bd: file test/dm/gpio.c, line 37. + (gdb) run -T -c "ut dm gpio" + Starting program: u-boot -T -c "ut dm gpio" + Test: dm_test_gpio: gpio.c + + Breakpoint 1, dm_test_gpio (uts=0x5555558029a0 <global_dm_test_state>) + at files/test/dm/gpio.c:37 + 37 ut_assertok(gpio_lookup_name("b4", &dev, &offset, &gpio)); + (gdb) + +You can then single-step and look at variables as needed. + + +Running sandbox_spl tests directly +---------------------------------- + +SPL is the phase before U-Boot proper. It is present in the sandbox_spl build, +so you can run SPL like this:: + + ./spl/u-boot-spl + +SPL tests are special in that they run (only in the SPL phase, of course) if the +-u flag is given:: + + ./spl/u-boot-spl -u + + U-Boot SPL 2021.01-00723-g43c77b51be5-dirty (Jan 24 2021 - 16:38:24 -0700) + Running 5 driver model tests + Test: dm_test_of_plat_base: of_platdata.c (flat tree) + Test: dm_test_of_plat_dev: of_platdata.c (flat tree) + Test: dm_test_of_plat_parent: of_platdata.c (flat tree) + Test: dm_test_of_plat_phandle: of_platdata.c (flat tree) + Test: dm_test_of_plat_props: of_platdata.c (flat tree) + Failures: 0 + + + U-Boot 2021.01-00723-g43c77b51be5-dirty (Jan 24 2021 - 16:38:24 -0700) + + DRAM: 128 MiB + ... + +It is not possible to run SPL tests in U-Boot proper, firstly because they are +not built into U-Boot proper and secondly because the environment is very +different, e.g. some SPL tests rely on of-platdata which is only available in +SPL. + +Note that after running, SPL continues to boot into U-Boot proper. You can add +'-c exit' to make U-Boot quit without doing anything further. It is not +currently possible to run SPL tests and then stop, since the pytests require +that U-Boot produces the expected banner. + +You can use the -k flag to select which tests run:: + + ./spl/u-boot-spl -u -k dm_test_of_plat_parent + +Of course you can use gdb with sandbox_spl, just as with sandbox. + + +Running all tests directly +-------------------------- + +A fast way to run all sandbox tests is:: + + ./u-boot -T -c "ut all" + +It typically runs single-thread in 6 seconds on 2021 hardware, with 2s of that +to the delays in the time test. + +This should not be considered a substitute for 'make check', but can be helpful +for git bisect, etc. + + +What tests are built in? +------------------------ + +Whatever sandbox build is used, which tests are present is determined by which +source files are built. For sandbox_spl, the of_platdata tests are built +because of the build rule in test/dm/Makefile:: + + ifeq ($(CONFIG_SPL_BUILD),y) + obj-$(CONFIG_SPL_OF_PLATDATA) += of_platdata.o + else + ...other tests for non-spl + endif + +You can get a list of tests in a U-Boot ELF file by looking for the +linker_list:: + + $ nm /tmp/b/sandbox_spl/spl/u-boot-spl |grep 2_dm_test + 000000000001f200 D _u_boot_list_2_dm_test_2_dm_test_of_plat_base + 000000000001f220 D _u_boot_list_2_dm_test_2_dm_test_of_plat_dev + 000000000001f240 D _u_boot_list_2_dm_test_2_dm_test_of_plat_parent + 000000000001f260 D _u_boot_list_2_dm_test_2_dm_test_of_plat_phandle + 000000000001f280 D _u_boot_list_2_dm_test_2_dm_test_of_plat_props + + +Writing tests +------------- + +See :doc:`tests_writing` for how to write new tests. + diff --git a/roms/u-boot/doc/develop/tests_writing.rst b/roms/u-boot/doc/develop/tests_writing.rst new file mode 100644 index 000000000..1ddf7a353 --- /dev/null +++ b/roms/u-boot/doc/develop/tests_writing.rst @@ -0,0 +1,346 @@ +.. SPDX-License-Identifier: GPL-2.0+ +.. Copyright 2021 Google LLC +.. sectionauthor:: Simon Glass <sjg@chromium.org> + +Writing Tests +============= + +This describes how to write tests in U-Boot and describes the possible options. + +Test types +---------- + +There are two basic types of test in U-Boot: + + - Python tests, in test/py/tests + - C tests, in test/ and its subdirectories + +(there are also UEFI tests in lib/efi_selftest/ not considered here.) + +Python tests talk to U-Boot via the command line. They support both sandbox and +real hardware. They typically do not require building test code into U-Boot +itself. They are fairly slow to run, due to the command-line interface and there +being two separate processes. Python tests are fairly easy to write. They can +be a little tricky to debug sometimes due to the voluminous output of pytest. + +C tests are written directly in U-Boot. While they can be used on boards, they +are more commonly used with sandbox, as they obviously add to U-Boot code size. +C tests are easy to write so long as the required facilities exist. Where they +do not it can involve refactoring or adding new features to sandbox. They are +fast to run and easy to debug. + +Regardless of which test type is used, all tests are collected and run by the +pytest framework, so there is typically no need to run them separately. This +means that C tests can be used when it makes sense, and Python tests when it +doesn't. + + +This table shows how to decide whether to write a C or Python test: + +===================== =========================== ============================= +Attribute C test Python test +===================== =========================== ============================= +Fast to run? Yes No (two separate processes) +Easy to write? Yes, if required test Yes + features exist in sandbox + or the target system +Needs code in U-Boot? Yes No, provided the test can be + executed and the result + determined using the command + line +Easy to debug? Yes No, since access to the U-Boot + state is not available and the + amount of output can + sometimes require a bit of + digging +Can use gdb? Yes, directly Yes, with --gdbserver +Can run on boards? Some can, but only if Some + compiled in and not + dependent on sandboxau +===================== =========================== ============================= + + +Python or C +----------- + +Typically in U-Boot we encourage C test using sandbox for all features. This +allows fast testing, easy development and allows contributors to make changes +without needing dozens of boards to test with. + +When a test requires setup or interaction with the running host (such as to +generate images and then running U-Boot to check that they can be loaded), or +cannot be run on sandbox, Python tests should be used. These should typically +NOT rely on running with sandbox, but instead should function correctly on any +board supported by U-Boot. + + +How slow are Python tests? +-------------------------- + +Under the hood, when running on sandbox, Python tests work by starting a sandbox +test and connecting to it via a pipe. Each interaction with the U-Boot process +requires at least a context switch to handle the pipe interaction. The test +sends a command to U-Boot, which then reacts and shows some output, then the +test sees that and continues. Of course on real hardware, communications delays +(e.g. with a serial console) make this slower. + +For comparison, consider a test that checks the 'md' (memory dump). All times +below are approximate, as measured on an AMD 2950X system. Here is is the test +in Python:: + + @pytest.mark.buildconfigspec('cmd_memory') + def test_md(u_boot_console): + """Test that md reads memory as expected, and that memory can be modified + using the mw command.""" + + ram_base = u_boot_utils.find_ram_base(u_boot_console) + addr = '%08x' % ram_base + val = 'a5f09876' + expected_response = addr + ': ' + val + u_boot_console.run_command('mw ' + addr + ' 0 10') + response = u_boot_console.run_command('md ' + addr + ' 10') + assert(not (expected_response in response)) + u_boot_console.run_command('mw ' + addr + ' ' + val) + response = u_boot_console.run_command('md ' + addr + ' 10') + assert(expected_response in response) + +This runs a few commands and checks the output. Note that it runs a command, +waits for the response and then checks it agains what is expected. If run by +itself it takes around 800ms, including test collection. For 1000 runs it takes +19 seconds, or 19ms per run. Of course 1000 runs it not that useful since we +only want to run it once. + +There is no exactly equivalent C test, but here is a similar one that tests 'ms' +(memory search):: + + /* Test 'ms' command with bytes */ + static int mem_test_ms_b(struct unit_test_state *uts) + { + u8 *buf; + + buf = map_sysmem(0, BUF_SIZE + 1); + memset(buf, '\0', BUF_SIZE); + buf[0x0] = 0x12; + buf[0x31] = 0x12; + buf[0xff] = 0x12; + buf[0x100] = 0x12; + ut_assertok(console_record_reset_enable()); + run_command("ms.b 1 ff 12", 0); + ut_assert_nextline("00000030: 00 12 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ................"); + ut_assert_nextline("--"); + ut_assert_nextline("000000f0: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 12 ................"); + ut_assert_nextline("2 matches"); + ut_assert_console_end(); + + ut_asserteq(2, env_get_hex("memmatches", 0)); + ut_asserteq(0xff, env_get_hex("memaddr", 0)); + ut_asserteq(0xfe, env_get_hex("mempos", 0)); + + unmap_sysmem(buf); + + return 0; + } + MEM_TEST(mem_test_ms_b, UT_TESTF_CONSOLE_REC); + +This runs the command directly in U-Boot, then checks the console output, also +directly in U-Boot. If run by itself this takes 100ms. For 1000 runs it takes +660ms, or 0.66ms per run. + +So overall running a C test is perhaps 8 times faster individually and the +interactions are perhaps 25 times faster. + +It should also be noted that the C test is fairly easy to debug. You can set a +breakpoint on do_mem_search(), which is what implements the 'ms' command, +single step to see what might be wrong, etc. That is also possible with the +pytest, but requires two terminals and --gdbserver. + + +Why does speed matter? +---------------------- + +Many development activities rely on running tests: + + - 'git bisect run make qcheck' can be used to find a failing commit + - test-driven development relies on quick iteration of build/test + - U-Boot's continuous integration (CI) systems make use of tests. Running + all sandbox tests typically takes 90 seconds and running each qemu test + takes about 30 seconds. This is currently dwarfed by the time taken to + build all boards + +As U-Boot continues to grow its feature set, fast and reliable tests are a +critical factor factor in developer productivity and happiness. + + +Writing C tests +--------------- + +C tests are arranged into suites which are typically executed by the 'ut' +command. Each suite is in its own file. This section describes how to accomplish +some common test tasks. + +(there are also UEFI C tests in lib/efi_selftest/ not considered here.) + +Add a new driver model test +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Use this when adding a test for a new or existing uclass, adding new operations +or features to a uclass, adding new ofnode or dev_read_() functions, or anything +else related to driver model. + +Find a suitable place for your test, perhaps near other test functions in +existing code, or in a new file. Each uclass should have its own test file. + +Declare the test with:: + + /* Test that ... */ + static int dm_test_uclassname_what(struct unit_test_state *uts) + { + /* test code here */ + + return 0; + } + DM_TEST(dm_test_uclassname_what, UT_TESTF_SCAN_FDT); + +Replace 'uclassname' with the name of your uclass, if applicable. Replace 'what' +with what you are testing. + +The flags for DM_TEST() are defined in test/test.h and you typically want +UT_TESTF_SCAN_FDT so that the devicetree is scanned and all devices are bound +and ready for use. The DM_TEST macro adds UT_TESTF_DM automatically so that +the test runner knows it is a driver model test. + +Driver model tests are special in that the entire driver model state is +recreated anew for each test. This ensures that if a previous test deletes a +device, for example, it does not affect subsequent tests. Driver model tests +also run both with livetree and flattree, to ensure that both devicetree +implementations work as expected. + +Example commit: c48cb7ebfb4 ("sandbox: add ADC unit tests") [1] + +[1] https://gitlab.denx.de/u-boot/u-boot/-/commit/c48cb7ebfb4 + + +Add a C test to an existing suite +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Use this when you are adding to or modifying an existing feature outside driver +model. An example is bloblist. + +Add a new function in the same file as the rest of the suite and register it +with the suite. For example, to add a new mem_search test:: + + /* Test 'ms' command with 32-bit values */ + static int mem_test_ms_new_thing(struct unit_test_state *uts) + { + /* test code here*/ + + return 0; + } + MEM_TEST(mem_test_ms_new_thing, UT_TESTF_CONSOLE_REC); + +Note that the MEM_TEST() macros is defined at the top of the file. + +Example commit: 9fe064646d2 ("bloblist: Support relocating to a larger space") [1] + +[1] https://gitlab.denx.de/u-boot/u-boot/-/commit/9fe064646d2 + + +Add a new test suite +~~~~~~~~~~~~~~~~~~~~ + +Each suite should focus on one feature or subsystem, so if you are writing a +new one of those, you should add a new suite. + +Create a new file in test/ or a subdirectory and define a macro to register the +suite. For example:: + + #include <common.h> + #include <console.h> + #include <mapmem.h> + #include <dm/test.h> + #include <test/ut.h> + + /* Declare a new wibble test */ + #define WIBBLE_TEST(_name, _flags) UNIT_TEST(_name, _flags, wibble_test) + + /* Tetss go here */ + + /* At the bottom of the file: */ + + int do_ut_wibble(struct cmd_tbl *cmdtp, int flag, int argc, char *const argv[]) + { + struct unit_test *tests = UNIT_TEST_SUITE_START(wibble_test); + const int n_ents = UNIT_TEST_SUITE_COUNT(wibble_test); + + return cmd_ut_category("cmd_wibble", "wibble_test_", tests, n_ents, argc, argv); + } + +Then add new tests to it as above. + +Register this new suite in test/cmd_ut.c by adding to cmd_ut_sub[]:: + + /* Within cmd_ut_sub[]... */ + + U_BOOT_CMD_MKENT(wibble, CONFIG_SYS_MAXARGS, 1, do_ut_wibble, "", ""), + +and adding new help to ut_help_text[]:: + + "ut wibble - Test the wibble feature\n" + +If your feature is conditional on a particular Kconfig, then you can use #ifdef +to control that. + +Finally, add the test to the build by adding to the Makefile in the same +directory:: + + obj-$(CONFIG_$(SPL_)CMDLINE) += wibble.o + +Note that CMDLINE is never enabled in SPL, so this test will only be present in +U-Boot proper. See below for how to do SPL tests. + +As before, you can add an extra Kconfig check if needed:: + + ifneq ($(CONFIG_$(SPL_)WIBBLE),) + obj-$(CONFIG_$(SPL_)CMDLINE) += wibble.o + endif + + +Example commit: 919e7a8fb64 ("test: Add a simple test for bloblist") [1] + +[1] https://gitlab.denx.de/u-boot/u-boot/-/commit/919e7a8fb64 + + +Making the test run from pytest +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +All C tests must run from pytest. Typically this is automatic, since pytest +scans the U-Boot executable for available tests to run. So long as you have a +'ut' subcommand for your test suite, it will run. The same applies for driver +model tests since they use the 'ut dm' subcommand. + +See test/py/tests/test_ut.py for how unit tests are run. + + +Add a C test for SPL +~~~~~~~~~~~~~~~~~~~~ + +Note: C tests are only available for sandbox_spl at present. There is currently +no mechanism in other boards to existing SPL tests even if they are built into +the image. + +SPL tests cannot be run from the 'ut' command since there are no commands +available in SPL. Instead, sandbox (only) calls ut_run_list() on start-up, when +the -u flag is given. This runs the available unit tests, no matter what suite +they are in. + +To create a new SPL test, follow the same rules as above, either adding to an +existing suite or creating a new one. + +An example SPL test is spl_test_load(). + + +Writing Python tests +-------------------- + +See :doc:`py_testing` for brief notes how to write Python tests. You +should be able to use the existing tests in test/py/tests as examples. diff --git a/roms/u-boot/doc/develop/trace.rst b/roms/u-boot/doc/develop/trace.rst new file mode 100644 index 000000000..7776c4842 --- /dev/null +++ b/roms/u-boot/doc/develop/trace.rst @@ -0,0 +1,355 @@ +.. SPDX-License-Identifier: GPL-2.0+ +.. Copyright (c) 2013 The Chromium OS Authors. + +Tracing in U-Boot +================= + +U-Boot supports a simple tracing feature which allows a record of excecution +to be collected and sent to a host machine for analysis. At present the +main use for this is to profile boot time. + + +Overview +-------- + +The trace feature uses GCC's instrument-functions feature to trace all +function entry/exit points. These are then recorded in a memory buffer. +The memory buffer can be saved to the host over a network link using +tftpput or by writing to an attached memory device such as MMC. + +On the host, the file is first converted with a tool called 'proftool', +which extracts useful information from it. The resulting trace output +resembles that emitted by Linux's ftrace feature, so can be visually +displayed by pytimechart. + + +Quick-start using Sandbox +------------------------- + +Sandbox is a build of U-Boot that can run under Linux so it is a convenient +way of trying out tracing before you use it on your actual board. To do +this, follow these steps: + +Add the following to include/configs/sandbox.h (if not already there) + +.. code-block:: c + + #define CONFIG_TRACE + #define CONFIG_CMD_TRACE + #define CONFIG_TRACE_BUFFER_SIZE (16 << 20) + #define CONFIG_TRACE_EARLY_SIZE (8 << 20) + #define CONFIG_TRACE_EARLY + #define CONFIG_TRACE_EARLY_ADDR 0x00100000 + +Build sandbox U-Boot with tracing enabled: + +.. code-block:: console + + $ make FTRACE=1 O=sandbox sandbox_config + $ make FTRACE=1 O=sandbox + +Run sandbox, wait for a bit of trace information to appear, and then capture +a trace: + +.. code-block:: console + + $ ./sandbox/u-boot + + U-Boot 2013.04-rc2-00100-ga72fcef (Apr 17 2013 - 19:25:24) + + DRAM: 128 MiB + trace: enabled + Using default environment + + In: serial + Out: serial + Err: serial + =>trace stats + 671,406 function sites + 69,712 function calls + 0 untracked function calls + 73,373 traced function calls + 16 maximum observed call depth + 15 call depth limit + 66,491 calls not traced due to depth + =>trace stats + 671,406 function sites + 1,279,450 function calls + 0 untracked function calls + 950,490 traced function calls (333217 dropped due to overflow) + 16 maximum observed call depth + 15 call depth limit + 1,275,767 calls not traced due to depth + =>trace calls 0 e00000 + Call list dumped to 00000000, size 0xae0a40 + =>print + baudrate=115200 + profbase=0 + profoffset=ae0a40 + profsize=e00000 + stderr=serial + stdin=serial + stdout=serial + + Environment size: 117/8188 bytes + =>host save host 0 trace 0 ${profoffset} + 11405888 bytes written in 10 ms (1.1 GiB/s) + =>reset + + +Then run proftool to convert the trace information to ftrace format + +.. code-block:: console + + $ ./sandbox/tools/proftool -m sandbox/System.map -p trace dump-ftrace >trace.txt + +Finally run pytimechart to display it + +.. code-block:: console + + $ pytimechart trace.txt + +Using this tool you can zoom and pan across the trace, with the function +calls on the left and little marks representing the start and end of each +function. + + +CONFIG Options +-------------- + +CONFIG_TRACE + Enables the trace feature in U-Boot. + +CONFIG_CMD_TRACE + Enables the trace command. + +CONFIG_TRACE_BUFFER_SIZE + Size of trace buffer to allocate for U-Boot. This buffer is + used after relocation, as a place to put function tracing + information. The address of the buffer is determined by + the relocation code. + +CONFIG_TRACE_EARLY + Define this to start tracing early, before relocation. + +CONFIG_TRACE_EARLY_SIZE + Size of 'early' trace buffer. Before U-Boot has relocated + it doesn't have a proper trace buffer. On many boards + you can define an area of memory to use for the trace + buffer until the 'real' trace buffer is available after + relocation. The contents of this buffer are then copied to + the real buffer. + +CONFIG_TRACE_EARLY_ADDR + Address of early trace buffer + + +Building U-Boot with Tracing Enabled +------------------------------------ + +Pass 'FTRACE=1' to the U-Boot Makefile to actually instrument the code. +This is kept as a separate option so that it is easy to enable/disable +instrumenting from the command line instead of having to change board +config files. + + +Collecting Trace Data +--------------------- + +When you run U-Boot on your board it will collect trace data up to the +limit of the trace buffer size you have specified. Once that is exhausted +no more data will be collected. + +Collecting trace data has an affect on execution time/performance. You +will notice this particularly with trvial functions - the overhead of +recording their execution may even exceed their normal execution time. +In practice this doesn't matter much so long as you are aware of the +effect. Once you have done your optimisations, turn off tracing before +doing end-to-end timing. + +The best time to start tracing is right at the beginning of U-Boot. The +best time to stop tracing is right at the end. In practice it is hard +to achieve these ideals. + +This implementation enables tracing early in board_init_f(). This means +that it captures most of the board init process, missing only the +early architecture-specific init. However, it also misses the entire +SPL stage if there is one. + +U-Boot typically ends with a 'bootm' command which loads and runs an +OS. There is useful trace data in the execution of that bootm +command. Therefore this implementation provides a way to collect trace +data after bootm has finished processing, but just before it jumps to +the OS. In practical terms, U-Boot runs the 'fakegocmd' environment +variable at this point. This variable should have a short script which +collects the trace data and writes it somewhere. + +Trace data collection relies on a microsecond timer, accesed through +timer_get_us(). So the first think you should do is make sure that +this produces sensible results for your board. Suitable sources for +this timer include high resolution timers, PWMs or profile timers if +available. Most modern SOCs have a suitable timer for this. Make sure +that you mark this timer (and anything it calls) with +__attribute__((no_instrument_function)) so that the trace library can +use it without causing an infinite loop. + + +Commands +-------- + +The trace command has variable sub-commands: + +stats + Display tracing statistics + +pause + Pause tracing + +resume + Resume tracing + +funclist [<addr> <size>] + Dump a list of functions into the buffer + +calls [<addr> <size>] + Dump function call trace into buffer + +If the address and size are not given, these are obtained from environment +variables (see below). In any case the environment variables are updated +after the command runs. + + +Environment Variables +--------------------- + +The following are used: + +profbase + Base address of trace output buffer + +profoffset + Offset of first unwritten byte in trace output buffer + +profsize + Size of trace output buffer + +All of these are set by the 'trace calls' command. + +These variables keep track of the amount of data written to the trace +output buffer by the 'trace' command. The trace commands which write data +to the output buffer can use these to specify the buffer to write to, and +update profoffset each time. This allows successive commands to append data +to the same buffer, for example:: + + => trace funclist 10000 e00000 + => trace calls + +(the latter command appends more data to the buffer). + + +fakegocmd + Specifies commands to run just before booting the OS. This + is a useful time to write the trace data to the host for + processing. + + +Writing Out Trace Data +---------------------- + +Once the trace data is in an output buffer in memory there are various ways +to transmit it to the host. Notably you can use tftput to send the data +over a network link:: + + fakegocmd=trace pause; usb start; set autoload n; bootp; + trace calls 10000000 1000000; + tftpput ${profbase} ${profoffset} 192.168.1.4:/tftpboot/calls + +This starts up USB (to talk to an attached USB Ethernet dongle), writes +a trace log to address 10000000 and sends it to a host machine using +TFTP. After this, U-Boot will boot the OS normally, albeit a little +later. + + +Converting Trace Output Data +---------------------------- + +The trace output data is kept in a binary format which is not documented +here. To convert it into something useful, you can use proftool. + +This tool must be given the U-Boot map file and the trace data received +from running that U-Boot. It produces a text output file. + +Options + +-m <map_file> + Specify U-Boot map file + +-p <trace_file> + Specifiy profile/trace file + +Commands: + +dump-ftrace + Write a text dump of the file in Linux ftrace format to stdout + + +Viewing the Trace Data +---------------------- + +You can use pytimechart for this (sudo apt-get pytimechart might work on +your Debian-style machine, and use your favourite search engine to obtain +documentation). It expects the file to have a .txt extension. The program +has terse user interface but is very convenient for viewing U-Boot +profile information. + + +Workflow Suggestions +-------------------- + +The following suggestions may be helpful if you are trying to reduce boot +time: + +1. Enable CONFIG_BOOTSTAGE and CONFIG_BOOTSTAGE_REPORT. This should get + you are helpful overall snapshot of the boot time. + +2. Build U-Boot with tracing and run it. Note the difference in boot time + (it is common for tracing to add 10% to the time) + +3. Collect the trace information as descibed above. Use this to find where + all the time is being spent. + +4. Take a look at that code and see if you can optimise it. Perhaps it is + possible to speed up the initialisation of a device, or remove an unused + feature. + +5. Rebuild, run and collect again. Compare your results. + +6. Keep going until you run out of steam, or your boot is fast enough. + + +Configuring Trace +----------------- + +There are a few parameters in the code that you may want to consider. +There is a function call depth limit (set to 15 by default). When the +stack depth goes above this then no tracing information is recorded. +The maximum depth reached is recorded and displayed by the 'trace stats' +command. + + +Future Work +----------- + +Tracing could be a little tidier in some areas, for example providing +run-time configuration options for trace. + +Some other features that might be useful: + +- Trace filter to select which functions are recorded +- Sample-based profiling using a timer interrupt +- Better control over trace depth +- Compression of trace information + + +Simon Glass <sjg@chromium.org> +April 2013 diff --git a/roms/u-boot/doc/develop/uefi/index.rst b/roms/u-boot/doc/develop/uefi/index.rst new file mode 100644 index 000000000..7e65dbc5d --- /dev/null +++ b/roms/u-boot/doc/develop/uefi/index.rst @@ -0,0 +1,15 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +Unified Extensible Firmware (UEFI) +================================== + +U-Boot provides an implementation of the UEFI API allowing to run UEFI +compliant software like Linux, GRUB, and iPXE. Furthermore U-Boot itself +can be run an UEFI payload. + +.. toctree:: + :maxdepth: 2 + + uefi.rst + u-boot_on_efi.rst + iscsi.rst diff --git a/roms/u-boot/doc/develop/uefi/iscsi.rst b/roms/u-boot/doc/develop/uefi/iscsi.rst new file mode 100644 index 000000000..51d38cde2 --- /dev/null +++ b/roms/u-boot/doc/develop/uefi/iscsi.rst @@ -0,0 +1,184 @@ +.. SPDX-License-Identifier: GPL-2.0+ +.. Copyright (c) 2018 Heinrich Schuchardt + +iSCSI booting with U-Boot and iPXE +================================== + +Motivation +---------- + +U-Boot has only a reduced set of supported network protocols. The focus for +network booting has been on UDP based protocols. A TCP stack and HTTP support +are expected to be integrated in 2018 together with a wget command. + +For booting a diskless computer this leaves us with BOOTP or DHCP to get the +address of a boot script. TFTP or NFS can be used to load the boot script, the +operating system kernel and the initial file system (initrd). + +These protocols are insecure. The client cannot validate the authenticity +of the contacted servers. And the server cannot verify the identity of the +client. + +Furthermore the services providing the operating system loader or kernel are +not the ones that the operating system typically will use. Especially in a SAN +environment this makes updating the operating system a hassle. After installing +a new kernel version the boot files have to be copied to the TFTP server +directory. + +The HTTPS protocol provides certificate based validation of servers. Sensitive +data like passwords can be securely transmitted. + +The iSCSI protocol is used for connecting storage attached networks. It +provides mutual authentication using the CHAP protocol. It typically runs on +a TCP transport. + +Thus a better solution than DHCP/TFTP/NFS boot would be to load a boot script +via HTTPS and to download any other files needed for booting via iSCSI from the +same target where the operating system is installed. + +An alternative to implementing these protocols in U-Boot is to use an existing +software that can run on top of U-Boot. iPXE[1] is the "swiss army knife" of +network booting. It supports both HTTPS and iSCSI. It has a scripting engine for +fine grained control of the boot process and can provide a command shell. + +iPXE can be built as an EFI application (named snp.efi) which can be loaded and +run by U-Boot. + +Boot sequence +------------- + +U-Boot loads the EFI application iPXE snp.efi using the bootefi command. This +application has network access via the simple network protocol offered by +U-Boot. + +iPXE executes its internal script. This script may optionally chain load a +secondary boot script via HTTPS or open a shell. + +For the further boot process iPXE connects to the iSCSI server. This includes +the mutual authentication using the CHAP protocol. After the authentication iPXE +has access to the iSCSI targets. + +For a selected iSCSI target iPXE sets up a handle with the block IO protocol. It +uses the ConnectController boot service of U-Boot to request U-Boot to connect a +file system driver. U-Boot reads from the iSCSI drive via the block IO protocol +offered by iPXE. It creates the partition handles and installs the simple file +protocol. Now iPXE can call the simple file protocol to load GRUB[2]. U-Boot +uses the block IO protocol offered by iPXE to fulfill the request. + +Once GRUB is started it uses the same block IO protocol to load Linux. Via +the EFI stub Linux is called as an EFI application:: + + +--------+ +--------+ + | | Runs | | + | U-Boot |========>| iPXE | + | EFI | | snp.efi| + +--------+ | | DHCP | | + | |<===|********|<========| | + | DHCP | | | Get IP | | + | Server | | | Address | | + | |===>|********|========>| | + +--------+ | | Response| | + | | | | + | | | | + +--------+ | | HTTPS | | + | |<===|********|<========| | + | HTTPS | | | Load | | + | Server | | | Script | | + | |===>|********|========>| | + +--------+ | | | | + | | | | + | | | | + +--------+ | | iSCSI | | + | |<===|********|<========| | + | iSCSI | | | Auth | | + | Server |===>|********|========>| | + | | | | | | + | | | | Loads | | + | |<===|********|<========| | +--------+ + | | | | GRUB | | Runs | | + | |===>|********|========>| |======>| GRUB | + | | | | | | | | + | | | | | | | | + | | | | | | Loads | | + | |<===|********|<========|********|<======| | +--------+ + | | | | | | Linux | | Runs | | + | |===>|********|========>|********|======>| |=====>| Linux | + | | | | | | | | | | + +--------+ +--------+ +--------+ +--------+ | | + | | + | | + | ~ ~ ~ ~| + +Security +-------- + +The iSCSI protocol is not encrypted. The traffic could be secured using IPsec +but neither U-Boot nor iPXE does support this. So we should at least separate +the iSCSI traffic from all other network traffic. This can be achieved using a +virtual local area network (VLAN). + +Configuration +------------- + +iPXE +~~~~ + +For running iPXE on arm64 the bin-arm64-efi/snp.efi build target is needed:: + + git clone http://git.ipxe.org/ipxe.git + cd ipxe/src + make bin-arm64-efi/snp.efi -j6 EMBED=myscript.ipxe + +The available commands for the boot script are documented at: + +http://ipxe.org/cmd + +Credentials are managed as environment variables. These are described here: + +http://ipxe.org/cfg + +iPXE by default will put the CPU to rest when waiting for input. U-Boot does +not wake it up due to missing interrupt support. To avoid this behavior create +file src/config/local/nap.h: + +.. code-block:: c + + /* nap.h */ + #undef NAP_EFIX86 + #undef NAP_EFIARM + #define NAP_NULL + +The supported commands in iPXE are controlled by an include, too. Putting the +following into src/config/local/general.h is sufficient for most use cases: + +.. code-block:: c + + /* general.h */ + #define NSLOOKUP_CMD /* Name resolution command */ + #define PING_CMD /* Ping command */ + #define NTP_CMD /* NTP commands */ + #define VLAN_CMD /* VLAN commands */ + #define IMAGE_EFI /* EFI image support */ + #define DOWNLOAD_PROTO_HTTPS /* Secure Hypertext Transfer Protocol */ + #define DOWNLOAD_PROTO_FTP /* File Transfer Protocol */ + #define DOWNLOAD_PROTO_NFS /* Network File System Protocol */ + #define DOWNLOAD_PROTO_FILE /* Local file system access */ + +Open-iSCSI +~~~~~~~~~~ + +When the root file system is on an iSCSI drive you should disable pings and set +the replacement timer to a high value in the configuration file [3]:: + + node.conn[0].timeo.noop_out_interval = 0 + node.conn[0].timeo.noop_out_timeout = 0 + node.session.timeo.replacement_timeout = 86400 + +Links +----- + +* [1] https://ipxe.org - iPXE open source boot firmware +* [2] https://www.gnu.org/software/grub/ - + GNU GRUB (Grand Unified Bootloader) +* [3] https://github.com/open-iscsi/open-iscsi/blob/master/README - + Open-iSCSI README diff --git a/roms/u-boot/doc/develop/uefi/u-boot_on_efi.rst b/roms/u-boot/doc/develop/uefi/u-boot_on_efi.rst new file mode 100644 index 000000000..c9a41bc91 --- /dev/null +++ b/roms/u-boot/doc/develop/uefi/u-boot_on_efi.rst @@ -0,0 +1,235 @@ +.. SPDX-License-Identifier: GPL-2.0+ +.. Copyright (C) 2015 Google, Inc + +U-Boot on EFI +============= +This document provides information about U-Boot running on top of EFI, either +as an application or just as a means of getting U-Boot onto a new platform. + + +Motivation +---------- +Running U-Boot on EFI is useful in several situations: + +- You have EFI running on a board but U-Boot does not natively support it + fully yet. You can boot into U-Boot from EFI and use that until U-Boot is + fully ported + +- You need to use an EFI implementation (e.g. UEFI) because your vendor + requires it in order to provide support + +- You plan to use coreboot to boot into U-Boot but coreboot support does + not currently exist for your platform. In the meantime you can use U-Boot + on EFI and then move to U-Boot on coreboot when ready + +- You use EFI but want to experiment with a simpler alternative like U-Boot + + +Status +------ +Only x86 is supported at present. If you are using EFI on another architecture +you may want to reconsider. However, much of the code is generic so could be +ported. + +U-Boot supports running as an EFI application for 32-bit EFI only. This is +not very useful since only a serial port is provided. You can look around at +memory and type 'help' but that is about it. + +More usefully, U-Boot supports building itself as a payload for either 32-bit +or 64-bit EFI. U-Boot is packaged up and loaded in its entirety by EFI. Once +started, U-Boot changes to 32-bit mode (currently) and takes over the +machine. You can use devices, boot a kernel, etc. + + +Build Instructions +------------------ +First choose a board that has EFI support and obtain an EFI implementation +for that board. It will be either 32-bit or 64-bit. Alternatively, you can +opt for using QEMU [1] and the OVMF [2], as detailed below. + +To build U-Boot as an EFI application (32-bit EFI required), enable CONFIG_EFI +and CONFIG_EFI_APP. The efi-x86_app config (efi-x86_app_defconfig) is set up +for this. Just build U-Boot as normal, e.g.:: + + make efi-x86_app_defconfig + make + +To build U-Boot as an EFI payload (32-bit or 64-bit EFI can be used), enable +CONFIG_EFI, CONFIG_EFI_STUB, and select either CONFIG_EFI_STUB_32BIT or +CONFIG_EFI_STUB_64BIT. The efi-x86_payload configs (efi-x86_payload32_defconfig +and efi-x86_payload32_defconfig) are set up for this. Then build U-Boot as +normal, e.g.:: + + make efi-x86_payload32_defconfig (or efi-x86_payload64_defconfig) + make + +You will end up with one of these files depending on what you build for: + +* u-boot-app.efi - U-Boot EFI application +* u-boot-payload.efi - U-Boot EFI payload application + + +Trying it out +------------- +QEMU is an emulator and it can emulate an x86 machine. Please make sure your +QEMU version is 2.3.0 or above to test this. You can run the payload with +something like this:: + + mkdir /tmp/efi + cp /path/to/u-boot*.efi /tmp/efi + qemu-system-x86_64 -bios bios.bin -hda fat:/tmp/efi/ + +Add -nographic if you want to use the terminal for output. Once it starts +type 'fs0:u-boot-payload.efi' to run the payload or 'fs0:u-boot-app.efi' to +run the application. 'bios.bin' is the EFI 'BIOS'. Check [2] to obtain a +prebuilt EFI BIOS for QEMU or you can build one from source as well. + +To try it on real hardware, put u-boot-app.efi on a suitable boot medium, +such as a USB stick. Then you can type something like this to start it:: + + fs0:u-boot-payload.efi + +(or fs0:u-boot-app.efi for the application) + +This will start the payload, copy U-Boot into RAM and start U-Boot. Note +that EFI does not support booting a 64-bit application from a 32-bit +EFI (or vice versa). Also it will often fail to print an error message if +you get this wrong. + + +Inner workings +-------------- +Here follow a few implementation notes for those who want to fiddle with +this and perhaps contribute patches. + +The application and payload approaches sound similar but are in fact +implemented completely differently. + +EFI Application +~~~~~~~~~~~~~~~ +For the application the whole of U-Boot is built as a shared library. The +efi_main() function is in lib/efi/efi_app.c. It sets up some basic EFI +functions with efi_init(), sets up U-Boot global_data, allocates memory for +U-Boot's malloc(), etc. and enters the normal init sequence (board_init_f() +and board_init_r()). + +Since U-Boot limits its memory access to the allocated regions very little +special code is needed. The CONFIG_EFI_APP option controls a few things +that need to change so 'git grep CONFIG_EFI_APP' may be instructive. +The CONFIG_EFI option controls more general EFI adjustments. + +The only available driver is the serial driver. This calls back into EFI +'boot services' to send and receive characters. Although it is implemented +as a serial driver the console device is not necessarilly serial. If you +boot EFI with video output then the 'serial' device will operate on your +target devices's display instead and the device's USB keyboard will also +work if connected. If you have both serial and video output, then both +consoles will be active. Even though U-Boot does the same thing normally, +These are features of EFI, not U-Boot. + +Very little code is involved in implementing the EFI application feature. +U-Boot is highly portable. Most of the difficulty is in modifying the +Makefile settings to pass the right build flags. In particular there is very +little x86-specific code involved - you can find most of it in +arch/x86/cpu. Porting to ARM (which can also use EFI if you are brave +enough) should be straightforward. + +Use the 'reset' command to get back to EFI. + +EFI Payload +~~~~~~~~~~~ +The payload approach is a different kettle of fish. It works by building +U-Boot exactly as normal for your target board, then adding the entire +image (including device tree) into a small EFI stub application responsible +for booting it. The stub application is built as a normal EFI application +except that it has a lot of data attached to it. + +The stub application is implemented in lib/efi/efi_stub.c. The efi_main() +function is called by EFI. It is responsible for copying U-Boot from its +original location into memory, disabling EFI boot services and starting +U-Boot. U-Boot then starts as normal, relocates, starts all drivers, etc. + +The stub application is architecture-dependent. At present it has some +x86-specific code and a comment at the top of efi_stub.c describes this. + +While the stub application does allocate some memory from EFI this is not +used by U-Boot (the payload). In fact when U-Boot starts it has all of the +memory available to it and can operate as it pleases (but see the next +section). + +Tables +~~~~~~ +The payload can pass information to U-Boot in the form of EFI tables. At +present this feature is used to pass the EFI memory map, an inordinately +large list of memory regions. You can use the 'efi mem all' command to +display this list. U-Boot uses the list to work out where to relocate +itself. + +Although U-Boot can use any memory it likes, EFI marks some memory as used +by 'run-time services', code that hangs around while U-Boot is running and +is even present when Linux is running. This is common on x86 and provides +a way for Linux to call back into the firmware to control things like CPU +fan speed. U-Boot uses only 'conventional' memory, in EFI terminology. It +will relocate itself to the top of the largest block of memory it can find +below 4GB. + +Interrupts +~~~~~~~~~~ +U-Boot drivers typically don't use interrupts. Since EFI enables interrupts +it is possible that an interrupt will fire that U-Boot cannot handle. This +seems to cause problems. For this reason the U-Boot payload runs with +interrupts disabled at present. + +32/64-bit +~~~~~~~~~ +While the EFI application can in principle be built as either 32- or 64-bit, +only 32-bit is currently supported. This means that the application can only +be used with 32-bit EFI. + +The payload stub can be build as either 32- or 64-bits. Only a small amount +of code is built this way (see the extra- line in lib/efi/Makefile). +Everything else is built as a normal U-Boot, so is always 32-bit on x86 at +present. + +Future work +----------- +This work could be extended in a number of ways: + +- Add ARM support + +- Add 64-bit application support + +- Figure out how to solve the interrupt problem + +- Add more drivers to the application side (e.g. video, block devices, USB, + environment access). This would mostly be an academic exercise as a strong + use case is not readily apparent, but it might be fun. + +- Avoid turning off boot services in the stub. Instead allow U-Boot to make + use of boot services in case it wants to. It is unclear what it might want + though. + +Where is the code? +------------------ +lib/efi + payload stub, application, support code. Mostly arch-neutral + +arch/x86/cpu/efi + x86 support code for running as an EFI application and payload + +board/efi/efi-x86_app/efi.c + x86 board code for running as an EFI application + +board/efi/efi-x86_payload + generic x86 EFI payload board support code + +common/cmd_efi.c + the 'efi' command + +-- +Ben Stoltz, Simon Glass +Google, Inc +July 2015 + +* [1] http://www.qemu.org +* [2] http://www.tianocore.org/ovmf/ diff --git a/roms/u-boot/doc/develop/uefi/uefi.rst b/roms/u-boot/doc/develop/uefi/uefi.rst new file mode 100644 index 000000000..4f2b8b036 --- /dev/null +++ b/roms/u-boot/doc/develop/uefi/uefi.rst @@ -0,0 +1,574 @@ +.. SPDX-License-Identifier: GPL-2.0+ +.. Copyright (c) 2018 Heinrich Schuchardt + +UEFI on U-Boot +============== + +The Unified Extensible Firmware Interface Specification (UEFI) [1] has become +the default for booting on AArch64 and x86 systems. It provides a stable API for +the interaction of drivers and applications with the firmware. The API comprises +access to block storage, network, and console to name a few. The Linux kernel +and boot loaders like GRUB or the FreeBSD loader can be executed. + +Development target +------------------ + +The implementation of UEFI in U-Boot strives to reach the requirements described +in the "Embedded Base Boot Requirements (EBBR) Specification - Release v1.0" +[2]. The "Server Base Boot Requirements System Software on ARM Platforms" [3] +describes a superset of the EBBR specification and may be used as further +reference. + +A full blown UEFI implementation would contradict the U-Boot design principle +"keep it small". + +Building U-Boot for UEFI +------------------------ + +The UEFI standard supports only little-endian systems. The UEFI support can be +activated for ARM and x86 by specifying:: + + CONFIG_CMD_BOOTEFI=y + CONFIG_EFI_LOADER=y + +in the .config file. + +Support for attaching virtual block devices, e.g. iSCSI drives connected by the +loaded UEFI application [4], requires:: + + CONFIG_BLK=y + CONFIG_PARTITIONS=y + +Executing a UEFI binary +~~~~~~~~~~~~~~~~~~~~~~~ + +The bootefi command is used to start UEFI applications or to install UEFI +drivers. It takes two parameters:: + + bootefi <image address> [fdt address] + +* image address - the memory address of the UEFI binary +* fdt address - the memory address of the flattened device tree + +Below you find the output of an example session starting GRUB:: + + => load mmc 0:2 ${fdt_addr_r} boot/dtb + 29830 bytes read in 14 ms (2 MiB/s) + => load mmc 0:1 ${kernel_addr_r} efi/debian/grubaa64.efi + reading efi/debian/grubaa64.efi + 120832 bytes read in 7 ms (16.5 MiB/s) + => bootefi ${kernel_addr_r} ${fdt_addr_r} + +When booting from a memory location it is unknown from which file it was loaded. +Therefore the bootefi command uses the device path of the block device partition +or the network adapter and the file name of the most recently loaded PE-COFF +file when setting up the loaded image protocol. + +Launching a UEFI binary from a FIT image +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +A signed FIT image can be used to securely boot a UEFI image via the +bootm command. This feature is available if U-Boot is configured with:: + + CONFIG_BOOTM_EFI=y + +A sample configuration is provided as file doc/uImage.FIT/uefi.its. + +Below you find the output of an example session starting GRUB:: + + => load mmc 0:1 ${kernel_addr_r} image.fit + 4620426 bytes read in 83 ms (53.1 MiB/s) + => bootm ${kernel_addr_r}#config-grub-nofdt + ## Loading kernel from FIT Image at 40400000 ... + Using 'config-grub-nofdt' configuration + Verifying Hash Integrity ... sha256,rsa2048:dev+ OK + Trying 'efi-grub' kernel subimage + Description: GRUB EFI Firmware + Created: 2019-11-20 8:18:16 UTC + Type: Kernel Image (no loading done) + Compression: uncompressed + Data Start: 0x404000d0 + Data Size: 450560 Bytes = 440 KiB + Hash algo: sha256 + Hash value: 4dbee00021112df618f58b3f7cf5e1595533d543094064b9ce991e8b054a9eec + Verifying Hash Integrity ... sha256+ OK + XIP Kernel Image (no loading done) + ## Transferring control to EFI (at address 404000d0) ... + Welcome to GRUB! + +See doc/uImage.FIT/howto.txt for an introduction to FIT images. + +Configuring UEFI secure boot +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The UEFI specification[1] defines a secure way of executing UEFI images +by verifying a signature (or message digest) of image with certificates. +This feature on U-Boot is enabled with:: + + CONFIG_UEFI_SECURE_BOOT=y + +To make the boot sequence safe, you need to establish a chain of trust; +In UEFI secure boot the chain trust is defined by the following UEFI variables + +* PK - Platform Key +* KEK - Key Exchange Keys +* db - white list database +* dbx - black list database + +An in depth description of UEFI secure boot is beyond the scope of this +document. Please, refer to the UEFI specification and available online +documentation. Here is a simple example that you can follow for your initial +attempt (Please note that the actual steps will depend on your system and +environment.): + +Install the required tools on your host + +* openssl +* efitools +* sbsigntool + +Create signing keys and the key database on your host: + +The platform key + +.. code-block:: bash + + openssl req -x509 -sha256 -newkey rsa:2048 -subj /CN=TEST_PK/ \ + -keyout PK.key -out PK.crt -nodes -days 365 + cert-to-efi-sig-list -g 11111111-2222-3333-4444-123456789abc \ + PK.crt PK.esl; + sign-efi-sig-list -c PK.crt -k PK.key PK PK.esl PK.auth + +The key exchange keys + +.. code-block:: bash + + openssl req -x509 -sha256 -newkey rsa:2048 -subj /CN=TEST_KEK/ \ + -keyout KEK.key -out KEK.crt -nodes -days 365 + cert-to-efi-sig-list -g 11111111-2222-3333-4444-123456789abc \ + KEK.crt KEK.esl + sign-efi-sig-list -c PK.crt -k PK.key KEK KEK.esl KEK.auth + +The whitelist database + +.. code-block:: bash + + openssl req -x509 -sha256 -newkey rsa:2048 -subj /CN=TEST_db/ \ + -keyout db.key -out db.crt -nodes -days 365 + cert-to-efi-sig-list -g 11111111-2222-3333-4444-123456789abc \ + db.crt db.esl + sign-efi-sig-list -c KEK.crt -k KEK.key db db.esl db.auth + +Copy the \*.auth files to media, say mmc, that is accessible from U-Boot. + +Sign an image with one of the keys in "db" on your host + +.. code-block:: bash + + sbsign --key db.key --cert db.crt helloworld.efi + +Now in U-Boot install the keys on your board:: + + fatload mmc 0:1 <tmpaddr> PK.auth + setenv -e -nv -bs -rt -at -i <tmpaddr>:$filesize PK + fatload mmc 0:1 <tmpaddr> KEK.auth + setenv -e -nv -bs -rt -at -i <tmpaddr>:$filesize KEK + fatload mmc 0:1 <tmpaddr> db.auth + setenv -e -nv -bs -rt -at -i <tmpaddr>:$filesize db + +Set up boot parameters on your board:: + + efidebug boot add -b 1 HELLO mmc 0:1 /helloworld.efi.signed "" + +Since kernel 5.7 there's an alternative way of loading an initrd using +LoadFile2 protocol if CONFIG_EFI_LOAD_FILE2_INITRD is enabled. +The initrd path can be specified with:: + + efidebug boot add -b ABE0 'kernel' mmc 0:1 Image -i mmc 0:1 initrd + +Now your board can run the signed image via the boot manager (see below). +You can also try this sequence by running Pytest, test_efi_secboot, +on the sandbox + +.. code-block:: bash + + cd <U-Boot source directory> + pytest.py test/py/tests/test_efi_secboot/test_signed.py --bd sandbox + +UEFI binaries may be signed by Microsoft using the following certificates: + +* KEK: Microsoft Corporation KEK CA 2011 + http://go.microsoft.com/fwlink/?LinkId=321185. +* db: Microsoft Windows Production PCA 2011 + http://go.microsoft.com/fwlink/p/?linkid=321192. +* db: Microsoft Corporation UEFI CA 2011 + http://go.microsoft.com/fwlink/p/?linkid=321194. + +Using OP-TEE for EFI variables +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Instead of implementing UEFI variable services inside U-Boot they can +also be provided in the secure world by a module for OP-TEE[1]. The +interface between U-Boot and OP-TEE for variable services is enabled by +CONFIG_EFI_MM_COMM_TEE=y. + +Tianocore EDK II's standalone management mode driver for variables can +be linked to OP-TEE for this purpose. This module uses the Replay +Protected Memory Block (RPMB) of an eMMC device for persisting +non-volatile variables. When calling the variable services via the +OP-TEE API U-Boot's OP-TEE supplicant relays calls to the RPMB driver +which has to be enabled via CONFIG_SUPPORT_EMMC_RPMB=y. + +EDK2 Build instructions +*********************** + +.. code-block:: bash + + $ git clone https://github.com/tianocore/edk2.git + $ git clone https://github.com/tianocore/edk2-platforms.git + $ cd edk2 + $ git submodule init && git submodule update --init --recursive + $ cd .. + $ export WORKSPACE=$(pwd) + $ export PACKAGES_PATH=$WORKSPACE/edk2:$WORKSPACE/edk2-platforms + $ export ACTIVE_PLATFORM="Platform/StandaloneMm/PlatformStandaloneMmPkg/PlatformStandaloneMmRpmb.dsc" + $ export GCC5_AARCH64_PREFIX=aarch64-linux-gnu- + $ source edk2/edksetup.sh + $ make -C edk2/BaseTools + $ build -p $ACTIVE_PLATFORM -b RELEASE -a AARCH64 -t GCC5 -n `nproc` + +OP-TEE Build instructions +************************* + +.. code-block:: bash + + $ git clone https://github.com/OP-TEE/optee_os.git + $ cd optee_os + $ ln -s ../Build/MmStandaloneRpmb/RELEASE_GCC5/FV/BL32_AP_MM.fd + $ export ARCH=arm + $ CROSS_COMPILE32=arm-linux-gnueabihf- make -j32 CFG_ARM64_core=y \ + PLATFORM=<myboard> CFG_STMM_PATH=BL32_AP_MM.fd CFG_RPMB_FS=y \ + CFG_RPMB_FS_DEV_ID=0 CFG_CORE_HEAP_SIZE=524288 CFG_RPMB_WRITE_KEY=1 \ + CFG_CORE_HEAP_SIZE=524288 CFG_CORE_DYN_SHM=y CFG_RPMB_TESTKEY=y \ + CFG_REE_FS=n CFG_CORE_ARM64_PA_BITS=48 CFG_TEE_CORE_LOG_LEVEL=1 \ + CFG_TEE_TA_LOG_LEVEL=1 CFG_SCTLR_ALIGNMENT_CHECK=n + +U-Boot Build instructions +************************* + +Although the StandAloneMM binary comes from EDK2, using and storing the +variables is currently available in U-Boot only. + +.. code-block:: bash + + $ git clone https://github.com/u-boot/u-boot.git + $ cd u-boot + $ export CROSS_COMPILE=aarch64-linux-gnu- + $ export ARCH=<arch> + $ make <myboard>_defconfig + $ make menuconfig + +Enable ``CONFIG_OPTEE``, ``CONFIG_CMD_OPTEE_RPMB`` and ``CONFIG_EFI_MM_COMM_TEE`` + +.. warning:: + + - Your OP-TEE platform port must support Dynamic shared memory, since that's + the only kind of memory U-Boot supports for now. + +[1] https://optee.readthedocs.io/en/latest/building/efi_vars/stmm.html + +Executing the boot manager +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The UEFI specification foresees to define boot entries and boot sequence via +UEFI variables. Booting according to these variables is possible via:: + + bootefi bootmgr [fdt address] + +As of U-Boot v2020.10 UEFI variables cannot be set at runtime. The U-Boot +command 'efidebug' can be used to set the variables. + +Executing the built in hello world application +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +A hello world UEFI application can be built with:: + + CONFIG_CMD_BOOTEFI_HELLO_COMPILE=y + +It can be embedded into the U-Boot binary with:: + + CONFIG_CMD_BOOTEFI_HELLO=y + +The bootefi command is used to start the embedded hello world application:: + + bootefi hello [fdt address] + +Below you find the output of an example session:: + + => bootefi hello ${fdtcontroladdr} + ## Starting EFI application at 01000000 ... + WARNING: using memory device/image path, this may confuse some payloads! + Hello, world! + Running on UEFI 2.7 + Have SMBIOS table + Have device tree + Load options: root=/dev/sdb3 init=/sbin/init rootwait ro + ## Application terminated, r = 0 + +The environment variable fdtcontroladdr points to U-Boot's internal device tree +(if available). + +Executing the built-in self-test +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +An UEFI self-test suite can be embedded in U-Boot by building with:: + + CONFIG_CMD_BOOTEFI_SELFTEST=y + +For testing the UEFI implementation the bootefi command can be used to start the +self-test:: + + bootefi selftest [fdt address] + +The environment variable 'efi_selftest' can be used to select a single test. If +it is not provided all tests are executed except those marked as 'on request'. +If the environment variable is set to 'list' a list of all tests is shown. + +Below you can find the output of an example session:: + + => setenv efi_selftest simple network protocol + => bootefi selftest + Testing EFI API implementation + Selected test: 'simple network protocol' + Setting up 'simple network protocol' + Setting up 'simple network protocol' succeeded + Executing 'simple network protocol' + DHCP Discover + DHCP reply received from 192.168.76.2 (52:55:c0:a8:4c:02) + as broadcast message. + Executing 'simple network protocol' succeeded + Tearing down 'simple network protocol' + Tearing down 'simple network protocol' succeeded + Boot services terminated + Summary: 0 failures + Preparing for reset. Press any key. + +The UEFI life cycle +------------------- + +After the U-Boot platform has been initialized the UEFI API provides two kinds +of services: + +* boot services +* runtime services + +The API can be extended by loading UEFI drivers which come in two variants: + +* boot drivers +* runtime drivers + +UEFI drivers are installed with U-Boot's bootefi command. With the same command +UEFI applications can be executed. + +Loaded images of UEFI drivers stay in memory after returning to U-Boot while +loaded images of applications are removed from memory. + +An UEFI application (e.g. an operating system) that wants to take full control +of the system calls ExitBootServices. After a UEFI application calls +ExitBootServices + +* boot services are not available anymore +* timer events are stopped +* the memory used by U-Boot except for runtime services is released +* the memory used by boot time drivers is released + +So this is a point of no return. Afterwards the UEFI application can only return +to U-Boot by rebooting. + +The UEFI object model +--------------------- + +UEFI offers a flexible and expandable object model. The objects in the UEFI API +are devices, drivers, and loaded images. These objects are referenced by +handles. + +The interfaces implemented by the objects are referred to as protocols. These +are identified by GUIDs. They can be installed and uninstalled by calling the +appropriate boot services. + +Handles are created by the InstallProtocolInterface or the +InstallMultipleProtocolinterfaces service if NULL is passed as handle. + +Handles are deleted when the last protocol has been removed with the +UninstallProtocolInterface or the UninstallMultipleProtocolInterfaces service. + +Devices offer the EFI_DEVICE_PATH_PROTOCOL. A device path is the concatenation +of device nodes. By their device paths all devices of a system are arranged in a +tree. + +Drivers offer the EFI_DRIVER_BINDING_PROTOCOL. This protocol is used to connect +a driver to devices (which are referenced as controllers in this context). + +Loaded images offer the EFI_LOADED_IMAGE_PROTOCOL. This protocol provides meta +information about the image and a pointer to the unload callback function. + +The UEFI events +--------------- + +In the UEFI terminology an event is a data object referencing a notification +function which is queued for calling when the event is signaled. The following +types of events exist: + +* periodic and single shot timer events +* exit boot services events, triggered by calling the ExitBootServices() service +* virtual address change events +* memory map change events +* read to boot events +* reset system events +* system table events +* events that are only triggered programmatically + +Events can be created with the CreateEvent service and deleted with CloseEvent +service. + +Events can be assigned to an event group. If any of the events in a group is +signaled, all other events in the group are also set to the signaled state. + +The UEFI driver model +--------------------- + +A driver is specific for a single protocol installed on a device. To install a +driver on a device the ConnectController service is called. In this context +controller refers to the device for which the driver is installed. + +The relevant drivers are identified using the EFI_DRIVER_BINDING_PROTOCOL. This +protocol has has three functions: + +* supported - determines if the driver is compatible with the device +* start - installs the driver by opening the relevant protocol with + attribute EFI_OPEN_PROTOCOL_BY_DRIVER +* stop - uninstalls the driver + +The driver may create child controllers (child devices). E.g. a driver for block +IO devices will create the device handles for the partitions. The child +controllers will open the supported protocol with the attribute +EFI_OPEN_PROTOCOL_BY_CHILD_CONTROLLER. + +A driver can be detached from a device using the DisconnectController service. + +U-Boot devices mapped as UEFI devices +------------------------------------- + +Some of the U-Boot devices are mapped as UEFI devices + +* block IO devices +* console +* graphical output +* network adapter + +As of U-Boot 2018.03 the logic for doing this is hard coded. + +The development target is to integrate the setup of these UEFI devices with the +U-Boot driver model [5]. So when a U-Boot device is discovered a handle should +be created and the device path protocol and the relevant IO protocol should be +installed. The UEFI driver then would be attached by calling ConnectController. +When a U-Boot device is removed DisconnectController should be called. + +UEFI devices mapped as U-Boot devices +------------------------------------- + +UEFI drivers binaries and applications may create new (virtual) devices, install +a protocol and call the ConnectController service. Now the matching UEFI driver +is determined by iterating over the implementations of the +EFI_DRIVER_BINDING_PROTOCOL. + +It is the task of the UEFI driver to create a corresponding U-Boot device and to +proxy calls for this U-Boot device to the controller. + +In U-Boot 2018.03 this has only been implemented for block IO devices. + +UEFI uclass +~~~~~~~~~~~ + +An UEFI uclass driver (lib/efi_driver/efi_uclass.c) has been created that +takes care of initializing the UEFI drivers and providing the +EFI_DRIVER_BINDING_PROTOCOL implementation for the UEFI drivers. + +A linker created list is used to keep track of the UEFI drivers. To create an +entry in the list the UEFI driver uses the U_BOOT_DRIVER macro specifying +UCLASS_EFI as the ID of its uclass, e.g:: + + /* Identify as UEFI driver */ + U_BOOT_DRIVER(efi_block) = { + .name = "EFI block driver", + .id = UCLASS_EFI, + .ops = &driver_ops, + }; + +The available operations are defined via the structure struct efi_driver_ops:: + + struct efi_driver_ops { + const efi_guid_t *protocol; + const efi_guid_t *child_protocol; + int (*bind)(efi_handle_t handle, void *interface); + }; + +When the supported() function of the EFI_DRIVER_BINDING_PROTOCOL is called the +uclass checks if the protocol GUID matches the protocol GUID of the UEFI driver. +In the start() function the bind() function of the UEFI driver is called after +checking the GUID. +The stop() function of the EFI_DRIVER_BINDING_PROTOCOL disconnects the child +controllers created by the UEFI driver and the UEFI driver. (In U-Boot v2013.03 +this is not yet completely implemented.) + +UEFI block IO driver +~~~~~~~~~~~~~~~~~~~~ + +The UEFI block IO driver supports devices exposing the EFI_BLOCK_IO_PROTOCOL. + +When connected it creates a new U-Boot block IO device with interface type +IF_TYPE_EFI, adds child controllers mapping the partitions, and installs the +EFI_SIMPLE_FILE_SYSTEM_PROTOCOL on these. This can be used together with the +software iPXE to boot from iSCSI network drives [4]. + +This driver is only available if U-Boot is configured with:: + + CONFIG_BLK=y + CONFIG_PARTITIONS=y + +Miscellaneous +------------- + +Load file 2 protocol +~~~~~~~~~~~~~~~~~~~~ + +The load file 2 protocol can be used by the Linux kernel to load the initial +RAM disk. U-Boot can be configured to provide an implementation with:: + + EFI_LOAD_FILE2_INITRD=y + +When the option is enabled the user can add the initrd path with the efidebug +command. + +Load options Boot#### have a FilePathList[] member. The first element of +the array (FilePathList[0]) is the EFI binary to execute. When an initrd +is specified the Device Path for the initrd is denoted by a VenMedia node +with the EFI_INITRD_MEDIA_GUID. Each entry of the array is terminated by the +'end of entire device path' subtype (0xff). If a user wants to define multiple +initrds, those must by separated by the 'end of this instance' identifier of +the end node (0x01). + +So our final format of the FilePathList[] is:: + + Loaded image - end node (0xff) - VenMedia - initrd_1 - [end node (0x01) - initrd_n ...] - end node (0xff) + +Links +----- + +* [1] http://uefi.org/specifications - UEFI specifications +* [2] https://github.com/ARM-software/ebbr/releases/download/v1.0/ebbr-v1.0.pdf - + Embedded Base Boot Requirements (EBBR) Specification - Release v1.0 +* [3] https://developer.arm.com/docs/den0044/latest/server-base-boot-requirements-system-software-on-arm-platforms-version-11 - + Server Base Boot Requirements System Software on ARM Platforms - Version 1.1 +* [4] :doc:`iscsi` +* [5] :doc:`../driver-model/index` diff --git a/roms/u-boot/doc/develop/version.rst b/roms/u-boot/doc/develop/version.rst new file mode 100644 index 000000000..a7797db41 --- /dev/null +++ b/roms/u-boot/doc/develop/version.rst @@ -0,0 +1,101 @@ +.. SPDX-License-Identifier: GPL-2.0+ +.. Copyright (c) 2013 The Chromium OS Authors. + +Version information +=================== + +U-Boot releases are named by year and patch level, for example 2020.10 means the +release that came out in October 2020. Release candidates are tagged every few +weeks as the project heads to the next release. So 2020.10-rc1 was the first +release candidate (RC), tagged soon after 2020.07 was released. + +See https://www.denx.de/wiki/view/U-Boot/ReleaseCycle for full details. + +Within the build system, various Makefile variables are created, making use of +VERSION, PATCHLEVEL and EXTRAVERSION defined at the top of 'Makefile'. There is +also SUBLEVEL available for downstream use. See also CONFIG_IDENT_STRING. + +Some variables end up in a generated header file at +include/generated/version_autogenerated.h and can be accessed from C source by +including <version.h> + +The following are available: + + UBOOTRELEASE (Makefile) + Full release version as a string. If this is not a tagged release, it also + includes the number of commits since the last tag as well as the the git + hash. If there are uncommitted changes a '-dirty' suffix is added too. + + This is written by scripts/setlocalversion (maintained by Linux) to + include/config/uboot.release and ends up in the UBOOTRELEASE Makefile + variable. + + Examples:: + + 2020.10-rc3 + 2021.01-rc5-00248-g60dd854f3ba-dirty + + PLAIN_VERSION (string #define) + This is UBOOTRELEASE but available in C source. + + Examples:: + + 2020.10 + 2021.01-rc5-00248-g60dd854f3ba-dirty + + UBOOTVERSION (Makefile) + This holds just the first three components of UBOOTRELEASE (i.e. not the + git hash, etc.) + + Examples:: + + 2020.10 + 2021.01-rc5 + + U_BOOT_VERSION (string #define) + "U-Boot " followed by UBOOTRELEASE, for example:: + + U-Boot 2020.10 + U-Boot 2021.01-rc5 + + This is used as part of the banner string when U-Boot starts. + + U_BOOT_VERSION_STRING (string #define) + U_BOOT_VERSION followed by build-time information + and CONFIG_IDENT_STRING. + + Examples:: + + U-Boot 2020.10 (Jan 06 2021 - 08:50:36 -0700) + U-Boot 2021.01-rc5-00248-g60dd854f3ba-dirty (Jan 06 2021 - 08:50:36 -0700) for spring + + U_BOOT_VERSION_NUM (integer #define) + Release year, e.g. 2021 for release 2021.01. Note + this is an integer, not a string. + + U_BOOT_VERSION_NUM_PATCH (integer #define) + Patch number, e.g. 1 for release 2020.01. Note + this is an integer, not a string. + +Build date/time is also included. See the generated file +include/generated/timestamp_autogenerated.h for the available +fields. For example:: + + #define U_BOOT_DATE "Jan 06 2021" (US format only) + #define U_BOOT_TIME "08:50:36" (24-hour clock) + #define U_BOOT_TZ "-0700" (Time zone in hours) + #define U_BOOT_DMI_DATE "01/06/2021" (US format only) + #define U_BOOT_BUILD_DATE 0x20210106 (hex yyyymmdd format) + #define U_BOOT_EPOCH 1609948236 + +The Epoch is the number of seconds since midnight on 1/1/70. You can convert +this to a time with:: + + $ date -u -d @1609948236 + Wed 06 Jan 2021 03:50:36 PM UTC + $ date -d 'Wed 06 Jan 2021 03:50:36 PM UTC' +%s + 1609948236 + +Every time you build U-Boot this will update based on the time +on your build machine. See 'Reproducible builds' if you want to +avoid that. diff --git a/roms/u-boot/doc/device-tree-bindings/README b/roms/u-boot/doc/device-tree-bindings/README new file mode 100644 index 000000000..2ea3439a1 --- /dev/null +++ b/roms/u-boot/doc/device-tree-bindings/README @@ -0,0 +1,17 @@ +Device Tree Bindings Staging Area +================================= + +This directory contains device tree bindings for U-Boot. + +These follow along with Linux kernel bindings, with a few additions. By +adding the files here, U-Boot patches can clearly show thees additions. +This makes it easier for device tree people to review these additions in +patches sent to the U-Boot mailing list. + +The intent IS to commit these files to U-Boot. Hopefully at some point +the files will be stored in another repo (shared with Linux) which is +brought in as needed. Changes here are intended to mirror changes in the +Linux Documentation/devicetree/bindings/ directory. + +sjg@chromium.org +17-Jan-12 diff --git a/roms/u-boot/doc/device-tree-bindings/adc/adc.txt b/roms/u-boot/doc/device-tree-bindings/adc/adc.txt new file mode 100644 index 000000000..463de3c8c --- /dev/null +++ b/roms/u-boot/doc/device-tree-bindings/adc/adc.txt @@ -0,0 +1,62 @@ +ADC device binding + +There are no mandatory properties for ADC. However, if Voltage info is required, +then there are two options: +- use microvolts constraint or +- use regulator phandle to enable/read supply's Voltage + +Properties and constraints: +*optional and always checked, Voltage polarity info: +- vdd-polarity-negative: positive reference Voltage has a negative polarity +- vss-polarity-negative: negative reference Voltage has a negative polarity + +Chose one option, for each supply (Vdd/Vss): + +*optional and always checked, supply Voltage constants: +- vdd-supply: phandle to Vdd regulator's node +- vss-supply: phandle to Vss regulator's node + +*optional and checked only if the above corresponding, doesn't exist: +- vdd-microvolts: positive reference Voltage value [uV] +- vss-microvolts: negative reference Voltage value [uV] + +Example with constant 'Vdd' value: +adc@1000000 { + compatible = "some-adc"; + reg = <0xaabb000 0x100>; + status = "enabled"; + vdd-microvolts = <1800000>; +}; + +Example of supply phandle usage, for the ADC's VDD/VSS references as below: + _______ _______ + |Sandbox| |Sandbox| + : PMIC : : ADC : + . . . . + | | (Vdd) | AIN0|--> + | BUCK2|-------|VDDref | + | (3.3V)| _|VSSref | + |_______| | |_______| + _|_ + +For the above PMIC, the node can be defined as follows: +sandbox_pmic { + compatible = "sandbox,pmic"; + ... + buck2: buck2 { + regulator-name = "SUPPLY_3.3V"; + regulator-min-microvolt = <3300000>; + regulator-max-microvolt = <3300000>; + }; + ... +}; + +For the above ADC, the node can be defined as follows: +adc@0 { + compatible = "sandbox,adc"; + vdd-supply = <&buck2>; + vss-microvolts = <0>; +}; + +The ADC uclass code, will enable the supply before start of the conversion, +but it will not configure the regulator settings. diff --git a/roms/u-boot/doc/device-tree-bindings/adc/st,stm32-adc.txt b/roms/u-boot/doc/device-tree-bindings/adc/st,stm32-adc.txt new file mode 100644 index 000000000..07fb6cd76 --- /dev/null +++ b/roms/u-boot/doc/device-tree-bindings/adc/st,stm32-adc.txt @@ -0,0 +1,141 @@ +STMicroelectronics STM32 ADC device + +STM32 ADC is a successive approximation analog-to-digital converter. +It has several multiplexed input channels. Conversions can be performed +in single, continuous, scan or discontinuous mode. Result of the ADC is +stored in a left-aligned or right-aligned 32-bit data register. +Conversions can be launched in software or using hardware triggers. + +The analog watchdog feature allows the application to detect if the input +voltage goes beyond the user-defined, higher or lower thresholds. + +Each STM32 ADC block can have up to 3 ADC instances. + +Each instance supports two contexts to manage conversions, each one has its +own configurable sequence and trigger: +- regular conversion can be done in sequence, running in background +- injected conversions have higher priority, and so have the ability to + interrupt regular conversion sequence (either triggered in SW or HW). + Regular sequence is resumed, in case it has been interrupted. + +Contents of a stm32 adc root node: +----------------------------------- +Required properties: +- compatible: Should be one of: + "st,stm32f4-adc-core" + "st,stm32h7-adc-core" + "st,stm32mp1-adc-core" +- reg: Offset and length of the ADC block register set. +- interrupts: One or more interrupts for ADC block. Some parts like stm32f4 + and stm32h7 share a common ADC interrupt line. stm32mp1 has two separate + interrupt lines, one for each ADC within ADC block. +- clocks: Core can use up to two clocks, depending on part used: + - "adc" clock: for the analog circuitry, common to all ADCs. + It's required on stm32f4. + It's optional on stm32h7. + - "bus" clock: for registers access, common to all ADCs. + It's not present on stm32f4. + It's required on stm32h7. +- clock-names: Must be "adc" and/or "bus" depending on part used. +- interrupt-controller: Identifies the controller node as interrupt-parent +- vref-supply: Phandle to the vref input analog reference voltage. +- #interrupt-cells = <1>; +- #address-cells = <1>; +- #size-cells = <0>; + +Optional properties: +- A pinctrl state named "default" for each ADC channel may be defined to set + inX ADC pins in mode of operation for analog input on external pin. + +Contents of a stm32 adc child node: +----------------------------------- +An ADC block node should contain at least one subnode, representing an +ADC instance available on the machine. + +Required properties: +- compatible: Should be one of: + "st,stm32f4-adc" + "st,stm32h7-adc" + "st,stm32mp1-adc" +- reg: Offset of ADC instance in ADC block (e.g. may be 0x0, 0x100, 0x200). +- clocks: Input clock private to this ADC instance. It's required only on + stm32f4, that has per instance clock input for registers access. +- interrupt-parent: Phandle to the parent interrupt controller. +- interrupts: IRQ Line for the ADC (e.g. may be 0 for adc@0, 1 for adc@100 or + 2 for adc@200). +- st,adc-channels: List of single-ended channels muxed for this ADC. + It can have up to 16 channels on stm32f4 or 20 channels on stm32h7, numbered + from 0 to 15 or 19 (resp. for in0..in15 or in0..in19). +- st,adc-diff-channels: List of differential channels muxed for this ADC. + Depending on part used, some channels can be configured as differential + instead of single-ended (e.g. stm32h7). List here positive and negative + inputs pairs as <vinp vinn>, <vinp vinn>,... vinp and vinn are numbered + from 0 to 19 on stm32h7) + Note: At least one of "st,adc-channels" or "st,adc-diff-channels" is required. + Both properties can be used together. Some channels can be used as + single-ended and some other ones as differential (mixed). But channels + can't be configured both as single-ended and differential (invalid). +- #io-channel-cells = <1>: See the IIO bindings section "IIO consumers" in + Documentation/devicetree/bindings/iio/iio-bindings.txt + +Optional properties: +- dmas: Phandle to dma channel for this ADC instance. + See ../../dma/dma.txt for details. +- dma-names: Must be "rx" when dmas property is being used. +- assigned-resolution-bits: Resolution (bits) to use for conversions. Must + match device available resolutions: + * can be 6, 8, 10 or 12 on stm32f4 + * can be 8, 10, 12, 14 or 16 on stm32h7 + Default is maximum resolution if unset. +- st,min-sample-time-nsecs: Minimum sampling time in nanoseconds. + Depending on hardware (board) e.g. high/low analog input source impedance, + fine tune of ADC sampling time may be recommended. + This can be either one value or an array that matches 'st,adc-channels' list, + to set sample time resp. for all channels, or independently for each channel. + +Example: + adc: adc@40012000 { + compatible = "st,stm32f4-adc-core"; + reg = <0x40012000 0x400>; + interrupts = <18>; + clocks = <&rcc 0 168>; + clock-names = "adc"; + vref-supply = <®_vref>; + interrupt-controller; + pinctrl-names = "default"; + pinctrl-0 = <&adc3_in8_pin>; + + #interrupt-cells = <1>; + #address-cells = <1>; + #size-cells = <0>; + + adc@0 { + compatible = "st,stm32f4-adc"; + #io-channel-cells = <1>; + reg = <0x0>; + clocks = <&rcc 0 168>; + interrupt-parent = <&adc>; + interrupts = <0>; + st,adc-channels = <8>; + dmas = <&dma2 0 0 0x400 0x0>; + dma-names = "rx"; + assigned-resolution-bits = <8>; + }; + ... + other adc child nodes follow... + }; + +Example to setup: +- channel 1 as single-ended +- channels 2 & 3 as differential (with resp. 6 & 7 negative inputs) + + adc: adc@40022000 { + compatible = "st,stm32h7-adc-core"; + ... + adc1: adc@0 { + compatible = "st,stm32h7-adc"; + ... + st,adc-channels = <1>; + st,adc-diff-channels = <2 6>, <3 7>; + }; + }; diff --git a/roms/u-boot/doc/device-tree-bindings/arm/arm,scmi.txt b/roms/u-boot/doc/device-tree-bindings/arm/arm,scmi.txt new file mode 100644 index 000000000..a76124f4a --- /dev/null +++ b/roms/u-boot/doc/device-tree-bindings/arm/arm,scmi.txt @@ -0,0 +1,231 @@ +System Control and Management Interface (SCMI) Message Protocol +---------------------------------------------------------- + +The SCMI is intended to allow agents such as OSPM to manage various functions +that are provided by the hardware platform it is running on, including power +and performance functions. + +This binding is intended to define the interface the firmware implementing +the SCMI as described in ARM document number ARM DEN 0056A ("ARM System Control +and Management Interface Platform Design Document")[0] provide for OSPM in +the device tree. + +Required properties: + +The scmi node with the following properties shall be under the /firmware/ node. + +- compatible : shall be "arm,scmi" or "arm,scmi-smc" for smc/hvc transports +- mboxes: List of phandle and mailbox channel specifiers. It should contain + exactly one or two mailboxes, one for transmitting messages("tx") + and another optional for receiving the notifications("rx") if + supported. +- shmem : List of phandle pointing to the shared memory(SHM) area as per + generic mailbox client binding. +- #address-cells : should be '1' if the device has sub-nodes, maps to + protocol identifier for a given sub-node. +- #size-cells : should be '0' as 'reg' property doesn't have any size + associated with it. +- arm,smc-id : SMC id required when using smc or hvc transports + +Optional properties: + +- mbox-names: shall be "tx" or "rx" depending on mboxes entries. + +See Documentation/devicetree/bindings/mailbox/mailbox.txt for more details +about the generic mailbox controller and client driver bindings. + +The mailbox is the only permitted method of calling the SCMI firmware. +Mailbox doorbell is used as a mechanism to alert the presence of a +messages and/or notification. + +Each protocol supported shall have a sub-node with corresponding compatible +as described in the following sections. If the platform supports dedicated +communication channel for a particular protocol, the 3 properties namely: +mboxes, mbox-names and shmem shall be present in the sub-node corresponding +to that protocol. + +Clock/Performance bindings for the clocks/OPPs based on SCMI Message Protocol +------------------------------------------------------------ + +This binding uses the common clock binding[1]. + +Required properties: +- #clock-cells : Should be 1. Contains the Clock ID value used by SCMI commands. + +Power domain bindings for the power domains based on SCMI Message Protocol +------------------------------------------------------------ + +This binding for the SCMI power domain providers uses the generic power +domain binding[2]. + +Required properties: + - #power-domain-cells : Should be 1. Contains the device or the power + domain ID value used by SCMI commands. + +Regulator bindings for the SCMI Regulator based on SCMI Message Protocol +------------------------------------------------------------ +An SCMI Regulator is permanently bound to a well defined SCMI Voltage Domain, +and should be always positioned as a root regulator. +It does not support any current operation. + +SCMI Regulators are grouped under a 'regulators' node which in turn is a child +of the SCMI Voltage protocol node inside the desired SCMI instance node. + +This binding uses the common regulator binding[6]. + +Required properties: + - reg : shall identify an existent SCMI Voltage Domain. + +Sensor bindings for the sensors based on SCMI Message Protocol +-------------------------------------------------------------- +SCMI provides an API to access the various sensors on the SoC. + +Required properties: +- #thermal-sensor-cells: should be set to 1. This property follows the + thermal device tree bindings[3]. + + Valid cell values are raw identifiers (Sensor ID) + as used by the firmware. Refer to platform details + for your implementation for the IDs to use. + +Reset signal bindings for the reset domains based on SCMI Message Protocol +------------------------------------------------------------ + +This binding for the SCMI reset domain providers uses the generic reset +signal binding[5]. + +Required properties: + - #reset-cells : Should be 1. Contains the reset domain ID value used + by SCMI commands. + +SRAM and Shared Memory for SCMI +------------------------------- + +A small area of SRAM is reserved for SCMI communication between application +processors and SCP. + +The properties should follow the generic mmio-sram description found in [4] + +Each sub-node represents the reserved area for SCMI. + +Required sub-node properties: +- reg : The base offset and size of the reserved area with the SRAM +- compatible : should be "arm,scmi-shmem" for Non-secure SRAM based + shared memory + +[0] http://infocenter.arm.com/help/topic/com.arm.doc.den0056a/index.html +[1] Documentation/devicetree/bindings/clock/clock-bindings.txt +[2] Documentation/devicetree/bindings/power/power-domain.yaml +[3] Documentation/devicetree/bindings/thermal/thermal.txt +[4] Documentation/devicetree/bindings/sram/sram.yaml +[5] Documentation/devicetree/bindings/reset/reset.txt +[6] Documentation/devicetree/bindings/regulator/regulator.yaml + +Example: + +sram@50000000 { + compatible = "mmio-sram"; + reg = <0x0 0x50000000 0x0 0x10000>; + + #address-cells = <1>; + #size-cells = <1>; + ranges = <0 0x0 0x50000000 0x10000>; + + cpu_scp_lpri: scp-shmem@0 { + compatible = "arm,scmi-shmem"; + reg = <0x0 0x200>; + }; + + cpu_scp_hpri: scp-shmem@200 { + compatible = "arm,scmi-shmem"; + reg = <0x200 0x200>; + }; +}; + +mailbox@40000000 { + .... + #mbox-cells = <1>; + reg = <0x0 0x40000000 0x0 0x10000>; +}; + +firmware { + + ... + + scmi { + compatible = "arm,scmi"; + mboxes = <&mailbox 0 &mailbox 1>; + mbox-names = "tx", "rx"; + shmem = <&cpu_scp_lpri &cpu_scp_hpri>; + #address-cells = <1>; + #size-cells = <0>; + + scmi_devpd: protocol@11 { + reg = <0x11>; + #power-domain-cells = <1>; + }; + + scmi_dvfs: protocol@13 { + reg = <0x13>; + #clock-cells = <1>; + }; + + scmi_clk: protocol@14 { + reg = <0x14>; + #clock-cells = <1>; + }; + + scmi_sensors0: protocol@15 { + reg = <0x15>; + #thermal-sensor-cells = <1>; + }; + + scmi_reset: protocol@16 { + reg = <0x16>; + #reset-cells = <1>; + }; + + scmi_voltage: protocol@17 { + reg = <0x17>; + + regulators { + regulator_devX: regulator@0 { + reg = <0x0>; + regulator-max-microvolt = <3300000>; + }; + + regulator_devY: regulator@9 { + reg = <0x9>; + regulator-min-microvolt = <500000>; + regulator-max-microvolt = <4200000>; + }; + + ... + }; + }; + }; +}; + +cpu@0 { + ... + reg = <0 0>; + clocks = <&scmi_dvfs 0>; +}; + +hdlcd@7ff60000 { + ... + reg = <0 0x7ff60000 0 0x1000>; + clocks = <&scmi_clk 4>; + power-domains = <&scmi_devpd 1>; + resets = <&scmi_reset 10>; +}; + +thermal-zones { + soc_thermal { + polling-delay-passive = <100>; + polling-delay = <1000>; + /* sensor ID */ + thermal-sensors = <&scmi_sensors0 3>; + ... + }; +}; diff --git a/roms/u-boot/doc/device-tree-bindings/arm/l2c2x0.txt b/roms/u-boot/doc/device-tree-bindings/arm/l2c2x0.txt new file mode 100644 index 000000000..fbe6cb21f --- /dev/null +++ b/roms/u-boot/doc/device-tree-bindings/arm/l2c2x0.txt @@ -0,0 +1,114 @@ +* ARM L2 Cache Controller + +ARM cores often have a separate L2C210/L2C220/L2C310 (also known as PL210/PL220/ +PL310 and variants) based level 2 cache controller. All these various implementations +of the L2 cache controller have compatible programming models (Note 1). +Some of the properties that are just prefixed "cache-*" are taken from section +3.7.3 of the Devicetree Specification which can be found at: +https://www.devicetree.org/specifications/ + +The ARM L2 cache representation in the device tree should be done as follows: + +Required properties: + +- compatible : should be one of: + "arm,pl310-cache" + "arm,l220-cache" + "arm,l210-cache" + "bcm,bcm11351-a2-pl310-cache": DEPRECATED by "brcm,bcm11351-a2-pl310-cache" + "brcm,bcm11351-a2-pl310-cache": For Broadcom bcm11351 chipset where an + offset needs to be added to the address before passing down to the L2 + cache controller + "marvell,aurora-system-cache": Marvell Controller designed to be + compatible with the ARM one, with system cache mode (meaning + maintenance operations on L1 are broadcasted to the L2 and L2 + performs the same operation). + "marvell,aurora-outer-cache": Marvell Controller designed to be + compatible with the ARM one with outer cache mode. + "marvell,tauros3-cache": Marvell Tauros3 cache controller, compatible + with arm,pl310-cache controller. +- cache-unified : Specifies the cache is a unified cache. +- cache-level : Should be set to 2 for a level 2 cache. +- reg : Physical base address and size of cache controller's memory mapped + registers. + +Optional properties: + +- arm,data-latency : Cycles of latency for Data RAM accesses. Specifies 3 cells of + read, write and setup latencies. Minimum valid values are 1. Controllers + without setup latency control should use a value of 0. +- arm,tag-latency : Cycles of latency for Tag RAM accesses. Specifies 3 cells of + read, write and setup latencies. Controllers without setup latency control + should use 0. Controllers without separate read and write Tag RAM latency + values should only use the first cell. +- arm,dirty-latency : Cycles of latency for Dirty RAMs. This is a single cell. +- arm,filter-ranges : <start length> Starting address and length of window to + filter. Addresses in the filter window are directed to the M1 port. Other + addresses will go to the M0 port. +- arm,io-coherent : indicates that the system is operating in an hardware + I/O coherent mode. Valid only when the arm,pl310-cache compatible + string is used. +- interrupts : 1 combined interrupt. +- cache-size : specifies the size in bytes of the cache +- cache-sets : specifies the number of associativity sets of the cache +- cache-block-size : specifies the size in bytes of a cache block +- cache-line-size : specifies the size in bytes of a line in the cache, + if this is not specified, the line size is assumed to be equal to the + cache block size +- cache-id-part: cache id part number to be used if it is not present + on hardware +- wt-override: If present then L2 is forced to Write through mode +- arm,double-linefill : Override double linefill enable setting. Enable if + non-zero, disable if zero. +- arm,double-linefill-incr : Override double linefill on INCR read. Enable + if non-zero, disable if zero. +- arm,double-linefill-wrap : Override double linefill on WRAP read. Enable + if non-zero, disable if zero. +- arm,prefetch-drop : Override prefetch drop enable setting. Enable if non-zero, + disable if zero. +- arm,prefetch-offset : Override prefetch offset value. Valid values are + 0-7, 15, 23, and 31. +- arm,shared-override : The default behavior of the L220 or PL310 cache + controllers with respect to the shareable attribute is to transform "normal + memory non-cacheable transactions" into "cacheable no allocate" (for reads) + or "write through no write allocate" (for writes). + On systems where this may cause DMA buffer corruption, this property must be + specified to indicate that such transforms are precluded. +- arm,parity-enable : enable parity checking on the L2 cache (L220 or PL310). +- arm,parity-disable : disable parity checking on the L2 cache (L220 or PL310). +- arm,outer-sync-disable : disable the outer sync operation on the L2 cache. + Some core tiles, especially ARM PB11MPCore have a faulty L220 cache that + will randomly hang unless outer sync operations are disabled. +- prefetch-data : Data prefetch. Value: <0> (forcibly disable), <1> + (forcibly enable), property absent (retain settings set by firmware) +- prefetch-instr : Instruction prefetch. Value: <0> (forcibly disable), + <1> (forcibly enable), property absent (retain settings set by + firmware) +- arm,dynamic-clock-gating : L2 dynamic clock gating. Value: <0> (forcibly + disable), <1> (forcibly enable), property absent (OS specific behavior, + preferably retain firmware settings) +- arm,standby-mode: L2 standby mode enable. Value <0> (forcibly disable), + <1> (forcibly enable), property absent (OS specific behavior, + preferably retain firmware settings) +- arm,early-bresp-disable : Disable the CA9 optimization Early BRESP (PL310) +- arm,full-line-zero-disable : Disable the CA9 optimization Full line of zero + write (PL310) + +Example: + +L2: cache-controller { + compatible = "arm,pl310-cache"; + reg = <0xfff12000 0x1000>; + arm,data-latency = <1 1 1>; + arm,tag-latency = <2 2 2>; + arm,filter-ranges = <0x80000000 0x8000000>; + cache-unified; + cache-level = <2>; + interrupts = <45>; +}; + +Note 1: The description in this document doesn't apply to integrated L2 + cache controllers as found in e.g. Cortex-A15/A7/A57/A53. These + integrated L2 controllers are assumed to be all preconfigured by + early secure boot code. Thus no need to deal with their configuration + in the kernel at all. diff --git a/roms/u-boot/doc/device-tree-bindings/ata/intel-sata.txt b/roms/u-boot/doc/device-tree-bindings/ata/intel-sata.txt new file mode 100644 index 000000000..5e4da832a --- /dev/null +++ b/roms/u-boot/doc/device-tree-bindings/ata/intel-sata.txt @@ -0,0 +1,26 @@ +Intel Pantherpoint SATA Device Binding +====================================== + +The device tree node which describes the operation of the Intel Pantherpoint +SATA device is as follows: + +Required properties : +- compatible = "intel,pantherpoint-ahci" +- intel,sata-mode : string, one of: + "ahci" : Use AHCI mode (default) + "combined" : Use combined IDE + legacy mode + "plain-ide" : Use plain IDE mode +- intel,sata-port-map : Which SATA ports are enabled, bit 0=enable first port, + bit 1=enable second port, etc. +- intel,sata-port0-gen3-tx : Value for the IOBP_SP0G3IR register +- intel,sata-port1-gen3-tx : Value for the IOBP_SP1G3IR register + +Example +------- + +sata { + compatible = "intel,pantherpoint-ahci"; + intel,sata-mode = "ahci"; + intel,sata-port-map = <1>; + intel,sata-port0-gen3-tx = <0x00880a7f>; +}; diff --git a/roms/u-boot/doc/device-tree-bindings/axi/gdsys,ihs_axi.txt b/roms/u-boot/doc/device-tree-bindings/axi/gdsys,ihs_axi.txt new file mode 100644 index 000000000..110788fa9 --- /dev/null +++ b/roms/u-boot/doc/device-tree-bindings/axi/gdsys,ihs_axi.txt @@ -0,0 +1,22 @@ +gdsys AXI busses of IHS FPGA devices + +Certain gdsys IHS FPGAs offer a interface to their built-in AXI bus with which +the connected devices (usually IP cores) can be controlled via software. + +Required properties: +- compatible: must be "gdsys,ihs_axi" +- reg: describes the address and length of the AXI bus's register map (within + the FPGA's register space) + +Example: + +fpga0_axi_video0 { + #address-cells = <1>; + #size-cells = <1>; + compatible = "gdsys,ihs_axi"; + reg = <0x170 0x10>; + + axi_dev_1 { + ... + }; +}; diff --git a/roms/u-boot/doc/device-tree-bindings/bus/simple-pm-bus.txt b/roms/u-boot/doc/device-tree-bindings/bus/simple-pm-bus.txt new file mode 100644 index 000000000..6f1503713 --- /dev/null +++ b/roms/u-boot/doc/device-tree-bindings/bus/simple-pm-bus.txt @@ -0,0 +1,44 @@ +Simple Power-Managed Bus +======================== + +A Simple Power-Managed Bus is a transparent bus that doesn't need a real +driver, as it's typically initialized by the boot loader. + +However, its bus controller is part of a PM domain, or under the control of a +functional clock. Hence, the bus controller's PM domain and/or clock must be +enabled for child devices connected to the bus (either on-SoC or externally) +to function. + +While "simple-pm-bus" follows the "simple-bus" set of properties, as specified +in the Devicetree Specification, it is not an extension of "simple-bus". + + +Required properties: + - compatible: Must contain at least "simple-pm-bus". + Must not contain "simple-bus". + It's recommended to let this be preceded by one or more + vendor-specific compatible values. + - #address-cells, #size-cells, ranges: Must describe the mapping between + parent address and child address spaces. + +Optional platform-specific properties for clock or PM domain control (at least +one of them is required): + - clocks: Must contain a reference to the functional clock(s), + - power-domains: Must contain a reference to the PM domain. +Please refer to the binding documentation for the clock and/or PM domain +providers for more details. + + +Example: + + bsc: bus@fec10000 { + compatible = "renesas,bsc-sh73a0", "renesas,bsc", + "simple-pm-bus"; + #address-cells = <1>; + #size-cells = <1>; + ranges = <0 0 0x20000000>; + reg = <0xfec10000 0x400>; + interrupts = <0 39 IRQ_TYPE_LEVEL_HIGH>; + clocks = <&zb_clk>; + power-domains = <&pd_a4s>; + }; diff --git a/roms/u-boot/doc/device-tree-bindings/chosen.txt b/roms/u-boot/doc/device-tree-bindings/chosen.txt new file mode 100644 index 000000000..e5ba6720c --- /dev/null +++ b/roms/u-boot/doc/device-tree-bindings/chosen.txt @@ -0,0 +1,163 @@ +The chosen node +--------------- +The chosen node does not represent a real device, but serves as a place +for passing data like which serial device to used to print the logs etc + + +stdout-path property +-------------------- +Device trees may specify the device to be used for boot console output +with a stdout-path property under /chosen. + +Example +------- +/ { + chosen { + stdout-path = "/serial@f00:115200"; + }; + + serial@f00 { + compatible = "vendor,some-uart"; + reg = <0xf00 0x10>; + }; +}; + +tick-timer property +------------------- +In a system there are multiple timers, specify which timer to be used +as the tick-timer. Earlier it was hardcoded in the timer driver now +since device tree has all the timer nodes. Specify which timer to be +used as tick timer. + +Example +------- +/ { + chosen { + tick-timer = "/timer2@f00"; + }; + + timer2@f00 { + compatible = "vendor,some-timer"; + reg = <0xf00 0x10>; + }; +}; + +u-boot,bootcount-device property +-------------------------------- + +In a DM-based system, the bootcount may be stored in a device known to +the DM framework (e.g. in a battery-backed SRAM area within a RTC +device) managed by a device conforming to UCLASS_BOOTCOUNT. If +multiple such devices are present in a system concurrently, then the +u-boot,bootcount-device property can select the preferred target. + +Example +------- +/ { + chosen { + u-boot,bootcount-device = &bootcount-rv3029; + }; + + bootcount-rv3029: bootcount@0 { + compatible = "u-boot,bootcount-rtc"; + rtc = &rv3029; + offset = <0x38>; + }; + + i2c2 { + rv3029: rtc@56 { + compatible = "mc,rv3029"; + reg = <0x56>; + }; + }; +}; + +u-boot,spl-boot-order property +------------------------------ + +In a system using an SPL stage and having multiple boot sources +(e.g. SPI NOR flash, on-board eMMC and a removable SD-card), the boot +device may be probed by reading the image and verifying an image +signature. + +If the SPL is configured through the device-tree, the boot-order can +be configured with the spl-boot-order property under the /chosen node. +Each list element of the property should specify a device to be probed +in the order they are listed: references (i.e. implicit paths), a full +path or an alias is expected for each entry. + +A special specifier "same-as-spl" can be used at any position in the +boot-order to direct U-Boot to insert the device the SPL was booted +from there. Whether this is indeed inserted or silently ignored (if +it is not supported on any given SoC/board or if the boot-device is +not available to continue booting from) is implementation-defined. +Note that if "same-as-spl" expands to an actual node for a given +board, the corresponding node may appear multiple times in the +boot-order (as there currently exists no mechanism to suppress +duplicates from the list). + +Example +------- +/ { + chosen { + u-boot,spl-boot-order = "same-as-spl", &sdmmc, "/sdhci@fe330000"; + }; +}; + +u-boot,spl-boot-device property +------------------------------- + +This property is a companion-property to the u-boot,spl-boot-order and +will be injected automatically by the SPL stage to notify a later stage +of where said later stage was booted from. + +You should not define this property yourself in the device-tree, as it +may be overwritten without warning. + +firmware-loader property +------------------------ +Multiple file system firmware loader nodes could be defined in device trees for +multiple storage type and their default partition, then a property +"firmware-loader" can be used to pass default firmware loader +node(default storage type) to the firmware loader driver. + +Example +------- +/ { + chosen { + firmware-loader = &fs_loader0; + }; + + fs_loader0: fs-loader@0 { + u-boot,dm-pre-reloc; + compatible = "u-boot,fs-loader"; + phandlepart = <&mmc 1>; + }; +}; + +u-boot,acpi-ssdt-order +---------------------- + +This provides the ordering to use when writing device data to the ACPI SSDT +(Secondary System Descriptor Table). Each cell is a phandle pointer to a device +node to add. The ACPI information is written in this order. + +If the ordering does not include all nodes, an error is generated. + +e820-entries +------------ + +This provides a way to add entries to the e820 table which tells the OS about +the memory map. The property contains three sets of 64-bit values: + + address - Start address of region + size - Size of region + flags - Flags (E820_...) + +Example: + +chosen { + e820-entries = /bits/ 64 < + IOMAP_P2SB_BAR IOMAP P2SB_SIZE E820_RESERVED + MCH_BASE_ADDRESS MCH_SIZE E820_RESERVED>; +}; diff --git a/roms/u-boot/doc/device-tree-bindings/clock/fixed-factor-clock.txt b/roms/u-boot/doc/device-tree-bindings/clock/fixed-factor-clock.txt new file mode 100644 index 000000000..1bae8527e --- /dev/null +++ b/roms/u-boot/doc/device-tree-bindings/clock/fixed-factor-clock.txt @@ -0,0 +1,24 @@ +Binding for simple fixed factor rate clock sources. + +This binding uses the common clock binding[1]. + +[1] Documentation/devicetree/bindings/clock/clock-bindings.txt + +Required properties: +- compatible : shall be "fixed-factor-clock". +- #clock-cells : from common clock binding; shall be set to 0. +- clock-div: fixed divider. +- clock-mult: fixed multiplier. +- clocks: parent clock. + +Optional properties: +- clock-output-names : From common clock binding. + +Example: + clock { + compatible = "fixed-factor-clock"; + clocks = <&parentclk>; + #clock-cells = <0>; + clock-div = <2>; + clock-mult = <1>; + }; diff --git a/roms/u-boot/doc/device-tree-bindings/clock/fsl,mpc83xx-clk.txt b/roms/u-boot/doc/device-tree-bindings/clock/fsl,mpc83xx-clk.txt new file mode 100644 index 000000000..8313da850 --- /dev/null +++ b/roms/u-boot/doc/device-tree-bindings/clock/fsl,mpc83xx-clk.txt @@ -0,0 +1,23 @@ +MPC83xx system clock devices + +MPC83xx SoCs supply a variety of clocks to drive various components of a +system. + +Required properties: +- compatible: must be one of "fsl,mpc8308-clk", + "fsl,mpc8309-clk", + "fsl,mpc8313-clk", + "fsl,mpc8315-clk", + "fsl,mpc832x-clk", + "fsl,mpc8349-clk", + "fsl,mpc8360-clk", + "fsl,mpc8379-clk" + depending on which SoC is employed +- #clock-cells: Must be 1 + +Example: + +socclocks: clocks { + compatible = "fsl,mpc832x-clk"; + #clock-cells = <1>; +}; diff --git a/roms/u-boot/doc/device-tree-bindings/clock/microchip,pic32-clock.txt b/roms/u-boot/doc/device-tree-bindings/clock/microchip,pic32-clock.txt new file mode 100644 index 000000000..f185ce0ae --- /dev/null +++ b/roms/u-boot/doc/device-tree-bindings/clock/microchip,pic32-clock.txt @@ -0,0 +1,33 @@ +* Microchip PIC32 Clock and Oscillator + +Microchip PIC32 clock tree consists of few oscillators, PLLs, +multiplexers and few divider modules capable of supplying clocks +to various controllers within SoC and also to off-chip. + +PIC32 clock controller output is defined by indices as defined +in [0] + +[0] include/dt-bindings/clock/microchip,clock.h + +Required Properties: +- compatible: should be "microchip,pic32mzda_clk" +- reg: physical base address of the controller and length of memory mapped + region. +- #clock-cells: should be 1. + +Example: Clock controller node: + + clock: clk@1f801200 { + compatible = "microchip,pic32mzda-clk"; + reg = <0x1f801200 0x1000>; + }; + +Example: UART controller node that consumes the clock generated by the clock +controller: + + uart1: serial@1f822000 { + compatible = "microchip,pic32mzda-uart"; + reg = <0xbf822000 0x50>; + interrupts = <112 IRQ_TYPE_LEVEL_HIGH>; + clocks = <&clock PB2CLK>; + }; diff --git a/roms/u-boot/doc/device-tree-bindings/clock/nvidia,tegra20-car.txt b/roms/u-boot/doc/device-tree-bindings/clock/nvidia,tegra20-car.txt new file mode 100644 index 000000000..5c07fcaed --- /dev/null +++ b/roms/u-boot/doc/device-tree-bindings/clock/nvidia,tegra20-car.txt @@ -0,0 +1,207 @@ +NVIDIA Tegra20 Clock And Reset Controller + +This binding uses the common clock binding: +Documentation/devicetree/bindings/clock/clock-bindings.txt + +The CAR (Clock And Reset) Controller on Tegra is the HW module responsible +for muxing and gating Tegra's clocks, and setting their rates. + +Required properties : +- compatible : Should be "nvidia,tegra20-car" +- reg : Should contain CAR registers location and length +- clocks : Should contain phandle and clock specifiers for two clocks: + the 32 KHz "32k_in", and the board-specific oscillator "osc". +- #clock-cells : Should be 1. + In clock consumers, this cell represents the clock ID exposed by the CAR. + + The first 96 clocks are numbered to match the bits in the CAR's CLK_OUT_ENB + registers. These IDs often match those in the CAR's RST_DEVICES registers, + but not in all cases. Some bits in CLK_OUT_ENB affect multiple clocks. In + this case, those clocks are assigned IDs above 95 in order to highlight + this issue. Implementations that interpret these clock IDs as bit values + within the CLK_OUT_ENB or RST_DEVICES registers should be careful to + explicitly handle these special cases. + + The balance of the clocks controlled by the CAR are assigned IDs of 96 and + above. + + 0 cpu + 1 unassigned + 2 unassigned + 3 ac97 + 4 rtc + 5 tmr + 6 uart1 + 7 unassigned (register bit affects uart2 and vfir) + 8 gpio + 9 sdmmc2 + 10 unassigned (register bit affects spdif_in and spdif_out) + 11 i2s1 + 12 i2c1 + 13 ndflash + 14 sdmmc1 + 15 sdmmc4 + 16 twc + 17 pwm + 18 i2s2 + 19 epp + 20 unassigned (register bit affects vi and vi_sensor) + 21 2d + 22 usbd + 23 isp + 24 3d + 25 ide + 26 disp2 + 27 disp1 + 28 host1x + 29 vcp + 30 unassigned + 31 cache2 + + 32 mem + 33 ahbdma + 34 apbdma + 35 unassigned + 36 kbc + 37 stat_mon + 38 pmc + 39 fuse + 40 kfuse + 41 sbc1 + 42 snor + 43 spi1 + 44 sbc2 + 45 xio + 46 sbc3 + 47 dvc + 48 dsi + 49 unassigned (register bit affects tvo and cve) + 50 mipi + 51 hdmi + 52 csi + 53 tvdac + 54 i2c2 + 55 uart3 + 56 unassigned + 57 emc + 58 usb2 + 59 usb3 + 60 mpe + 61 vde + 62 bsea + 63 bsev + + 64 speedo + 65 uart4 + 66 uart5 + 67 i2c3 + 68 sbc4 + 69 sdmmc3 + 70 pcie + 71 owr + 72 afi + 73 csite + 74 unassigned + 75 avpucq + 76 la + 77 unassigned + 78 unassigned + 79 unassigned + 80 unassigned + 81 unassigned + 82 unassigned + 83 unassigned + 84 irama + 85 iramb + 86 iramc + 87 iramd + 88 cram2 + 89 audio_2x a/k/a audio_2x_sync_clk + 90 clk_d + 91 unassigned + 92 sus + 93 cdev1 + 94 cdev2 + 95 unassigned + + 96 uart2 + 97 vfir + 98 spdif_in + 99 spdif_out + 100 vi + 101 vi_sensor + 102 tvo + 103 cve + 104 osc + 105 clk_32k a/k/a clk_s + 106 clk_m + 107 sclk + 108 cclk + 109 hclk + 110 pclk + 111 blink + 112 pll_a + 113 pll_a_out0 + 114 pll_c + 115 pll_c_out1 + 116 pll_d + 117 pll_d_out0 + 118 pll_e + 119 pll_m + 120 pll_m_out1 + 121 pll_p + 122 pll_p_out1 + 123 pll_p_out2 + 124 pll_p_out3 + 125 pll_p_out4 + 126 pll_s + 127 pll_u + 128 pll_x + 129 cop a/k/a avp + 130 audio a/k/a audio_sync_clk + +Example SoC include file: + +/ { + tegra_car: clock@60006000 { + compatible = "nvidia,tegra20-car"; + reg = <0x60006000 0x1000>; + #clock-cells = <1>; + }; + + usb@c5004000 { + clocks = <&tegra_car 58>; /* usb2 */ + }; +}; + +Example board file: + +/ { + clocks { + #address-cells = <1>; + #size-cells = <0>; + + osc: clock { + compatible = "fixed-clock"; + #clock-cells = <0>; + clock-frequency = <12000000>; + }; + }; + + i2c@7000d000 { + pmic@34 { + compatible = "ti,tps6586x"; + reg = <0x34>; + + clk_32k: clock { + compatible = "fixed-clock"; + #clock-cells = <0>; + clock-frequency = <32768>; + }; + }; + }; + + &tegra_car { + clocks = <&clk_32k> <&osc>; + }; +}; diff --git a/roms/u-boot/doc/device-tree-bindings/clock/rockchip,rk3188-cru.txt b/roms/u-boot/doc/device-tree-bindings/clock/rockchip,rk3188-cru.txt new file mode 100644 index 000000000..0c2bf5eba --- /dev/null +++ b/roms/u-boot/doc/device-tree-bindings/clock/rockchip,rk3188-cru.txt @@ -0,0 +1,61 @@ +* Rockchip RK3188/RK3066 Clock and Reset Unit + +The RK3188/RK3066 clock controller generates and supplies clock to various +controllers within the SoC and also implements a reset controller for SoC +peripherals. + +Required Properties: + +- compatible: should be "rockchip,rk3188-cru", "rockchip,rk3188a-cru" or + "rockchip,rk3066a-cru" +- reg: physical base address of the controller and length of memory mapped + region. +- #clock-cells: should be 1. +- #reset-cells: should be 1. + +Optional Properties: + +- rockchip,grf: phandle to the syscon managing the "general register files" + If missing pll rates are not changable, due to the missing pll lock status. + +Each clock is assigned an identifier and client nodes can use this identifier +to specify the clock which they consume. All available clocks are defined as +preprocessor macros in the dt-bindings/clock/rk3188-cru.h and +dt-bindings/clock/rk3066-cru.h headers and can be used in device tree sources. +Similar macros exist for the reset sources in these files. + +External clocks: + +There are several clocks that are generated outside the SoC. It is expected +that they are defined using standard clock bindings with following +clock-output-names: + - "xin24m" - crystal input - required, + - "xin32k" - rtc clock - optional, + - "xin27m" - 27mhz crystal input on rk3066 - optional, + - "ext_hsadc" - external HSADC clock - optional, + - "ext_cif0" - external camera clock - optional, + - "ext_rmii" - external RMII clock - optional, + - "ext_jtag" - externalJTAG clock - optional + +Example: Clock controller node: + + cru: cru@20000000 { + compatible = "rockchip,rk3188-cru"; + reg = <0x20000000 0x1000>; + rockchip,grf = <&grf>; + + #clock-cells = <1>; + #reset-cells = <1>; + }; + +Example: UART controller node that consumes the clock generated by the clock + controller: + + uart0: serial@10124000 { + compatible = "snps,dw-apb-uart"; + reg = <0x10124000 0x400>; + interrupts = <GIC_SPI 34 IRQ_TYPE_LEVEL_HIGH>; + reg-shift = <2>; + reg-io-width = <1>; + clocks = <&cru SCLK_UART0>; + }; diff --git a/roms/u-boot/doc/device-tree-bindings/clock/rockchip,rk3288-cru.txt b/roms/u-boot/doc/device-tree-bindings/clock/rockchip,rk3288-cru.txt new file mode 100644 index 000000000..c9fbb7657 --- /dev/null +++ b/roms/u-boot/doc/device-tree-bindings/clock/rockchip,rk3288-cru.txt @@ -0,0 +1,61 @@ +* Rockchip RK3288 Clock and Reset Unit + +The RK3288 clock controller generates and supplies clock to various +controllers within the SoC and also implements a reset controller for SoC +peripherals. + +Required Properties: + +- compatible: should be "rockchip,rk3288-cru" +- reg: physical base address of the controller and length of memory mapped + region. +- #clock-cells: should be 1. +- #reset-cells: should be 1. + +Optional Properties: + +- rockchip,grf: phandle to the syscon managing the "general register files" + If missing pll rates are not changable, due to the missing pll lock status. + +Each clock is assigned an identifier and client nodes can use this identifier +to specify the clock which they consume. All available clocks are defined as +preprocessor macros in the dt-bindings/clock/rk3288-cru.h headers and can be +used in device tree sources. Similar macros exist for the reset sources in +these files. + +External clocks: + +There are several clocks that are generated outside the SoC. It is expected +that they are defined using standard clock bindings with following +clock-output-names: + - "xin24m" - crystal input - required, + - "xin32k" - rtc clock - optional, + - "ext_i2s" - external I2S clock - optional, + - "ext_hsadc" - external HSADC clock - optional, + - "ext_edp_24m" - external display port clock - optional, + - "ext_vip" - external VIP clock - optional, + - "ext_isp" - external ISP clock - optional, + - "ext_jtag" - external JTAG clock - optional + +Example: Clock controller node: + + cru: cru@20000000 { + compatible = "rockchip,rk3188-cru"; + reg = <0x20000000 0x1000>; + rockchip,grf = <&grf>; + + #clock-cells = <1>; + #reset-cells = <1>; + }; + +Example: UART controller node that consumes the clock generated by the clock + controller: + + uart0: serial@10124000 { + compatible = "snps,dw-apb-uart"; + reg = <0x10124000 0x400>; + interrupts = <GIC_SPI 34 IRQ_TYPE_LEVEL_HIGH>; + reg-shift = <2>; + reg-io-width = <1>; + clocks = <&cru SCLK_UART0>; + }; diff --git a/roms/u-boot/doc/device-tree-bindings/clock/rockchip,rk3288-dmc.txt b/roms/u-boot/doc/device-tree-bindings/clock/rockchip,rk3288-dmc.txt new file mode 100644 index 000000000..2ca9db70a --- /dev/null +++ b/roms/u-boot/doc/device-tree-bindings/clock/rockchip,rk3288-dmc.txt @@ -0,0 +1,155 @@ +Rockchip Dynamic Memory Controller Driver +Required properties: +- compatible: "rockchip,rk3288-dmc", "syscon" +- rockchip,cru: this driver should access cru regs, so need get cru here +- rockchip,grf: this driver should access grf regs, so need get grf here +- rockchip,pmu: this driver should access pmu regs, so need get pmu here +- rockchip,sgrf: this driver should access sgrf regs, so need get sgrf here +- rockchip,noc: this driver should access noc regs, so need get noc here +- reg: dynamic ram protocol controller(PCTL) address and phy controller(PHYCTL) address +- clock: must include clock specifiers corresponding to entries in the clock-names property. +- clock-output-names: from common clock binding to override the default output clock name + Must contain + pclk_ddrupctl0: support clock for access protocol controller registers of channel 0 + pclk_publ0: support clock for access phy controller registers of channel 0 + pclk_ddrupctl1: support clock for access protocol controller registers of channel 1 + pclk_publ1: support clock for access phy controller registers of channel 1 + arm_clk: for get arm frequency +-logic-supply: this driver should adjust VDD_LOGIC according to dmc frequency, so need get logic-supply here +-timings: + Must contain + rockchip,odt-disable-freq: if ddr clock frequency low than odt-disable-freq,this driver should disable DDR ODT + rockchip,dll-disable-freq: if ddr clock frequency low than dll-disable-freq,this driver should disable DDR DLL + rockchip,sr-enable-freq: if ddr clock frequency high than sr-enable-freq,this driver should enable the automatic self refresh function + rockchip,pd-enable-freq: if ddr clock frequency high than pd-enable-freq,this driver should enable the automatic power down function + rockchip,auto-self-refresh-cnt: Self Refresh idle period. Memories are placed into Self-Refresh mode if the NIF is idle in Access state for auto-self-refresh-cnt * 32 * n_clk cycles.The automatic self refresh function is disabled when auto-self-refresh-cnt=0. + rockchip,auto-power-down-cnt: Power-down idle period. Memories are placed into power-down mode if the NIF is idle for auto-power-down-cnt n_clk cycles.The automatic power down function is disabled when auto-power-down-cnt=0. + rockchip,ddr-speed-bin: DDR3 type,AC timing parameters from the memory data-sheet + 0.DDR3_800D (5-5-5) + 1.DDR3_800E (6-6-6) + 2.DDR3_1066E (6-6-6) + 3.DDR3_1066F (7-7-7) + 4.DDR3_1066G (8-8-8) + 5.DDR3_1333F (7-7-7) + 6.DDR3_1333G (8-8-8) + 7.DDR3_1333H (9-9-9) + 8.DDR3_1333J (10-10-10) + 9.DDR3_1600G (8-8-8) + 10.DDR3_1600H (9-9-9) + 11.DDR3_1600J (10-10-10) + 12.DDR3_1600K (11-11-11) + 13.DDR3_1866J (10-10-10) + 14.DDR3_1866K (11-11-11) + 15.DDR3_1866L (12-12-12) + 16.DDR3_1866M (13-13-13) + 17.DDR3_2133K (11-11-11) + 18.DDR3_2133L (12-12-12) + 19.DDR3_2133M (13-13-13) + 20.DDR3_2133N (14-14-14) + 21.DDR3_DEFAULT + rockchip,trcd: tRCD,AC timing parameters from the memory data-sheet + rockchip,trp: tRP,AC timing parameters from the memory data-sheet +-rockchip,num-channels: number of SDRAM channels (1 or 2) +-rockchip,pctl-timing: parameters for the SDRAM setup, in this order: + togcnt1u + tinit + trsth + togcnt100n + trefi + tmrd + trfc + trp + trtw + tal + tcl + tcwl + tras + trc + trcd + trrd + trtp + twr + twtr + texsr + txp + txpdll + tzqcs + tzqcsi + tdqs + tcksre + tcksrx + tcke + tmod + trstl + tzqcl + tmrr + tckesr + tdpd +-rockchip,phy-timing: PHY timing information in this order: + dtpr0 + dtpr1 + dtpr2 + mr0..mr3 +-rockchip,sdram-channel: SDRAM channel information, each 8 bits. Both channels +will be set up the same. The parameters are in this order: + rank + col + bk + bw + dbw + row_3_4 + cs0_row + cs1_row +- rockchip,sdram-params: SDRAM base parameters, in this order: + NOC timing - value for ddrtiming register + NOC activate - value for activate register + ddrconf - value for ddrconf register + DDR frequency in MHz + DRAM type (3=DDR3, 6=LPDDR3) + stride - stride value for soc_con2 register + odt - 1 to enable DDR ODT, 0 to disable + +Example: + dmc: dmc@ff610000 { + compatible = "rockchip,rk3288-dmc", "syscon"; + rockchip,cru = <&cru>; + rockchip,grf = <&grf>; + rockchip,pmu = <&pmu>; + rockchip,sgrf = <&sgrf>; + rockchip,noc = <&noc>; + reg = <0xff610000 0x3fc + 0xff620000 0x294 + 0xff630000 0x3fc + 0xff640000 0x294>; + clocks = <&cru PCLK_DDRUPCTL0>, <&cru PCLK_PUBL0>, + <&cru PCLK_DDRUPCTL1>, <&cru PCLK_PUBL1>, + <&cru ARMCLK>; + clock-names = "pclk_ddrupctl0", "pclk_publ0", + "pclk_ddrupctl1", "pclk_publ1", + "arm_clk"; + }; + + &dmc { + logic-supply = <&vdd_logic>; + timings { + rockchip,odt-disable-freq = <333000000>; + rockchip,dll-disable-freq = <333000000>; + rockchip,sr-enable-freq = <333000000>; + rockchip,pd-enable-freq = <666000000>; + rockchip,auto-self-refresh-cnt = <0>; + rockchip,auto-power-down-cnt = <64>; + rockchip,ddr-speed-bin = <21>; + rockchip,trcd = <10>; + rockchip,trp = <10>; + }; + rockchip,num-channels = <2>; + rockchip,pctl-timing = <0x29a 0x1f4 0xc8 0x42 0x4e 0x4 0xea 0xa + 0x5 0x0 0xa 0x7 0x19 0x24 0xa 0x7 + 0x5 0xa 0x5 0x200 0x5 0x10 0x40 0x0 + 0x1 0x7 0x7 0x4 0xc 0x43 0x100 0x0 + 0x5 0x0>; + rockchip,phy-timing = <0x48f9aab4 0xea0910 0x1002c200 + 0xa60 0x40 0x10 0x0>; + rockchip,sdram-channel = /bits/ 8 <0x1 0xa 0x3 0x2 0x1 0x0 0xf 0xf>; + rockchip,sdram-params = <0x30B25564 0x627 3 666000000 3 9 1>; + }; diff --git a/roms/u-boot/doc/device-tree-bindings/clock/rockchip,rk3368-dmc.txt b/roms/u-boot/doc/device-tree-bindings/clock/rockchip,rk3368-dmc.txt new file mode 100644 index 000000000..8e7357d53 --- /dev/null +++ b/roms/u-boot/doc/device-tree-bindings/clock/rockchip,rk3368-dmc.txt @@ -0,0 +1,67 @@ +RK3368 dynamic memory controller driver +======================================= + +The RK3368 DMC (dynamic memory controller) driver supports setup/initialisation +during TPL using configuration data from the DTS (i.e. OF_PLATDATA), based on +the following key configuration data: + (a) a target-frequency (i.e. operating point) for the memory operation + (b) a speed-bin (as defined in JESD-79) for the DDR3 used in hardware + (c) a memory-schedule (i.e. mapping from physical addresses to the address + pins of the memory bus) + +Required properties +------------------- + +- compatible: "rockchip,rk3368-dmc" +- reg + protocol controller (PCTL) address and PHY controller (DDRPHY) address +- rockchip,ddr-speed-bin + the DDR3 device's speed-bin (as specified according to JESD-79) + DDR3_800D (5-5-5) + DDR3_800E (6-6-6) + DDR3_1066E (6-6-6) + DDR3_1066F (7-7-7) + DDR3_1066G (8-8-8) + DDR3_1333F (7-7-7) + DDR3_1333G (8-8-8) + DDR3_1333H (9-9-9) + DDR3_1333J (10-10-10) + DDR3_1600G (8-8-8) + DDR3_1600H (9-9-9) + DDR3_1600J (10-10-10) + DDR3_1600K (11-11-11) + DDR3_1866J (10-10-10) + DDR3_1866K (11-11-11) + DDR3_1866L (12-12-12) + DDR3_1866M (13-13-13) + DDR3_2133K (11-11-11) + DDR3_2133L (12-12-12) + DDR3_2133M (13-13-13) + DDR3_2133N (14-14-14) +- rockchip,ddr-frequency: + target DDR clock frequency in Hz (not all frequencies may be supported, + as there's some cooperation from the clock-driver required) +- rockchip,memory-schedule: + controls the decoding of physical addresses to DRAM addressing (i.e. how + the physical address maps onto the address pins/chip-select of the device) + DMC_MSCH_CBDR: column -> bank -> device -> row + DMC_MSCH_CBRD: column -> band -> row -> device + DMC_MSCH_CRBD: column -> row -> band -> device + +Example (for DDR3-1600K and 800MHz) +----------------------------------- + + #include <dt-bindings/memory/rk3368-dmc.h> + + dmc: dmc@ff610000 { + u-boot,dm-pre-reloc; + compatible = "rockchip,rk3368-dmc"; + reg = <0 0xff610000 0 0x400 + 0 0xff620000 0 0x400>; + }; + + &dmc { + rockchip,ddr-speed-bin = <DDR3_1600K>; + rockchip,ddr-frequency = <800000000>; + rockchip,memory-schedule = <DMC_MSCH_CBRD>; + }; diff --git a/roms/u-boot/doc/device-tree-bindings/clock/rockchip,rk3399-dmc.txt b/roms/u-boot/doc/device-tree-bindings/clock/rockchip,rk3399-dmc.txt new file mode 100644 index 000000000..a15dc5d1f --- /dev/null +++ b/roms/u-boot/doc/device-tree-bindings/clock/rockchip,rk3399-dmc.txt @@ -0,0 +1,42 @@ +Rockchip Dynamic Memory Controller Driver +Required properties: +- compatible: "rockchip,rk3399-dmc", "syscon" +- rockchip,cru: this driver should access cru regs, so need get cru here +- rockchip,pmucru: this driver should access pmucru regs, so need get pmucru here +- rockchip,pmugrf: this driver should access pmugrf regs, so need get pmugrf here +- rockchip,pmusgrf: this driver should access pmusgrf regs, so need get pmusgrf here +- rockchip,cic: this driver should access cic regs, so need get cic here +- reg: dynamic ram protocol controller(PCTL) address, PHY Independent(PI) address, phy controller(PHYCTL) address and memory schedule(MSCH) address +- clock: must include clock specifiers corresponding to entries in the clock-names property. + Must contain + dmc_clk: for ddr working frequency +- rockchip,sdram-params: SDRAM parameters, including all the information by ddr driver: + Must contain + Genarate by vendor tool and adjust for U-Boot dtsi. + +Example: + dmc: dmc { + u-boot,dm-pre-reloc; + compatible = "rockchip,rk3399-dmc"; + devfreq-events = <&dfi>; + interrupts = <GIC_SPI 1 IRQ_TYPE_LEVEL_HIGH 0>; + clocks = <&cru SCLK_DDRCLK>; + clock-names = "dmc_clk"; + reg = <0x0 0xffa80000 0x0 0x0800 + 0x0 0xffa80800 0x0 0x1800 + 0x0 0xffa82000 0x0 0x2000 + 0x0 0xffa84000 0x0 0x1000 + 0x0 0xffa88000 0x0 0x0800 + 0x0 0xffa88800 0x0 0x1800 + 0x0 0xffa8a000 0x0 0x2000 + 0x0 0xffa8c000 0x0 0x1000>; + }; + + &dmc { + rockchip,sdram-params = < + 0x2 + 0xa + 0x3 + ... + >; + }; diff --git a/roms/u-boot/doc/device-tree-bindings/clock/rockchip.txt b/roms/u-boot/doc/device-tree-bindings/clock/rockchip.txt new file mode 100644 index 000000000..22f6769e5 --- /dev/null +++ b/roms/u-boot/doc/device-tree-bindings/clock/rockchip.txt @@ -0,0 +1,77 @@ +Device Tree Clock bindings for arch-rockchip + +This binding uses the common clock binding[1]. + +[1] Documentation/devicetree/bindings/clock/clock-bindings.txt + +== Gate clocks == + +These bindings are deprecated! +Please use the soc specific CRU bindings instead. + +The gate registers form a continuos block which makes the dt node +structure a matter of taste, as either all gates can be put into +one gate clock spanning all registers or they can be divided into +the 10 individual gates containing 16 clocks each. +The code supports both approaches. + +Required properties: +- compatible : "rockchip,rk2928-gate-clk" +- reg : shall be the control register address(es) for the clock. +- #clock-cells : from common clock binding; shall be set to 1 +- clock-output-names : the corresponding gate names that the clock controls +- clocks : should contain the parent clock for each individual gate, + therefore the number of clocks elements should match the number of + clock-output-names + +Example using multiple gate clocks: + + clk_gates0: gate-clk@200000d0 { + compatible = "rockchip,rk2928-gate-clk"; + reg = <0x200000d0 0x4>; + clocks = <&dummy>, <&dummy>, + <&dummy>, <&dummy>, + <&dummy>, <&dummy>, + <&dummy>, <&dummy>, + <&dummy>, <&dummy>, + <&dummy>, <&dummy>, + <&dummy>, <&dummy>, + <&dummy>, <&dummy>; + + clock-output-names = + "gate_core_periph", "gate_cpu_gpll", + "gate_ddrphy", "gate_aclk_cpu", + "gate_hclk_cpu", "gate_pclk_cpu", + "gate_atclk_cpu", "gate_i2s0", + "gate_i2s0_frac", "gate_i2s1", + "gate_i2s1_frac", "gate_i2s2", + "gate_i2s2_frac", "gate_spdif", + "gate_spdif_frac", "gate_testclk"; + + #clock-cells = <1>; + }; + + clk_gates1: gate-clk@200000d4 { + compatible = "rockchip,rk2928-gate-clk"; + reg = <0x200000d4 0x4>; + clocks = <&xin24m>, <&xin24m>, + <&xin24m>, <&dummy>, + <&dummy>, <&xin24m>, + <&xin24m>, <&dummy>, + <&xin24m>, <&dummy>, + <&xin24m>, <&dummy>, + <&xin24m>, <&dummy>, + <&xin24m>, <&dummy>; + + clock-output-names = + "gate_timer0", "gate_timer1", + "gate_timer2", "gate_jtag", + "gate_aclk_lcdc1_src", "gate_otgphy0", + "gate_otgphy1", "gate_ddr_gpll", + "gate_uart0", "gate_frac_uart0", + "gate_uart1", "gate_frac_uart1", + "gate_uart2", "gate_frac_uart2", + "gate_uart3", "gate_frac_uart3"; + + #clock-cells = <1>; + }; diff --git a/roms/u-boot/doc/device-tree-bindings/clock/snps,hsdk-cgu.txt b/roms/u-boot/doc/device-tree-bindings/clock/snps,hsdk-cgu.txt new file mode 100644 index 000000000..82fe1dd83 --- /dev/null +++ b/roms/u-boot/doc/device-tree-bindings/clock/snps,hsdk-cgu.txt @@ -0,0 +1,35 @@ +* Synopsys HSDK clock generation unit + +The Synopsys HSDK clock controller generates and supplies clock to various +controllers and peripherals within the SoC. + +Required Properties: + +- compatible: should be "snps,hsdk-cgu-clock" +- reg: the pair of physical base address and length of clock generation unit + memory mapped region and creg arc core divider memory mapped region. +- #clock-cells: should be 1. + +Each clock is assigned an identifier and client nodes can use this identifier +to specify the clock which they consume. All available clocks are defined as +preprocessor macros in the dt-bindings/clock/snps,hsdk-cgu.h headers and can be +used in device tree sources. + +Example: Clock controller node: + + cgu_clk: cgu-clk@f0000000 { + compatible = "snps,hsdk-cgu-clock"; + reg = <0xf0000000 0x1000>, <0xf00014B8 0x4>; + #clock-cells = <1>; + }; + +Example: UART controller node that consumes the clock generated by the clock +controller: + + uart0: serial0@f0005000 { + compatible = "snps,dw-apb-uart"; + reg = <0xf0005000 0x1000>; + reg-shift = <2>; + reg-io-width = <4>; + clocks = <&cgu_clk CLK_SYS_UART_REF>; + }; diff --git a/roms/u-boot/doc/device-tree-bindings/clock/st,stm32-rcc.txt b/roms/u-boot/doc/device-tree-bindings/clock/st,stm32-rcc.txt new file mode 100644 index 000000000..0532d815d --- /dev/null +++ b/roms/u-boot/doc/device-tree-bindings/clock/st,stm32-rcc.txt @@ -0,0 +1,95 @@ +STMicroelectronics STM32 Reset and Clock Controller +=================================================== + +The RCC IP is both a reset and a clock controller. + +Please refer to clock-bindings.txt for common clock controller binding usage. +Please also refer to reset.txt for common reset controller binding usage. + +Required properties: +- compatible: Should be: + "st,stm32f42xx-rcc" + "st,stm32f469-rcc" +- reg: should be register base and length as documented in the + datasheet +- #reset-cells: 1, see below +- #clock-cells: 2, device nodes should specify the clock in their "clocks" + property, containing a phandle to the clock device node, an index selecting + between gated clocks and other clocks and an index specifying the clock to + use. + +Example: + + rcc: rcc@40023800 { + #reset-cells = <1>; + #clock-cells = <2> + compatible = "st,stm32f42xx-rcc", "st,stm32-rcc"; + reg = <0x40023800 0x400>; + }; + +Specifying gated clocks +======================= + +The primary index must be set to 0. + +The secondary index is the bit number within the RCC register bank, starting +from the first RCC clock enable register (RCC_AHB1ENR, address offset 0x30). + +It is calculated as: index = register_offset / 4 * 32 + bit_offset. +Where bit_offset is the bit offset within the register (LSB is 0, MSB is 31). + +To simplify the usage and to share bit definition with the reset and clock +drivers of the RCC IP, macros are available to generate the index in +human-readble format. + +For STM32F4 series, the macro are available here: + - include/dt-bindings/mfd/stm32f4-rcc.h + +Example: + + /* Gated clock, AHB1 bit 0 (GPIOA) */ + ... { + clocks = <&rcc 0 STM32F4_AHB1_CLOCK(GPIOA)> + }; + + /* Gated clock, AHB2 bit 4 (CRYP) */ + ... { + clocks = <&rcc 0 STM32F4_AHB2_CLOCK(CRYP)> + }; + +Specifying other clocks +======================= + +The primary index must be set to 1. + +The secondary index is bound with the following magic numbers: + + 0 SYSTICK + 1 FCLK + +Example: + + /* Misc clock, FCLK */ + ... { + clocks = <&rcc 1 STM32F4_APB1_CLOCK(TIM2)> + }; + + +Specifying softreset control of devices +======================================= + +Device nodes should specify the reset channel required in their "resets" +property, containing a phandle to the reset device node and an index specifying +which channel to use. +The index is the bit number within the RCC registers bank, starting from RCC +base address. +It is calculated as: index = register_offset / 4 * 32 + bit_offset. +Where bit_offset is the bit offset within the register. +For example, for CRC reset: + crc = AHB1RSTR_offset / 4 * 32 + CRCRST_bit_offset = 0x10 / 4 * 32 + 12 = 140 + +example: + + timer2 { + resets = <&rcc STM32F4_APB1_RESET(TIM2)>; + }; diff --git a/roms/u-boot/doc/device-tree-bindings/clock/st,stm32h7-rcc.txt b/roms/u-boot/doc/device-tree-bindings/clock/st,stm32h7-rcc.txt new file mode 100644 index 000000000..9d4b5873d --- /dev/null +++ b/roms/u-boot/doc/device-tree-bindings/clock/st,stm32h7-rcc.txt @@ -0,0 +1,152 @@ +STMicroelectronics STM32H7 Reset and Clock Controller +===================================================== + +The RCC IP is both a reset and a clock controller. + +Please refer to clock-bindings.txt for common clock controller binding usage. +Please also refer to reset.txt for common reset controller binding usage. + +Required properties: +- compatible: Should be: + "st,stm32h743-rcc" + +- reg: should be register base and length as documented in the + datasheet + +- #reset-cells: 1, see below + +- #clock-cells : from common clock binding; shall be set to 1 + +- clocks: External oscillator clock phandle + - high speed external clock signal (HSE) + - low speed external clock signal (LSE) + - external I2S clock (I2S_CKIN) + +- st,syscfg: phandle for pwrcfg, mandatory to disable/enable backup domain + write protection (RTC clock). + +- pll x node: Allow to register a pll with specific parameters. + Please see PLL section below. + +Example: + + rcc: rcc@58024400 { + #reset-cells = <1>; + #clock-cells = <2> + compatible = "st,stm32h743-rcc", "st,stm32-rcc"; + reg = <0x58024400 0x400>; + clocks = <&clk_hse>, <&clk_lse>, <&clk_i2s_ckin>; + + st,syscfg = <&pwrcfg>; + + #address-cells = <1>; + #size-cells = <0>; + + vco1@58024430 { + #clock-cells = <0>; + compatible = "stm32,pll"; + reg = <0>; + }; + + vco2@58024438 { + #clock-cells = <0>; + compatible = "stm32,pll"; + reg = <1>; + st,clock-div = <2>; + st,clock-mult = <40>; + st,frac-status = <0>; + st,frac = <0>; + st,vcosel = <1>; + st,pllrge = <2>; + }; + }; + + +STM32H7 PLL +----------- + +The VCO of STM32 PLL could be reprensented like this: + + Vref --------- -------- + ---->| / DIVM |---->| x DIVN | ------> VCO + --------- -------- + ^ + | + ------- + | FRACN | + ------- + +When the PLL is configured in integer mode: +- VCO = ( Vref / DIVM ) * DIVN + +When the PLL is configured in fractional mode: +- VCO = ( Vref / DIVM ) * ( DIVN + FRACN / 2^13) + + +Required properties for pll node: +- compatible: Should be: + "stm32,pll" + +- #clock-cells: from common clock binding; shall be set to 0 +- reg: Should be the pll number. + +Optional properties: +- st,clock-div: DIVM division factor : <1..63> +- st,clock-mult: DIVN multiplication factor : <4..512> + +- st,frac-status: + - 0 Pll is configured in integer mode + - 1 Pll is configure in fractional mode + +- st,frac: Fractional part of the multiplication factor : <0..8191> + +- st,vcosel: VCO selection + - 0: Wide VCO range:192 to 836 MHz + - 1: Medium VCO range:150 to 420 MHz + +- st,pllrge: PLL input frequency range + - 0: The PLL input (Vref / DIVM) clock range frequency is between 1 and 2 MHz + - 1: The PLL input (Vref / DIVM) clock range frequency is between 2 and 4 MHz + - 2: The PLL input (Vref / DIVM) clock range frequency is between 4 and 8 MHz + - 3: The PLL input (Vref / DIVM) clock range frequency is between 8 and 16 MHz + + +The peripheral clock consumer should specify the desired clock by +having the clock ID in its "clocks" phandle cell. + +All available clocks are defined as preprocessor macros in +dt-bindings/clock/stm32h7-clks.h header and can be used in device +tree sources. + +Example: + + timer5: timer@40000c00 { + compatible = "st,stm32-timer"; + reg = <0x40000c00 0x400>; + interrupts = <50>; + clocks = <&rcc TIM5_CK>; + + }; + +Specifying softreset control of devices +======================================= + +Device nodes should specify the reset channel required in their "resets" +property, containing a phandle to the reset device node and an index specifying +which channel to use. +The index is the bit number within the RCC registers bank, starting from RCC +base address. +It is calculated as: index = register_offset / 4 * 32 + bit_offset. +Where bit_offset is the bit offset within the register. + +For example, for CRC reset: + crc = AHB4RSTR_offset / 4 * 32 + CRCRST_bit_offset = 0x88 / 4 * 32 + 19 = 1107 + +All available preprocessor macros for reset are defined dt-bindings//mfd/stm32h7-rcc.h +header and can be used in device tree sources. + +example: + + timer2 { + resets = <&rcc STM32H7_APB1L_RESET(TIM2)>; + }; diff --git a/roms/u-boot/doc/device-tree-bindings/clock/st,stm32mp1.txt b/roms/u-boot/doc/device-tree-bindings/clock/st,stm32mp1.txt new file mode 100644 index 000000000..4d4136d2f --- /dev/null +++ b/roms/u-boot/doc/device-tree-bindings/clock/st,stm32mp1.txt @@ -0,0 +1,405 @@ +STMicroelectronics STM32MP1 clock tree initialization +===================================================== + +The STM32MP1 clock tree initialization is based on device tree information +for RCC IP node (st,stm32mp1-rcc) and on fixed-clock nodes. + +RCC IP = st,stm32mp1-rcc +======================== + +The RCC IP is both a reset and a clock controller but this documentation only +describes the fields added for clock tree initialization which are not present +in Linux binding for compatible "st,stm32mp1-rcc" defined in st,stm32mp1-rcc.txt +file. + +This parent node may optionally have additional children nodes which define +specific init values for RCC elements. + +The added properties for clock tree initialization are: + +Required properties: +- st,clksrc : The clock sources configuration array in a platform specific + order. + + For the STM32MP15x family there are 9 clock sources selector which are + configured in the following order: + MPU AXI MCU PLL12 PLL3 PLL4 RTC MCO1 MCO2 + + Clock source configuration values are defined by macros CLK_<NAME>_<SOURCE> + from dt-bindings/clock/stm32mp1-clksrc.h. + + Example: + st,clksrc = < + CLK_MPU_PLL1P + CLK_AXI_PLL2P + CLK_MCU_PLL3P + CLK_PLL12_HSE + CLK_PLL3_HSE + CLK_PLL4_HSE + CLK_RTC_LSE + CLK_MCO1_DISABLED + CLK_MCO2_DISABLED + >; + +- st,clkdiv : The clock main dividers value specified in an array + in a platform specific order. + + When used, it shall describe the whole clock dividers tree. + + For the STM32MP15x family there are 11 dividers values expected. + They shall be configured in the following order: + MPU AXI MCU APB1 APB2 APB3 APB4 APB5 RTC MCO1 MCO2 + + The each divider value uses the DIV coding defined in RCC associated + register RCC_xxxDIVR. In most the case, it is: + 0x0: not divided + 0x1: division by 2 + 0x2: division by 4 + 0x3: division by 8 + ... + + Note that for RTC MCO1 MCO2, the coding is different: + 0x0: not divided + 0x1: division by 2 + 0x2: division by 3 + 0x3: division by 4 + ... + + Example: + st,clkdiv = < + 1 /*MPU*/ + 0 /*AXI*/ + 0 /*MCU*/ + 1 /*APB1*/ + 1 /*APB2*/ + 1 /*APB3*/ + 1 /*APB4*/ + 2 /*APB5*/ + 23 /*RTC*/ + 0 /*MCO1*/ + 0 /*MCO2*/ + >; + +Optional Properties: +- children for a PLL configuration with "st,stm32mp1-pll" compatible + + each PLL children nodes for PLL1 to PLL4 (see ref manual for details) + are listed with associated reg 0 to 3. + PLLx is off when the associated node is absent or deactivated. + + For PLL1, when the node is absent, the frequency of the OPP node is used + to compute the PLL setting (see compatible "operating-points-v2" in + opp/opp.txt for details). + + Here are the available properties for each PLL node: + - compatible: should be "st,stm32mp1-pll" + + - reg: index of the pll instance + + - cfg: The parameters for PLL configuration in the following order: + DIVM DIVN DIVP DIVQ DIVR Output. + + DIVx values are defined as in RCC spec: + 0x0: bypass (division by 1) + 0x1: division by 2 + 0x2: division by 3 + 0x3: division by 4 + ... + + Output contains a bitfield for each output value (1:ON/0:OFF) + BIT(0) => output P : DIVPEN + BIT(1) => output Q : DIVQEN + BIT(2) => output R : DIVREN + NB: macro PQR(p,q,r) can be used to build this value + with p,q,r = 0 or 1. + + - frac : Fractional part of the multiplication factor + (optional, PLL is in integer mode when absent). + + - csg : Clock Spreading Generator (optional) with parameters in the + following order: MOD_PER INC_STEP SSCG_MODE. + + MOD_PER: Modulation Period Adjustment + INC_STEP: Modulation Depth Adjustment + SSCG_MODE: Spread spectrum clock generator mode, with associated + defined from stm32mp1-clksrc.h: + - SSCG_MODE_CENTER_SPREAD = 0 + - SSCG_MODE_DOWN_SPREAD = 1 + + Example: + st,pll@0 { + compatible = "st,stm32mp1-pll"; + reg = <0>; + cfg = < 1 53 0 0 0 1 >; + frac = < 0x810 >; + }; + st,pll@1 { + compatible = "st,stm32mp1-pll"; + reg = <1>; + cfg = < 1 43 1 0 0 PQR(0,1,1) >; + csg = < 10 20 1 >; + }; + st,pll@2 { + compatible = "st,stm32mp1-pll"; + reg = <2>; + cfg = < 2 85 3 13 3 0 >; + csg = < 10 20 SSCG_MODE_CENTER_SPREAD >; + }; + st,pll@3 { + compatible = "st,stm32mp1-pll"; + reg = <3>; + cfg = < 2 78 4 7 9 3 >; + }; + +- st,pkcs : used to configure the peripherals kernel clock selection. + + The property is a list of peripheral kernel clock source identifiers defined + by macros CLK_<KERNEL-CLOCK>_<PARENT-CLOCK> as defined by header file + dt-bindings/clock/stm32mp1-clksrc.h. + + st,pkcs may not list all the kernel clocks and has no ordering requirements. + + Example: + st,pkcs = < + CLK_STGEN_HSE + CLK_CKPER_HSI + CLK_USBPHY_PLL2P + CLK_DSI_PLL2Q + CLK_I2C46_HSI + CLK_UART1_HSI + CLK_UART24_HSI + >; + +other clocks = fixed-clock +========================== + +The clock tree is also based on 5 fixed-clock in clocks node +used to define the state of associated ST32MP1 oscillators: + - clk-lsi + - clk-lse + - clk-hsi + - clk-hse + - clk-csi + +At boot the clock tree initialization will + - enable oscillators present in device tree and not disabled + (node with status="disabled"), + - disable HSI oscillator if the node is absent (always activated by bootrom) + and not disabled (node with status="disabled"). + +Optional properties : + +a) for external oscillator: "clk-lse", "clk-hse" + + 4 optional fields are managed + - "st,bypass" configures the oscillator bypass mode (HSEBYP, LSEBYP) + - "st,digbypass" configures the bypass mode as full-swing digital + signal (DIGBYP) + - "st,css" activates the clock security system (HSECSSON, LSECSSON) + - "st,drive" (only for LSE) contains the value of the drive for the + oscillator (see LSEDRV_ defined in the file + dt-bindings/clock/stm32mp1-clksrc.h) + + Example board file: + / { + clocks { + clk_hse: clk-hse { + #clock-cells = <0>; + compatible = "fixed-clock"; + clock-frequency = <64000000>; + st,bypass; + }; + + clk_lse: clk-lse { + #clock-cells = <0>; + compatible = "fixed-clock"; + clock-frequency = <32768>; + st,css; + st,drive = <LSEDRV_LOWEST>; + }; + }; + +b) for internal oscillator: "clk-hsi" + + Internally HSI clock is fixed to 64MHz for STM32MP157 SoC. + In device tree, clk-hsi is the clock after HSIDIV (clk_hsi in RCC + doc). So this clock frequency is used to compute the expected HSI_DIV + for the clock tree initialization. + + Example with HSIDIV = /1: + / { + clocks { + clk_hsi: clk-hsi { + #clock-cells = <0>; + compatible = "fixed-clock"; + clock-frequency = <64000000>; + }; + }; + + Example with HSIDIV = /2 + / { + clocks { + clk_hsi: clk-hsi { + #clock-cells = <0>; + compatible = "fixed-clock"; + clock-frequency = <32000000>; + }; + }; + +Example of clock tree initialization +==================================== + +/ { + clocks { + u-boot,dm-pre-reloc; + clk_hse: clk-hse { + u-boot,dm-pre-reloc; + #clock-cells = <0>; + compatible = "fixed-clock"; + clock-frequency = <24000000>; + st,digbypass; + }; + + clk_hsi: clk-hsi { + u-boot,dm-pre-reloc; + #clock-cells = <0>; + compatible = "fixed-clock"; + clock-frequency = <64000000>; + }; + + clk_lse: clk-lse { + u-boot,dm-pre-reloc; + #clock-cells = <0>; + compatible = "fixed-clock"; + clock-frequency = <32768>; + }; + + clk_lsi: clk-lsi { + u-boot,dm-pre-reloc; + #clock-cells = <0>; + compatible = "fixed-clock"; + clock-frequency = <32000>; + }; + + clk_csi: clk-csi { + u-boot,dm-pre-reloc; + #clock-cells = <0>; + compatible = "fixed-clock"; + clock-frequency = <4000000>; + }; + }; + + soc { + + rcc: rcc@50000000 { + u-boot,dm-pre-reloc; + compatible = "st,stm32mp1-rcc", "syscon"; + reg = <0x50000000 0x1000>; + #address-cells = <1>; + #size-cells = <0>; + #clock-cells = <1>; + #reset-cells = <1>; + interrupts = <GIC_SPI 5 IRQ_TYPE_LEVEL_HIGH>; + + st,clksrc = < + CLK_MPU_PLL1P + CLK_AXI_PLL2P + CLK_MCU_PLL3P + CLK_PLL12_HSE + CLK_PLL3_HSE + CLK_PLL4_HSE + CLK_RTC_LSE + CLK_MCO1_DISABLED + CLK_MCO2_DISABLED + >; + + st,clkdiv = < + 1 /*MPU*/ + 0 /*AXI*/ + 0 /*MCU*/ + 1 /*APB1*/ + 1 /*APB2*/ + 1 /*APB3*/ + 1 /*APB4*/ + 2 /*APB5*/ + 23 /*RTC*/ + 0 /*MCO1*/ + 0 /*MCO2*/ + >; + + st,pkcs = < + CLK_CKPER_HSE + CLK_FMC_ACLK + CLK_QSPI_ACLK + CLK_ETH_DISABLED + CLK_SDMMC12_PLL4P + CLK_DSI_DSIPLL + CLK_STGEN_HSE + CLK_USBPHY_HSE + CLK_SPI2S1_PLL3Q + CLK_SPI2S23_PLL3Q + CLK_SPI45_HSI + CLK_SPI6_HSI + CLK_I2C46_HSI + CLK_SDMMC3_PLL4P + CLK_USBO_USBPHY + CLK_ADC_CKPER + CLK_CEC_LSE + CLK_I2C12_HSI + CLK_I2C35_HSI + CLK_UART1_HSI + CLK_UART24_HSI + CLK_UART35_HSI + CLK_UART6_HSI + CLK_UART78_HSI + CLK_SPDIF_PLL4P + CLK_FDCAN_PLL4Q + CLK_SAI1_PLL3Q + CLK_SAI2_PLL3Q + CLK_SAI3_PLL3Q + CLK_SAI4_PLL3Q + CLK_RNG1_LSI + CLK_RNG2_LSI + CLK_LPTIM1_PCLK1 + CLK_LPTIM23_PCLK3 + CLK_LPTIM45_LSE + >; + + /* VCO = 1300.0 MHz => P = 650 (CPU) */ + pll1: st,pll@0 { + compatible = "st,stm32mp1-pll"; + reg = <0>; + cfg = < 2 80 0 0 0 PQR(1,0,0) >; + frac = < 0x800 >; + u-boot,dm-pre-reloc; + }; + + /* VCO = 1066.0 MHz => P = 266 (AXI), Q = 533 (GPU), + R = 533 (DDR) */ + pll2: st,pll@1 { + compatible = "st,stm32mp1-pll"; + reg = <1>; + cfg = < 2 65 1 0 0 PQR(1,1,1) >; + frac = < 0x1400 >; + u-boot,dm-pre-reloc; + }; + + /* VCO = 417.8 MHz => P = 209, Q = 24, R = 11 */ + pll3: st,pll@2 { + compatible = "st,stm32mp1-pll"; + reg = <2>; + cfg = < 1 33 1 16 36 PQR(1,1,1) >; + frac = < 0x1a04 >; + u-boot,dm-pre-reloc; + }; + + /* VCO = 594.0 MHz => P = 99, Q = 74, R = 74 */ + pll4: st,pll@3 { + compatible = "st,stm32mp1-pll"; + reg = <3>; + cfg = < 3 98 5 7 7 PQR(1,1,1) >; + u-boot,dm-pre-reloc; + }; + }; + }; +}; diff --git a/roms/u-boot/doc/device-tree-bindings/clock/ti,cdce9xx.txt b/roms/u-boot/doc/device-tree-bindings/clock/ti,cdce9xx.txt new file mode 100644 index 000000000..0d01f2d5c --- /dev/null +++ b/roms/u-boot/doc/device-tree-bindings/clock/ti,cdce9xx.txt @@ -0,0 +1,49 @@ +Binding for TI CDCE913/925/937/949 programmable I2C clock synthesizers. + +Reference +This binding uses the common clock binding[1]. + +[1] Documentation/devicetree/bindings/clock/clock-bindings.txt +[2] http://www.ti.com/product/cdce913 +[3] http://www.ti.com/product/cdce925 +[4] http://www.ti.com/product/cdce937 +[5] http://www.ti.com/product/cdce949 + +The driver provides clock sources for each output Y1 through Y5. + +Required properties: + - compatible: Shall be one of the following: + - "ti,cdce913": 1-PLL, 3 Outputs + - "ti,cdce925": 2-PLL, 5 Outputs + - "ti,cdce937": 3-PLL, 7 Outputs + - "ti,cdce949": 4-PLL, 9 Outputs + - reg: I2C device address. + - clocks: Points to a fixed parent clock that provides the input frequency. + - #clock-cells: From common clock bindings: Shall be 1. + +Optional properties: + - xtal-load-pf: Crystal load-capacitor value to fine-tune performance on a + board, or to compensate for external influences. + +For all PLL1, PLL2, ... an optional child node can be used to specify spread +spectrum clocking parameters for a board. + - spread-spectrum: SSC mode as defined in the data sheet. + - spread-spectrum-center: Use "centered" mode instead of "max" mode. When + present, the clock runs at the requested frequency on average. Otherwise + the requested frequency is the maximum value of the SCC range. + + +Example: + + clockgen: cdce925pw@64 { + compatible = "cdce925"; + reg = <0x64>; + clocks = <&xtal_27Mhz>; + #clock-cells = <1>; + xtal-load-pf = <5>; + /* PLL options to get SSC 1% centered */ + PLL2 { + spread-spectrum = <4>; + spread-spectrum-center; + }; + }; diff --git a/roms/u-boot/doc/device-tree-bindings/clock/ti,sci-clk.txt b/roms/u-boot/doc/device-tree-bindings/clock/ti,sci-clk.txt new file mode 100644 index 000000000..c6fe48200 --- /dev/null +++ b/roms/u-boot/doc/device-tree-bindings/clock/ti,sci-clk.txt @@ -0,0 +1,53 @@ +Texas Instruments TI SCI Clock Controller +========================================= + +All clocks on Texas Instruments' SoCs that contain a System Controller, +are only controlled by this entity. Communication between a host processor +running an OS and the System Controller happens through a protocol known +as TI SCI[1]. This clock implementation plugs into the common clock +framework and makes use of the TI SCI protocol on clock API requests. + +[1] http://processors.wiki.ti.com/index.php/TISCI + +Clock Controller Node +===================== +The clock controller node represents the clocks managed by the SYSFW. Because +this relies on the TI SCI protocol to communicate with the SYSFW it must be a +child of the sysfw node. + +Required Properties: +-------------------- +- compatible: Must be "ti,k2g-sci-clk" +- #clock-cells: Must be be 2. In clock consumers, this cell represents the + device ID and clock ID exposed by the SYSFW firmware. + +Example (AM65x): +---------------- + dmsc: dmsc { + compatible = "ti,k2g-sci"; + ... + k3_clks: clocks { + compatible = "ti,k2g-sci-clk"; + #clock-cells = <2>; + }; + }; + +Clock Consumers +=============== +Hardware blocks supplied by a clock should contain a "clocks" property that is +a phandle pointing to the clock controller node along with an index representing +the device id together with a clock ID to be passed to the SYSFW for device +control. + +Required Properties: +-------------------- +- clocks: phandle pointing to the corresponding clock node, an ID representing + the device, and an index representing a clock. + +Example (AM65x): +---------------- + uart2: serial@02800000 { + compatible = "ti,omap4-uart"; + ... + clocks = <&k3_clks 0x0007 1>; + }; diff --git a/roms/u-boot/doc/device-tree-bindings/config.txt b/roms/u-boot/doc/device-tree-bindings/config.txt new file mode 100644 index 000000000..6cdc16da5 --- /dev/null +++ b/roms/u-boot/doc/device-tree-bindings/config.txt @@ -0,0 +1,54 @@ +The /config node (Configuration Options) +---------------------------------------- + +A number of run-time configuration options are provided in the /config node +of the control device tree. You can access these using fdtdec_get_config_int(), +fdtdec_get_config_bool() and fdtdec_get_config_string(). + +Available options are: + +silent-console + If present and non-zero, the console is silenced by default on boot. + +no-keyboard + Tells U-Boot not to expect an attached keyboard with a VGA console + +u-boot,efi-partition-entries-offset + If present, this provides an offset (in bytes, from the start of a + device) that should be skipped over before the partition entries. + This is used by the EFI/GPT partition implementation when a device + is formatted. + + This setting will override any values configured via Kconfig. + +u-boot,mmc-env-partition + if present, the environment shall be placed at the last + CONFIG_ENV_SIZE blocks of the partition on the + CONFIG_SYS_MMC_ENV_DEV. + + if u-boot,mmc-env-offset* is present, this setting will take + precedence. In that case, only if the partition is not found, + mmc-env-offset* will be tried. + +u-boot,mmc-env-offset +u-boot,mmc-env-offset-redundant + If present, the values of the 'u-boot,mmc-env-offset' and/or + of the u-boot,mmc-env-offset-redundant' properties overrides + CONFIG_ENV_OFFSET and CONFIG_ENV_OFFSET_REDUND, respectively, + for SD/MMC devices. + + Values are interpreted as the offset from the start of the + device, specified in bytes. It is assumed that the setting + will point at the beginning of a LBA and values that are not + LBA-aligned will be rounded up to the next LBA address. + +u-boot,spl-payload-offset + If present (and SPL is controlled by the device-tree), this allows + to override the CONFIG_SYS_SPI_U_BOOT_OFFS setting using a value + from the device-tree. + +sysreset-gpio + If present (and supported by the specific board), indicates a + GPIO that can be set to trigger a system reset. It is assumed + that such a system reset will effect a complete platform reset, + being roughly equivalent to a power-on reset. diff --git a/roms/u-boot/doc/device-tree-bindings/cpu/fsl,mpc83xx.txt b/roms/u-boot/doc/device-tree-bindings/cpu/fsl,mpc83xx.txt new file mode 100644 index 000000000..ac563d906 --- /dev/null +++ b/roms/u-boot/doc/device-tree-bindings/cpu/fsl,mpc83xx.txt @@ -0,0 +1,34 @@ +MPC83xx CPU devices + +MPC83xx SoCs contain a e300 core as their main processor. + +Required properties: +- compatible: must be one of "fsl,mpc83xx", + "fsl,mpc8308", + "fsl,mpc8309", + "fsl,mpc8313", + "fsl,mpc8315", + "fsl,mpc832x", + "fsl,mpc8349", + "fsl,mpc8360", + "fsl,mpc8379" +- clocks: has to have two entries, which must be the core clock at index 0 and + the CSB (Coherent System Bus) clock at index 1. Both are given by a suitable + "fsl,mpc83xx-clk" device + +Example: + +socclocks: clocks { + compatible = "fsl,mpc8315-clk"; + #clock-cells = <1>; +}; + +cpus { + compatible = "cpu_bus"; + + PowerPC,8315@0 { + compatible = "fsl,mpc8315"; + clocks = <&socclocks MPC83XX_CLK_CORE + &socclocks MPC83XX_CLK_CSB>; + }; +}; diff --git a/roms/u-boot/doc/device-tree-bindings/cpu/nios2.txt b/roms/u-boot/doc/device-tree-bindings/cpu/nios2.txt new file mode 100644 index 000000000..0ed2f44bc --- /dev/null +++ b/roms/u-boot/doc/device-tree-bindings/cpu/nios2.txt @@ -0,0 +1,54 @@ +* Nios II Processor Binding + +This binding specifies what properties available in the device tree +representation of a Nios II Processor Core. + +Users can use sopc2dts tool for generating device tree sources (dts) from a +Qsys system. See more detail in: http://www.alterawiki.com/wiki/Sopc2dts + +Required properties: + +- compatible: Compatible property value should be "altr,nios2-1.0" or + "altr,nios2-1.1". +- reg: Contains CPU index. +- clock-frequency: Contains the clock frequency for CPU, in Hz. +- dcache-line-size: Contains data cache line size. +- icache-line-size: Contains instruction line size. +- dcache-size: Contains data cache size. +- icache-size: Contains instruction cache size. +- altr,reset-addr: Specifies CPU reset address +- altr,exception-addr: Specifies CPU exception address + +Optional properties: +- altr,has-initda: Specifies CPU support initda instruction, should be 1. +- altr,has-mmu: Specifies CPU support MMU support. +- altr,has-mul: Specifies CPU hardware multipy support. +- altr,has-div: Specifies CPU hardware divide support +- altr,implementation: Nios II core implementation, this should be "fast"; + +Example: + +cpu@0x0 { + device_type = "cpu"; + compatible = "altr,nios2-1.0"; + reg = <0>; + interrupt-controller; + #interrupt-cells = <1>; + clock-frequency = <125000000>; + dcache-line-size = <32>; + icache-line-size = <32>; + dcache-size = <32768>; + icache-size = <32768>; + altr,implementation = "fast"; + altr,pid-num-bits = <8>; + altr,tlb-num-ways = <16>; + altr,tlb-num-entries = <128>; + altr,tlb-ptr-sz = <7>; + altr,has-div = <1>; + altr,has-mul = <1>; + altr,reset-addr = <0xc2800000>; + altr,fast-tlb-miss-addr = <0xc7fff400>; + altr,exception-addr = <0xd0000020>; + altr,has-initda = <1>; + altr,has-mmu = <1>; +}; diff --git a/roms/u-boot/doc/device-tree-bindings/device.txt b/roms/u-boot/doc/device-tree-bindings/device.txt new file mode 100644 index 000000000..73ce2a3b5 --- /dev/null +++ b/roms/u-boot/doc/device-tree-bindings/device.txt @@ -0,0 +1,75 @@ +Devices +======= + +Device bindings are described by their own individual binding files. + +U-Boot provides for some optional properties which are documented here. See +also hid-over-i2c.txt which describes HID devices. See also +Documentation/firmware-guide/acpi/enumeration.rst in the Linux kernel for +the acpi,compatible property. + + - acpi,has-power-resource : (boolean) true if this device has a power resource. + This causes an ACPI PowerResource to be written containing the properties + provided by this binding, to describe how to handle powering the device up + and down using GPIOs + - acpi,compatible : compatible string to report + - acpi,ddn : Contains the string to use as the _DDN (DOS (Disk Operating + System) Device Name) + - acpi,hid : Contains the string to use as the HID (Hardware ID) + identifier _HID + - acpi,path : Specifies the full ACPI path for a device. This overrides the + normal path built from the driver-model hierarchy + - acpi,name : Provides the ACPI name for a device, which is a string consisting + of four alphanumeric character (upper case) + - acpi,uid : _UID value for device + - acpi,wake : Provides the GPE used to detect a request from a device to wake + from sleep + - linux,probed : Tells U-Boot to add 'linux,probed' to the ACPI tables so that + Linux will only load the driver if the device can be detected (e.g. on I2C + bus). Note that this is an out-of-tree Linux feature. + + +Example +------- + +elan_touchscreen: elan-touchscreen@10 { + compatible = "i2c-chip"; + reg = <0x10>; + acpi,hid = "ELAN0001"; + acpi,ddn = "ELAN Touchscreen"; + interrupts-extended = <&acpi_gpe GPIO_21_IRQ IRQ_TYPE_EDGE_FALLING>; + linux,probed; +}; + +pcie-a0@14,0 { + reg = <0x0000a000 0 0 0 0>; + acpi,name = "RP01"; + wifi: wifi { + compatible = "intel,generic-wifi"; + acpi,ddn = "Intel WiFi"; + acpi,name = "WF00"; + acpi,wake = <GPE0_DW3_00>; + interrupts-extended = <&acpi_gpe 0x3c 0>; + }; +}; + +p2sb: p2sb@d,0 { + u-boot,dm-pre-reloc; + reg = <0x02006810 0 0 0 0>; + compatible = "intel,apl-p2sb"; + early-regs = <IOMAP_P2SB_BAR 0x100000>; + pci,no-autoconfig; + + n { + compatible = "intel,apl-pinctrl"; + u-boot,dm-pre-reloc; + intel,p2sb-port-id = <PID_GPIO_N>; + acpi,path = "\\_SB.GPO0"; + gpio_n: gpio-n { + compatible = "intel,gpio"; + u-boot,dm-pre-reloc; + gpio-controller; + #gpio-cells = <2>; + linux-name = "INT3452:00"; + }; + }; diff --git a/roms/u-boot/doc/device-tree-bindings/exynos/dwmmc.txt b/roms/u-boot/doc/device-tree-bindings/exynos/dwmmc.txt new file mode 100644 index 000000000..694d19591 --- /dev/null +++ b/roms/u-boot/doc/device-tree-bindings/exynos/dwmmc.txt @@ -0,0 +1,54 @@ +* Exynos DWC_mobile_storage + +The Exynos provides DWC_mobile_storage interface which supports +. Embedded Multimedia Cards (EMMC-version 4.5) +. Secure Digital memory (SD mem-version 2.0) +. Secure Digital I/O (SDIO-version 3.0) +. Consumer Electronics Advanced Transport Architecture (CE-ATA-version 1.1) + +The Exynos DWC_mobile_storage provides four channels. +SOC specific and Board specific properties are channel specific. + +Required SoC Specific Properties: + +- compatible: should be + - samsung,exynos-dwmmc: for exynos platforms + +- reg: physical base address of the controller and length of memory mapped + region. + +- interrupts: The interrupt number to the cpu. + +Required Board Specific Properties: + +- #address-cells: should be 1. +- #size-cells: should be 0. +- samsung,bus-width: The width of the bus used to interface the devices + supported by DWC_mobile_storage (SD-MMC/EMMC/SDIO). + . Typically the bus width is 4 or 8. +- samsung,timing: The timing values to be written into the + Drv/sample clock selection register of corresponding channel. + . It is comprised of 3 values corresponding to the 3 fileds + 'SelClk_sample', 'SelClk_drv' and 'DIVRATIO' of CLKSEL register. + . SelClk_sample: Select sample clock among 8 shifted clocks. + . SelClk_drv: Select drv clock among 8 shifted clocks. + . DIVRATIO: Clock Divide ratio select. + . The above 3 values are used by the clock phase shifter. + +Example: + +mmc@12200000 { + samsung,bus-width = <8>; + samsung,timing = <1 3 3>; + samsung,removable = <1>; +} +In the above example, + . The bus width is 8 + . Timing is comprised of 3 values as explained below + 1 - SelClk_sample + 3 - SelClk_drv + 3 - DIVRATIO + . The 'removable' flag indicates whether the the particilar device + cannot be removed (always present) or it is a removable device. + 1 - Indicates that the device is removable. + 0 - Indicates that the device cannot be removed. diff --git a/roms/u-boot/doc/device-tree-bindings/exynos/emmc-reset.txt b/roms/u-boot/doc/device-tree-bindings/exynos/emmc-reset.txt new file mode 100644 index 000000000..5e7ba26c2 --- /dev/null +++ b/roms/u-boot/doc/device-tree-bindings/exynos/emmc-reset.txt @@ -0,0 +1,15 @@ +* Samsung eMMC reset + +Some exynos boards require special handling of nRESET_OUT line for eMMC memory +to perform complete reboot. + +Required properties: +- compatible: should be "samsung,emmc-reset" +- reset-gpio: gpio chip for eMMC reset. + +Example: + +emmc-reset { + compatible = "samsung,emmc-reset"; + reset-gpio = <&gpk1 2 0>; +}; diff --git a/roms/u-boot/doc/device-tree-bindings/exynos/isp-spi.txt b/roms/u-boot/doc/device-tree-bindings/exynos/isp-spi.txt new file mode 100644 index 000000000..b8086e82b --- /dev/null +++ b/roms/u-boot/doc/device-tree-bindings/exynos/isp-spi.txt @@ -0,0 +1,22 @@ +Exynos ISP SPI Subsystem + +The device node for ISP SPI subsytem. +Since Peripheral id in EXYNOS is decoded based on Interrupts, currently +ISP SPI have no individual interrupts hence we add ad dummy interrupt node +which will have a value beyond the maximum number of interrupts exynos5 can +support. + +Required properties : + - compatible : Should be "samsung,exynos-spi" for spi. + - reg : Base adrress of the the subsystem. + - interrupts : A value which is beyond the maximum number of interrupts +exynos5 can support. + +Example: +spi@131a0000 { + #address-cells = <1>; + #size-cells = <0>; + compatible = "samsung,exynos-spi"; + reg = <0x131a0000 0x30>; + interrupts = <0 129 0>; +}; diff --git a/roms/u-boot/doc/device-tree-bindings/exynos/soc.txt b/roms/u-boot/doc/device-tree-bindings/exynos/soc.txt new file mode 100644 index 000000000..9ba6f3b9f --- /dev/null +++ b/roms/u-boot/doc/device-tree-bindings/exynos/soc.txt @@ -0,0 +1,21 @@ +Exynos SoC model + +The "cpu-model" property is a non-standard extension for the device tree root +node. Since the cpu id of some Exynos variants does not correspond to product +name, this property fills the gap. + +For almost all Exynos based boards in the kernel, the product name corresponds +to the device tree file name. The same name is generated in U-Boot, so the new +property allows doing it automatically. + +Required properties: + - cpu-model : Exynos product name + +Example: + +/ { + model = "Samsung/Google Peach Pi board based on Exynos5800"; + cpu-model = "Exynos5800"; + + compatible = ... +}; diff --git a/roms/u-boot/doc/device-tree-bindings/exynos/sound.txt b/roms/u-boot/doc/device-tree-bindings/exynos/sound.txt new file mode 100644 index 000000000..98d1798d0 --- /dev/null +++ b/roms/u-boot/doc/device-tree-bindings/exynos/sound.txt @@ -0,0 +1,27 @@ +Exynos Sound Subsystem + +The device node for sound subsytem which contains codec and i2s block +that is a part of Exynos5250 + +Required properties : + - compatible : Should be "samsung,exynos-sound" for sound + - samsung,i2s-epll-clock-frequency : epll clock output frequency in Hz + - samsung,i2s-sampling-rate : sampling rate, default is 48000 + - samsung,i2s-bits-per-sample : sample width, defalut is 16 bit + - samsung,i2s-channels : nummber of channels, default is 2 + - samsung,i2s-lr-clk-framesize : lr clock frame size + - samsung,i2s-bit-clk-framesize : bit clock frame size + - samsung,codec-type : sound codec type + +Example: + +sound@12d60000 { + compatible = "samsung,exynos-sound" + samsung,i2s-epll-clock-frequency = <192000000>; + samsung,i2s-sampling-rate = <48000>; + samsung,i2s-bits-per-sample = <16>; + samsung,i2s-channels = <2>; + samsung,i2s-lr-clk-framesize = <256>; + samsung,i2s-bit-clk-framesize = <32>; + samsung,codec-type = "wm8994"; +}; diff --git a/roms/u-boot/doc/device-tree-bindings/exynos/tmu.txt b/roms/u-boot/doc/device-tree-bindings/exynos/tmu.txt new file mode 100644 index 000000000..89d3bf05f --- /dev/null +++ b/roms/u-boot/doc/device-tree-bindings/exynos/tmu.txt @@ -0,0 +1,44 @@ +Exynos Thermal management Unit + +Required properties: + + - compatible : Should be "samsung,exynos-tmu" for TMU + - samsung,min-temp : Minimum temperature value (25 degree celsius) + - Current temperature of SoC should be more than this value. + - samsung,max-temp : Maximum temperature value (125 degree celsius) + - Current temperature of SoC should be less than this value. + - samsung,start-warning : Temperature at which TMU starts giving warning (degree celsius) + - samsung,start-tripping : Temperature at which TMU shuts down the system (degree celsius) + - samsung,hw-tripping : Temperature at which hardware tripping should happen + in case TMU fails to power off (degree celsius) + - samsung,efuse-min-value : SOC efuse min value (Constant 40) + - efuse-value should be more than this value. + - samsung,efuse-value : SOC actual efuse value (Literal value) + - This is the data trimming info. + - This value is used to calculate measuring error. + - samsung,efuse-max-value : SoC max efuse value (Constant 100) + - efuse-value should be less than this value. + - samsung,slope : Default value 274761730 (Constant 0x1060_8802). + - This is the default value for TMU_CONTROL register. + - It sets the gain of amplifier to the positive-tc generator block. + - It selects thermal tripping mode and enables thermal tripping. + - samsung,dc-value : Measured data calibration value (Constant 25) + - Used for tempearture calculation. + - This is 25 because temperature measured is always above 25 degrees. + + +Example: + +tmu@10060000 { + compatible = "samsung,exynos-tmu" + samsung,min-temp = <25>; + samsung,max-temp = <125>; + samsung,start-warning = <95>; + samsung,start-tripping = <105>; + samsung,hw-tripping = <110>; + samsung,efuse-min-value = <40>; + samsung,efuse-value = <55>; + samsung,efuse-max-value = <100>; + samsung,slope = <274761730>; + samsung,dc-value = <25>; +}; diff --git a/roms/u-boot/doc/device-tree-bindings/firmware/linaro,optee-tz.txt b/roms/u-boot/doc/device-tree-bindings/firmware/linaro,optee-tz.txt new file mode 100644 index 000000000..d38834c67 --- /dev/null +++ b/roms/u-boot/doc/device-tree-bindings/firmware/linaro,optee-tz.txt @@ -0,0 +1,31 @@ +OP-TEE Device Tree Bindings + +OP-TEE is a piece of software using hardware features to provide a Trusted +Execution Environment. The security can be provided with ARM TrustZone, but +also by virtualization or a separate chip. + +We're using "linaro" as the first part of the compatible property for +the reference implementation maintained by Linaro. + +* OP-TEE based on ARM TrustZone required properties: + +- compatible : should contain "linaro,optee-tz" + +- method : The method of calling the OP-TEE Trusted OS. Permitted + values are: + + "smc" : SMC #0, with the register assignments specified + in drivers/tee/optee/optee_smc.h + + "hvc" : HVC #0, with the register assignments specified + in drivers/tee/optee/optee_smc.h + + + +Example: + firmware { + optee { + compatible = "linaro,optee-tz"; + method = "smc"; + }; + }; diff --git a/roms/u-boot/doc/device-tree-bindings/firmware/nvidia,tegra186-bpmp.txt b/roms/u-boot/doc/device-tree-bindings/firmware/nvidia,tegra186-bpmp.txt new file mode 100644 index 000000000..447252e88 --- /dev/null +++ b/roms/u-boot/doc/device-tree-bindings/firmware/nvidia,tegra186-bpmp.txt @@ -0,0 +1,104 @@ +NVIDIA Tegra Boot and Power Management Processor (BPMP) + +The BPMP is a specific processor in Tegra chip, which is designed for +booting process handling and offloading the power management, clock +management, and reset control tasks from the CPU. The binding document +defines the resources that would be used by the BPMP firmware driver, +which can create the interprocessor communication (IPC) between the CPU +and BPMP. + +Required properties: +- name : Should be bpmp +- compatible + Array of strings + One of: + - "nvidia,tegra186-bpmp" +- mboxes : The phandle of mailbox controller and the mailbox specifier. +- shmem : List of the phandle of the TX and RX shared memory area that + the IPC between CPU and BPMP is based on. +- #clock-cells : Should be 1. +- #power-domain-cells : Should be 1. +- #reset-cells : Should be 1. + +This node is a mailbox consumer. See the following files for details of +the mailbox subsystem, and the specifiers implemented by the relevant +provider(s): + +- .../mailbox/mailbox.txt +- .../mailbox/nvidia,tegra186-hsp.txt + +This node is a clock, power domain, and reset provider. See the following +files for general documentation of those features, and the specifiers +implemented by this node: + +- .../clock/clock-bindings.txt +- <dt-bindings/clock/tegra186-clock.h> +- ../power/power_domain.txt +- <dt-bindings/power/tegra186-powergate.h> +- .../reset/reset.txt +- <dt-bindings/reset/tegra186-reset.h> + +The BPMP implements some services which must be represented by separate nodes. +For example, it can provide access to certain I2C controllers, and the I2C +bindings represent each I2C controller as a device tree node. Such nodes should +be nested directly inside the main BPMP node. + +Software can determine whether a child node of the BPMP node represents a device +by checking for a compatible property. Any node with a compatible property +represents a device that can be instantiated. Nodes without a compatible +property may be used to provide configuration information regarding the BPMP +itself, although no such configuration nodes are currently defined by this +binding. + +The BPMP firmware defines no single global name-/numbering-space for such +services. Put another way, the numbering scheme for I2C buses is distinct from +the numbering scheme for any other service the BPMP may provide (e.g. a future +hypothetical SPI bus service). As such, child device nodes will have no reg +property, and the BPMP node will have no #address-cells or #size-cells property. + +The shared memory bindings for BPMP +----------------------------------- + +The shared memory area for the IPC TX and RX between CPU and BPMP are +predefined and work on top of sysram, which is an SRAM inside the chip. + +See ".../sram/sram.txt" for the bindings. + +Example: + +hsp_top0: hsp@03c00000 { + ... + #mbox-cells = <2>; +}; + +sysram@30000000 { + compatible = "nvidia,tegra186-sysram", "mmio-sram"; + reg = <0x0 0x30000000 0x0 0x50000>; + #address-cells = <2>; + #size-cells = <2>; + ranges = <0 0x0 0x0 0x30000000 0x0 0x50000>; + + cpu_bpmp_tx: bpmp_shmem@4e000 { + compatible = "nvidia,tegra186-bpmp-shmem"; + reg = <0x0 0x4e000 0x0 0x1000>; + }; + + cpu_bpmp_rx: bpmp_shmem@4f000 { + compatible = "nvidia,tegra186-bpmp-shmem"; + reg = <0x0 0x4f000 0x0 0x1000>; + }; +}; + +bpmp { + compatible = "nvidia,tegra186-bpmp"; + mboxes = <&hsp_top0 HSP_MBOX_TYPE_DB HSP_DB_MASTER_BPMP>; + shmem = <&cpu_bpmp_tx &cpu_bpmp_rx>; + #clock-cells = <1>; + #power-domain-cells = <1>; + #reset-cells = <1>; + + i2c { + compatible = "..."; + ... + }; +}; diff --git a/roms/u-boot/doc/device-tree-bindings/firmware/ti,sci.txt b/roms/u-boot/doc/device-tree-bindings/firmware/ti,sci.txt new file mode 100644 index 000000000..4d40d0dcb --- /dev/null +++ b/roms/u-boot/doc/device-tree-bindings/firmware/ti,sci.txt @@ -0,0 +1,76 @@ +Texas Instruments System Control Interface (TI-SCI) Message Protocol +-------------------------------------------------------------------- + +Texas Instrument's processors including those belonging to Keystone generation +of processors have separate hardware entity which is now responsible for the +management of the System on Chip (SoC) system. These include various system +level functions as well. + +An example of such an SoC is K2G, which contains the system control hardware +block called Power Management Micro Controller (PMMC). This hardware block is +initialized early into boot process and provides services to Operating Systems +on multiple processors including ones running Linux. + +See http://processors.wiki.ti.com/index.php/TISCI for protocol definition. + +TI-SCI controller Device Node: +============================= + +The TI-SCI node describes the Texas Instrument's System Controller entity node. +This parent node may optionally have additional children nodes which describe +specific functionality such as clocks, power domain, reset or additional +functionality as may be required for the SoC. This hierarchy also describes the +relationship between the TI-SCI parent node to the child node. + +Required properties: +------------------- +- compatible: should be "ti,k2g-sci" +- mbox-names: + "rx" - Mailbox corresponding to receive path + "tx" - Mailbox corresponding to transmit path + +- mboxes: Mailboxes corresponding to the mbox-names. Each value of the mboxes + property should contain a phandle to the mailbox controller device + node and an args specifier that will be the phandle to the intended + sub-mailbox child node to be used for communication. + +Optional Properties: +------------------- +- reg-names: + debug_messages - Map the Debug message region +- reg: register space corresponding to the debug_messages +- ti,system-reboot-controller: If system reboot can be triggered by SoC reboot +- ti,secure-host: If the host is defined as secure. + +Example: +------------- + dmsc: dmsc { + compatible = "ti,k2g-sci"; + ti,host-id = <12>; + #address-cells = <1>; + #size-cells = <1>; + ranges; + } + + +TI-SCI Client Device Node: +========================= + +Client nodes are maintained as children of the relevant TI-SCI device node. + +Example: +------------- + dmsc: dmsc { + compatible = "ti,k2g-sci"; + ... + + my_clk_node: clk_node { + ... + ... + }; + + my_pd_node: pd_node { + ... + ... + }; + }; diff --git a/roms/u-boot/doc/device-tree-bindings/fpga/altera-socfpga-a10-fpga-mgr.txt b/roms/u-boot/doc/device-tree-bindings/fpga/altera-socfpga-a10-fpga-mgr.txt new file mode 100644 index 000000000..da210bfc8 --- /dev/null +++ b/roms/u-boot/doc/device-tree-bindings/fpga/altera-socfpga-a10-fpga-mgr.txt @@ -0,0 +1,43 @@ +Altera SOCFPGA Arria10 FPGA Manager + +Required properties: +- compatible : should contain "altr,socfpga-a10-fpga-mgr" +- reg : base address and size for memory mapped io. + - The first index is for FPGA manager register access. + - The second index is for writing FPGA configuration data. +- resets : Phandle and reset specifier for the device's reset. +- clocks : Clocks used by the device. +- altr,bitstream : Fit image file name for both FPGA peripheral bitstream, + FPGA core bitstream and full bitstream. + + Full bitstream, consist of peripheral bitstream and core + bitstream. + + FPGA peripheral bitstream is used to initialize FPGA IOs, + PLL, IO48 and DDR. This bitstream is required to get DDR up + running. + + FPGA core bitstream contains FPGA design which is used to + program FPGA CRAM and ERAM. + +Example: Bundles both peripheral bitstream and core bitstream into FIT image + called fit_spl_fpga.itb. This FIT image can be created through running + this command: tools/mkimage + -E -p 400 + -f board/altera/arria10-socdk/fit_spl_fpga.its + fit_spl_fpga.itb + + For details of describing structure and contents of the FIT image, + please refer board/altera/arria10-socdk/fit_spl_fpga.its + +- Examples for booting with full release or booting with early IO release, then + follow by entering early user mode: + + fpga_mgr: fpga-mgr@ffd03000 { + compatible = "altr,socfpga-a10-fpga-mgr"; + reg = <0xffd03000 0x100 + 0xffcfe400 0x20>; + clocks = <&l4_mp_clk>; + resets = <&rst FPGAMGR_RESET>; + altr,bitstream = "fit_spl_fpga.itb"; + }; diff --git a/roms/u-boot/doc/device-tree-bindings/fsp/fsp2/apollolake/fsp-m.txt b/roms/u-boot/doc/device-tree-bindings/fsp/fsp2/apollolake/fsp-m.txt new file mode 100644 index 000000000..36936f2eb --- /dev/null +++ b/roms/u-boot/doc/device-tree-bindings/fsp/fsp2/apollolake/fsp-m.txt @@ -0,0 +1,327 @@ +* Intel FSP-M configuration + +Several Intel platforms require the execution of the Intel FSP (Firmware +Support Package) for initialization. The FSP consists of multiple parts, one +of which is the FSP-M (Memory initialization phase). + +This binding applies to the FSP-M for the Intel Apollo Lake SoC. + +The FSP-M is available on Github [1]. +For detailed information on the FSP-M parameters see the documentation in +FSP/ApolloLakeFspBinPkg/Docs [2]. + +The properties of this binding are all optional. If no properties are set the +values of the FSP-M are used. + +[1] https://github.com/IntelFsp/FSP +[2] https://github.com/IntelFsp/FSP/tree/master/ApolloLakeFspBinPkg/Docs + +Optional properties: +- fspm,training-delay: Time taken to train DDR memory if there is no cached MRC + data, in seconds. This is used to show a message if possible. For Chromebook + Coral this is typically 21 seconds. For an APL board with 1GB of RAM, it may + be only 6 seconds. +- fspm,serial-debug-port-address: Debug Serial Port Base address +- fspm,serial-debug-port-type: Debug Serial Port Type + 0: NONE + 1: I/O + 2: MMIO (default) +- fspm,serial-debug-port-device: Serial Port Debug Device + 0: SOC UART0 + 1: SOC UART1 + 2: SOC UART2 (default) + 3: External Device +- fspm,serial-debug-port-stride-size: Debug Serial Port Stride Size + 0: 1 + 2: 4 (default) +- fspm,mrc-fast-boot: Memory Fast Boot +- fspm,igd: Integrated Graphics Device +- fspm,igd-dvmt50-pre-alloc: DVMT Pre-Allocated + 0x02: 64 MB (default) + 0x03: 96 MB + 0x04: 128 MB + 0x05: 160 MB + 0x06: 192 MB + 0x07: 224 MB + 0x08: 256 MB + 0x09: 288 MB + 0x0A: 320 MB + 0x0B: 352 MB + 0x0C: 384 MB + 0x0D: 416 MB + 0x0E: 448 MB + 0x0F: 480 MB + 0x10: 512 MB +- fspm,aperture-size: Aperture Size + 0x1: 128 MB (default) + 0x2: 256 MB + 0x3: 512 MB +- fspm,gtt-size: GTT Size + 0x1: 2 MB + 0x2: 4 MB + 0x3: 8 MB (default) +- fspm,primary-video-adaptor: Primary Display + 0x0: AUTO (default) + 0x2: IGD + 0x3: PCI +- fspm,package: Package + 0x0: SODIMM (default) + 0x1: BGA + 0x2: BGA mirrored (LPDDR3 only) + 0x3: SODIMM/UDIMM with Rank 1 Mirrored (DDR3L) +- fspm,profile: Profile + 0x01: WIO2_800_7_8_8 + 0x02: WIO2_1066_9_10_10 + 0x03: LPDDR3_1066_8_10_10 + 0x04: LPDDR3_1333_10_12_12 + 0x05: LPDDR3_1600_12_15_15 + 0x06: LPDDR3_1866_14_17_17 + 0x07: LPDDR3_2133_16_20_20 + 0x08: LPDDR4_1066_10_10_10 + 0x09: LPDDR4_1600_14_15_15 + 0x0A: LPDDR4_2133_20_20_20 + 0x0B: LPDDR4_2400_24_22_22 + 0x0C: LPDDR4_2666_24_24_24 + 0x0D: LPDDR4_2933_28_27_27 + 0x0E: LPDDR4_3200_28_29_29 + 0x0F: DDR3_1066_6_6_6 + 0x10: DDR3_1066_7_7_7 + 0x11: DDR3_1066_8_8_8 + 0x12: DDR3_1333_7_7_7 + 0x13: DDR3_1333_8_8_8 + 0x14: DDR3_1333_9_9_9 + 0x15: DDR3_1333_10_10_10 + 0x16: DDR3_1600_8_8_8 + 0x17: DDR3_1600_9_9_9 + 0x18: DDR3_1600_10_10_10 + 0x19: DDR3_1600_11_11_11 (default) + 0x1A: DDR3_1866_10_10_10 + 0x1B: DDR3_1866_11_11_11 + 0x1C: DDR3_1866_12_12_12 + 0x1D: DDR3_1866_13_13_13 + 0x1E: DDR3_2133_11_11_11 + 0x1F: DDR3_2133_12_12_12 + 0x20: DDR3_2133_13_13_13 + 0x21: DDR3_2133_14_14_14 + 0x22: DDR4_1333_10_10_10 + 0x23: DDR4_1600_10_10_10 + 0x24: DDR4_1600_11_11_11 + 0x25: DDR4_1600_12_12_12 + 0x26: DDR4_1866_12_12_12 + 0x27: DDR4_1866_13_13_13 + 0x28: DDR4_1866_14_14_14 + 0x29: DDR4_2133_14_14_14 + 0x2A: DDR4_2133_15_15_15 + 0x2B: DDR4_2133_16_16_16 + 0x2C: DDR4_2400_15_15_15 + 0x2D: DDR4_2400_16_16_16 + 0x2E: DDR4_2400_17_17_17 + 0x2F: DDR4_2400_18_18_18 +- fspm,memory-down: Memory Down + 0x0: No (default) + 0x1: Yes + 0x2: 1MD+SODIMM (for DDR3L only) ACRD + 0x3: 1x32 LPDDR4 +- fspm,ddr3l-page-size: DDR3LPageSize + 0x1: 1KB (default) + 0x2: 2KB +- fspm,ddr3-lasr: DDR3LASR +- fspm,scrambler-support: ScramblerSupport +- fspm,interleaved-mode: InterleavedMode +- fspm,channel-hash-mask: ChannelHashMask +- fspm,fspm,slice-hash-mask: SliceHashMask +- fspm,channels-slices-enable: ChannelsSlices +- fspm,min-ref-rate2x-enable: MinRefRate2x +- fspm,dual-rank-support-enable: DualRankSupport +- fspm,rmt-mode: RmtMode +- fspm,memory-size-limit: MemorySizeLimit +- fspm,low-memory-max-value: LowMemoryMaxValue +- fspm,high-memory-max-value: HighMemoryMaxValue +- fspm,disable-fast-boot: FastBoot +- fspm,dimm0-spd-address: DIMM0 SPD Address +- fspm,dimm1-spd-address: DIMM1 SPD Address +- fspm,chX-rank-enable: Must be set to enable rank (X = 0-3) +- fspm,chX-device-width: DRAM device width per DRAM channel (X = 0-3) + 0: x8 + 1: x16 + 2: x32 + 3: x64 +- fspm,chX-dram-density: Must specify the DRAM device density (X = 0-3) + 0: 4Gb + 1: 6Gb + 2: 8Gb + 3: 12Gb + 4: 16Gb + 5: 2Gb +- fspm,chX-option: Channel options (X = 0-3) +- fspm,chX-odt-config: Channel Odt Config (X = 0-3) +- fspm,chX-mode2-n: Force 2N Mode (X = 0-3) + 0x0: Auto + 0x1: Force 2N CMD Timing Mode +- fspm,chX-odt-levels: Channel Odt Levels (X = 0-3) + 0: ODT Connected to SoC + 1: ODT held high +- fspm,rmt-check-run: RmtCheckRun +- fspm,rmt-margin-check-scale-high-threshold: RmtMarginCheckScaleHighThreshold +- fspm,ch-bit-swizzling: Bit_swizzling +- fspm,msg-level-mask: MsgLevelMask +- fspm,pre-mem-gpio-table-pin-num: PreMem GPIO Pin Number for each table +- fspm,pre-mem-gpio-table-ptr: PreMem GPIO Table Pointer +- fspm,pre-mem-gpio-table-entry-num: PreMem GPIO Table Entry Number +- fspm,enhance-port8xh-decoding: Enhance the port 8xh decoding +- fspm,spd-write-enable: SPD Data Write +- fspm,mrc-data-saving: MRC Training Data Saving +- fspm,oem-loading-base: OEM File Loading Address +- fspm,oem-file-name: OEM File Name to Load +- fspm,mrc-boot-data-ptr: +- fspm,emmc-trace-len: eMMC Trace Length + 0x0: Long + 0x1: Short +- fspm,skip-cse-rbp: Skip CSE RBP to support zero sized IBB +- fspm,npk-en: Npk Enable + 0: Disable + 1: Enable + 2: Debugger + 3: Auto (default) +- fspm,fw-trace-en: FW Trace Enable +- fspm,fw-trace-destination: FW Trace Destination + 1: NPK_TRACE_TO_MEMORY + 2: NPK_TRACE_TO_DCI + 3: NPK_TRACE_TO_BSSB + 4: NPK_TRACE_TO_PTI (default) +- fspm,recover-dump: NPK Recovery Dump +- fspm,msc0-wrap: Memory Region 0 Buffer WrapAround + 0: n0-warp + 1: n1-warp (default) +- fspm,msc1-wrap: Memory Region 1 Buffer WrapAround + 0: n0-warp + 1: n1-warp (default) +- fspm,msc0-size: Memory Region 0 Buffer Size + 0: 0MB (default) + 1: 1MB + 2: 8MB + 3: 64MB + 4: 128MB + 5: 256MB + 6: 512MB + 7: 1GB +- fspm,msc1-size: Memory Region 1 Buffer Size + 0: 0MB (default) + 1: 1MB + 2: 8MB + 3: 64MB + 4: 128MB + 5: 256MB + 6: 512MB + 7: 1GB +- fspm,pti-mode: PTI Mode + 0: 0ff + 1: x4 (default) + 2: x8 + 3: x12 + 4: x16 +- fspm,pti-training: PTI Training + 0: off (default) + 1-6: 1-6 +- fspm,pti-speed: + 0: full + 1: half + 2: quarter (default) +- fspm,punit-mlvl: Punit Message Level + 0: + 1: (default) + 2-4: 2-4 +- fspm,pmc-mlvl: PMC Message Level + 0: + 1: (default) + 2-4: 2-4 +- fspm,sw-trace-en: SW Trace Enable +- fspm,periodic-retraining-disable: Periodic Retraining Disable +- fspm,enable-reset-system: Enable Reset System +- fspm,enable-s3-heci2: Enable HECI2 in S3 resume path +- fspm,variable-nvs-buffer-ptr: +- fspm,start-timer-ticker-of-pfet-assert: PCIE SLOT Power Enable Assert Time - PFET +- fspm,rt-en: Real Time Enabling +- fspm,skip-pcie-power-sequence: Skip Pcie Power Sequence + +Example: + +&host_bridge { + fspm,package = <PACKAGE_BGA>; + fspm,profile = <PROFILE_LPDDR4_2400_24_22_22>; + fspm,memory-down = <MEMORY_DOWN_YES>; + fspm,scrambler-support = <1>; + fspm,interleaved-mode = <INTERLEAVED_MODE_ENABLE>; + fspm,channel-hash-mask = <0x36>; + fspm,slice-hash-mask = <0x9>; + fspm,low-memory-max-value = <2048>; + fspm,ch0-rank-enable = <1>; + fspm,ch0-device-width = <CHX_DEVICE_WIDTH_X16>; + fspm,ch0-dram-density = <CHX_DEVICE_DENSITY_8GB>; + fspm,ch0-option = <(CHX_OPTION_RANK_INTERLEAVING | + CHX_OPTION_BANK_ADDRESS_HASHING_ENABLE)>; + fspm,ch0-odt-config = <CHX_ODT_CONFIG_DDR4_CA_ODT>; + fspm,ch1-rank-enable = <1>; + fspm,ch1-device-width = <CHX_DEVICE_WIDTH_X16>; + fspm,ch1-dram-density = <CHX_DEVICE_DENSITY_8GB>; + fspm,ch1-option = <(CHX_OPTION_RANK_INTERLEAVING | + CHX_OPTION_BANK_ADDRESS_HASHING_ENABLE)>; + fspm,ch1-odt-config = <CHX_ODT_CONFIG_DDR4_CA_ODT>; + fspm,ch2-rank-enable = <1>; + fspm,ch2-device-width = <CHX_DEVICE_WIDTH_X16>; + fspm,ch2-dram-density = <CHX_DEVICE_DENSITY_8GB>; + fspm,ch2-option = <(CHX_OPTION_RANK_INTERLEAVING | + CHX_OPTION_BANK_ADDRESS_HASHING_ENABLE)>; + fspm,ch2-odt-config = <CHX_ODT_CONFIG_DDR4_CA_ODT>; + fspm,ch3-rank-enable = <1>; + fspm,ch3-device-width = <CHX_DEVICE_WIDTH_X16>; + fspm,ch3-dram-density = <CHX_DEVICE_DENSITY_8GB>; + fspm,ch3-option = <(CHX_OPTION_RANK_INTERLEAVING | + CHX_OPTION_BANK_ADDRESS_HASHING_ENABLE)>; + fspm,ch3-odt-config = <CHX_ODT_CONFIG_DDR4_CA_ODT>; + fspm,fspm,skip-cse-rbp = <1>; + + fspm,ch-bit-swizzling = /bits/ 8 < + /* LP4_PHYS_CH0A */ + + /* DQA[0:7] pins of LPDDR4 module */ + 6 7 5 4 3 1 0 2 + /* DQA[8:15] pins of LPDDR4 module */ + 12 10 11 13 14 8 9 15 + /* DQB[0:7] pins of LPDDR4 module with offset of 16 */ + 16 22 23 20 18 17 19 21 + /* DQB[7:15] pins of LPDDR4 module with offset of 16 */ + 30 28 29 25 24 26 27 31 + + /* LP4_PHYS_CH0B */ + /* DQA[0:7] pins of LPDDR4 module */ + 7 3 5 2 6 0 1 4 + /* DQA[8:15] pins of LPDDR4 module */ + 9 14 12 13 10 11 8 15 + /* DQB[0:7] pins of LPDDR4 module with offset of 16 */ + 20 22 23 16 19 17 18 21 + /* DQB[7:15] pins of LPDDR4 module with offset of 16 */ + 28 24 26 27 29 30 31 25 + + /* LP4_PHYS_CH1A */ + + /* DQA[0:7] pins of LPDDR4 module */ + 2 1 6 7 5 4 3 0 + /* DQA[8:15] pins of LPDDR4 module */ + 11 10 8 9 12 15 13 14 + /* DQB[0:7] pins of LPDDR4 module with offset of 16 */ + 17 23 19 16 21 22 20 18 + /* DQB[7:15] pins of LPDDR4 module with offset of 16 */ + 31 29 26 25 28 27 24 30 + + /* LP4_PHYS_CH1B */ + + /* DQA[0:7] pins of LPDDR4 module */ + 4 3 7 5 6 1 0 2 + /* DQA[8:15] pins of LPDDR4 module */ + 15 9 8 11 14 13 12 10 + /* DQB[0:7] pins of LPDDR4 module with offset of 16 */ + 20 23 22 21 18 19 16 17 + /* DQB[7:15] pins of LPDDR4 module with offset of 16 */ + 25 28 30 31 26 27 24 29>; +}; diff --git a/roms/u-boot/doc/device-tree-bindings/fsp/fsp2/apollolake/fsp-s.txt b/roms/u-boot/doc/device-tree-bindings/fsp/fsp2/apollolake/fsp-s.txt new file mode 100644 index 000000000..dc8e3251a --- /dev/null +++ b/roms/u-boot/doc/device-tree-bindings/fsp/fsp2/apollolake/fsp-s.txt @@ -0,0 +1,490 @@ +* Intel FSP-S configuration + +Several Intel platforms require the execution of the Intel FSP (Firmware +Support Package) for initialization. The FSP consists of multiple parts, one +of which is the FSP-S (Silicon initialization phase). + +This binding applies to the FSP-S for the Intel Apollo Lake SoC. + +The FSP-S is available on Github [1]. +For detailed information on the FSP-S parameters see the documentation in +FSP/ApolloLakeFspBinPkg/Docs [2]. + +The properties of this binding are all optional. If no properties are set the +values of the FSP-S are used. + +[1] https://github.com/IntelFsp/FSP +[2] https://github.com/IntelFsp/FSP/tree/master/ApolloLakeFspBinPkg/Docs + +Optional properties: +- fsps,active-processor-cores: ActiveProcessorCores +- fsps,disable-core1: Disable Core1 +- fsps,disable-core2: Disable Core2 +- fsps,disable-core2: Disable Core3 +- fsps,vmx-enable: VMX Enable +- fsps,proc-trace-mem-size: Memory region allocation for Processor Trace + 0xFF: Disable (default) +- fsps,proc-trace-enable: Enable Processor Trace +- fsps,eist: Eist +- fsps,boot-p-state: Boot PState + 0: HFM (default) + 1: LFM +- fsps,enable-cx: CPU power states (C-states) +- fsps,c1e: Enhanced C-states +- fsps,bi-proc-hot: Bi-Directional PROCHOT# +- fsps,pkg-c-state-limit: Max Pkg Cstate + 0: PkgC0C1 + 1: PkgC2 + 2: PkgC3 (default) + 3: PkgC6 + 4: PkgC7 + 5: PkgC7s + 6: PkgC8 + 7: PkgC9 + 8: PkgC10 + 9: PkgCMax + 254: PkgCpuDefault + 255: PkgAuto +- fsps,c-state-auto-demotion: C-State auto-demotion + 0: Disable C1 and C3 Auto-demotion (default) + 1: Enable C3/C6/C7 Auto-demotion to C1 + 2: Enable C6/C7 Auto-demotion to C3 + 3: Enable C6/C7 Auto-demotion to C1 and C3 +- fsps,c-state-un-demotion: C-State un-demotion + 0: Disable C1 and C3 Un-demotion (default) + 1: Enable C1 Un-demotion + 2: Enable C3 Un-demotion + 3: Enable C1 and C3 Un-demotion +- fsps,max-core-c-state: Max Core C-State + 0: Unlimited + 1: C1 + 2: C3 + 3: C6 + 4: C7 + 5: C8 + 6: C9 + 7: C10 + 8: CCx (default) +- fsps,pkg-c-state-demotion: Package C-State Demotion +- fsps,pkg-c-state-un-demotion: Package C-State Un-demotion +- fsps,turbo-mode: Turbo Mode +- fsps,hda-verb-table-entry-num: SC HDA Verb Table Entry Number + 0: (default) +- fsps,hda-verb-table-ptr: SC HDA Verb Table Pointer + 0x00000000: (default) +- fsps,p2sb-unhide: Enable/Disable P2SB device hidden +- fsps,ipu-en: IPU Enable/Disable +- fsps,ipu-acpi-mode: IMGU ACPI mode selection + 0: Auto + 1: IGFX Child device (default) + 2: ACPI device +- fsps,force-wake: Enable ForceWake +- fsps,gtt-mm-adr: GttMmAdr + 0xbf000000: (default) +- fsps,gm-adr: GmAdr + 0xa0000000: (default) +- fsps,pavp-lock: Enable PavpLock +- fsps,graphics-freq-modify: Enable GraphicsFreqModify +- fsps,graphics-freq-req: Enable GraphicsFreqReq +- fsps,graphics-video-freq: Enable GraphicsVideoFreq +- fsps,pm-lock: Enable PmLock +- fsps,dop-clock-gating: Enable DopClockGating +- fsps,unsolicited-attack-override: Enable UnsolicitedAttackOverride +- fsps,wopcm-support: Enable WOPCMSupport +- fsps,wopcm-size: Enable WOPCMSize +- fsps,power-gating: Enable PowerGating +- fsps,unit-level-clock-gating: Enable UnitLevelClockGating +- fsps,fast-boot: Enable FastBoot +- fsps,dyn-sr: Enable DynSR +- fsps,sa-ipu-enable: Enable SaIpuEnable +- fsps,pm-support: GT PM Support +- fsps,enable-render-standby: RC6(Render Standby) +- fsps,logo-size: BMP Logo Data Size +- fsps,logo-ptr: BMP Logo Data Pointer +- fsps,graphics-config-ptr: Graphics Configuration Data Pointer +- fsps,pavp-enable: PAVP Enable +- fsps,pavp-pr3: PAVP PR3 +- fsps,cd-clock: CdClock Frequency selection + 0: 144MHz + 1: 288MHz + 2: 384MHz + 3: 576MHz + 4: 624MHz (default) +- fsps,pei-graphics-peim-init: Enable/Disable PeiGraphicsPeimInit +- fsps,write-protection-enable: Write Protection Support +- fsps,read-protection-enable: Read Protection Support +- fsps,protected-range-limit: Protected Range Limitation + 0x0FFF: (default) +- fsps,protected-range-base: Protected Range Base + 0x0000: (default) +- fsps,gmm: Enable SC Gaussian Mixture Models +- fsps,clk-gating-pgcb-clk-trunk: GMM Clock Gating - PGCB Clock Trunk +- fsps,clk-gating-sb: GMM Clock Gating - Sideband +- fsps,clk-gating-sb-clk-trunk: GMM Clock Gating - Sideband +- fsps,clk-gating-sb-clk-partition: GMM Clock Gating - Sideband Clock + Partition +- fsps,clk-gating-core: GMM Clock Gating - Core +- fsps,clk-gating-dma: GMM Clock Gating - DMA +- fsps,clk-gating-reg-access: GMM Clock Gating - Register Access +- fsps,clk-gating-host: GMM Clock Gating - Host +- fsps,clk-gating-partition: GMM Clock Gating - Partition +- fsps,clk-gating-trunk: Clock Gating - Trunk +- fsps,hda-enable: HD Audio Support +- fsps,dsp-enable: HD Audio DSP Support +- fsps,pme: Azalia wake-on-ring +- fsps,hd-audio-io-buffer-ownership: HD-Audio I/O Buffer Ownership + 0: HD-Audio link owns all the I/O buffers (default) + 1: HD-Audio link owns 4 I/O buffers and I2S port owns 4 I/O buffers + 3: I2S port owns all the I/O buffers +- fsps,hd-audio-io-buffer-voltage: HD-Audio I/O Buffer Voltage + 0: 3.3V (default) + 1: 1.8V +- fsps,hd-audio-vc-type: HD-Audio Virtual Channel Type + 0: VC0 (default) + 1: VC1 +- fsps,hd-audio-link-frequency: HD-Audio Link Frequency + 0: 6MHz (default) + 1: 12MHz + 2: 24MHz + 3: 48MHz + 4: 96MHz + 5: Invalid +- fsps,hd-audio-i-disp-link-frequency: HD-Audio iDisp-Link Frequency + 0: 6MHz (default) + 1: 12MHz + 2: 24MHz + 3: 48MHz + 4: 96MHz + 5: Invalid +- fsps,hd-audio-i-disp-link-tmode: HD-Audio iDisp-Link T-Mode + 0: 2T (default) + 1: 1T +- fsps,dsp-endpoint-dmic: HD-Audio Disp DMIC + 0: disable, + 1: 2ch array (default) + 2: 4ch array +- fsps,dsp-endpoint-bluetooth: HD-Audio Bluetooth +- fsps,dsp-endpoint-i2s-skp: HD-Audio I2S SHK +- fsps,dsp-endpoint-i2s-hp: HD-Audio I2S HP +- fsps,audio-ctl-pwr-gate: HD-Audio Controller Power Gating (deprecated) +- fsps,audio-dsp-pwr-gate: HD-Audio ADSP Power Gating (deprecated) +- fsps,mmt: HD-Audio CSME Memory Transfers + 0: VC0 (default) + 1: VC2 +- fsps,hmt: HD-Audio Host Memory Transfers + 0: VC0 (default) + 1: VC2 +- fsps,hd-audio-pwr-gate: HD-Audio Power Gating +- fsps,hd-audio-clk-gate: HD-Audio Clock Gating +- fsps,dsp-feature-mask: Bitmask of DSP Feature + 0x01: WoV + 0x02: BT Sideband + 0x04: Codec VAD + 0x20: BT Intel HFP + 0x40: BT Intel A2DP + 0x80: DSP based speech pre-processing disabled +- fsps,dsp-pp-module-mask: Bitmask of supported DSP Post-Processing Modules + 0x01: WoV + 0x02: BT Sideband + 0x04: Codec VAD + 0x20: BT Intel HFP + 0x40: BT Intel A2DP + 0x80: DSP based speech pre-processing disabled +- fsps,bios-cfg-lock-down: HD-Audio BIOS Configuration Lock Down +- fsps,hpet: Enable High Precision Timer +- fsps,hpet-bdf-valid: Hpet Valid BDF Value +- fsps,hpet-bus-number: Bus Number of Hpet + 0xFA: (default) +- fsps,hpet-device-number: Device Number of Hpet + 0x1F: (default) +- fsps,hpet-function-number: Function Number of Hpet + 0x00: (default) +- fsps,io-apic-bdf-valid: IoApic Valid BDF Value +- fsps,io-apic-bus-number: Bus Number of IoApic + 0xFA: (default) +- fsps,io-apic-device-number: Device Number of IoApic + 0x0F: (default) +- fsps,io-apic-function-number: Function Number of IoApic + 0x00: (default) +- fsps,io-apic-entry24-119: IOAPIC Entry 24-119 +- fsps,io-apic-id: IO APIC ID + 0x01: (default) +- fsps,io-apic-range-select: IoApic Range + 0x00: (default) +- fsps,ish-enable: ISH Controller +- fsps,bios-interface: BIOS Interface Lock Down +- fsps,bios-lock: Bios LockDown Enable +- fsps,spi-eiss: SPI EISS Status +- fsps,bios-lock-sw-smi-number: BiosLock SWSMI Number + 0xA9: (default) +- fsps,lpss-s0ix-enable: LPSS IOSF PMCTL S0ix Enable +- fsps,i2c-clk-gate-cfg: LPSS I2C Clock Gating Configuration +- fsps,hsuart-clk-gate-cfg: LPSS HSUART Clock Gating Configuration +- fsps,spi-clk-gate-cfg: LPSS SPI Clock Gating Configuration +- fsps,i2cX-enable: 2C Device X + 0: Disabled + 1: PCI Mode (default) + 2: ACPI Mode +- fsps,hsuartX-enable: UART Device X + 0: Disabled + 1: PCI Mode (default) + 2: ACPI Mode +- fsps,spiX-enable: SPI UART Device X + 0: Disabled + 1: PCI Mode (default) + 2: ACPI Mode +- fsps,os-dbg-enable: OS Debug Feature +- fsps,dci-en: DCI Feature +- fsps,uart2-kernel-debug-base-address: UART Debug Base Address + 0x00000000: (default) +- fsps,pcie-clock-gating-disabled: Enable PCIE Clock Gating +- fsps,pcie-root-port8xh-decode: Enable PCIE Root Port 8xh Decode +- fsps,pcie8xh-decode-port-index: PCIE 8xh Decode Port Index + 0x00: (default) +- fsps,pcie-root-port-peer-memory-write-enable: Enable PCIE Root Port Peer + Memory Write +- fsps,pcie-aspm-sw-smi-number: PCIE SWSMI Number + 0xAA: (default) +- fsps,pcie-root-port-en: PCI Express Root Port +- fsps,pcie-rp-hide: Hide PCIE Root Port Configuration Space +- fsps,pcie-rp-slot-implemented: PCIE Root Port Slot Implement +- fsps,pcie-rp-hot-plug: Hot Plug +- fsps,pcie-rp-pm-sci: PCIE PM SCI +- fsps,pcie-rp-ext-sync: PCIE Root Port Extended Sync +- fsps,pcie-rp-transmitter-half-swing: Transmitter Half Swing +- fsps,pcie-rp-acs: ACS +- fsps,pcie-rp-clk-req-supported: Clock Request Support +- fsps,pcie-rp-clk-req-number: Configure CLKREQ Number +- fsps,pcie-rp-clk-req-detect: CLKREQ# Detection +- fsps,advanced-error-reportingt: Advanced Error Reporting +- fsps,pme-interrupt: PME Interrupt +- fsps,unsupported-request-report: URR +- fsps,fatal-error-report: FER +- fsps,no-fatal-error-report: NFER +- fsps,correctable-error-report: CER +- fsps,system-error-on-fatal-error: SEFE +- fsps,system-error-on-non-fatal-error: SENFE +- fsps,system-error-on-correctable-error: SECE +- fsps,pcie-rp-speed: PCIe Speed +- fsps,physical-slot-number: Physical Slot Number + 0: Auto (default) + 1: Gen1 + 2: Gen2 + 3: Gen3 +- fsps,pcie-rp-completion-timeout: CTO + 0x00, 0x01, 0x02, 0x03, 0x04, 0x05 (default) +- fsps,enable-ptm: PTM Support +- fsps,pcie-rp-aspm: ASPM +- fsps,pcie-rp-l1-substates: L1 Substates +- fsps,pcie-rp-ltr-enable: PCH PCIe LTR +- fsps,pcie-rp-ltr-config-lock: PCIE LTR Lock +- fsps,pme-b0-s5-di: PME_B0_S5 Disable bit +- fsps,pci-clock-run: PCI Clock Run +- fsps,timer8254-clk-setting: Enable/Disable Timer 8254 Clock Setting +- fsps,enable-sata: Chipset SATA +- fsps,sata-mode: SATA Mode Selection + 0: AHCI (default) + 1: RAID +- fsps,sata-salp-support: Aggressive LPM Support +- fsps,sata-pwr-opt-enable: SATA Power Optimization +- fsps,e-sata-speed-limit: eSATA Speed Limit +- fsps,speed-limit: SATA Speed Limit + 0x1: 1.5Gb/s(Gen 1) + 0x2: 3Gb/s(Gen 2) + 0x3: 6Gb/s(Gen 3) +- fsps,sata-ports-enable: SATA Port +- fsps,sata-ports-dev-slp: SATA Port DevSlp +- fsps,sata-ports-hot-plug: SATA Port HotPlug +- fsps,sata-ports-interlock-sw: Mechanical Presence Switch +- fsps,sata-ports-external: External SATA Ports +- fsps,sata-ports-spin-up: Spin Up Device +- fsps,sata-ports-solid-state-drive: SATA Solid State + 0: Hard Disk Drive (default) + 1: Solid State Drive +- fsps,sata-ports-enable-dito-config: DITO Configuration +- fsps,sata-ports-dm-val: DM Value + 0x0F: Maximum (default) +- fsps,sata-ports-dito-val: DITO Value + 0x0271 (default) +- fsps,sub-system-vendor-id: Subsystem Vendor ID + 0x8086: (default) +- fsps,sub-system-id: Subsystem ID + 0x7270: (default) +- fsps,crid-setting: CRIDSettings + 0: Disable (default) + 1: CRID_1 + 2: CRID_2 + 3: CRID_3 +- fsps,reset-select: ResetSelect + 0x6: warm reset (default) + 0xE: cold reset +- fsps,sdcard-enabled: SD Card Support (D27:F0) +- fsps,emmc-enabled: SeMMC Support (D28:F0) +- fsps,emmc-host-max-speed: eMMC Max Speed + 0: HS400(default) + 1: HS200 + 2: DDR50 +- fsps,ufs-enabled: UFS Support (D29:F0) +- fsps,sdio-enabled: SDIO Support (D30:F0) +- fsps,gpp-lock: GPP Lock Feature +- fsps,sirq-enable: Serial IRQ +- fsps,sirq-mode: Serial IRQ Mode + 0: Quiet mode (default) + 1: Continuous mode +- fsps,start-frame-pulse: Start Frame Pulse Width + 0: ScSfpw4Clk (default) + 1: ScSfpw6Clk + 2: ScSfpw8Clk +- fsps,smbus-enable: SMBus +- fsps,arp-enable: SMBus ARP Support +- fsps,num-rsvd-smbus-addresses: SMBus Table Elements + 0x0080: (default) +- fsps,rsvd-smbus-address-table: Reserved SMBus Address Table + 0x00: (default) +- fsps,disable-compliance-mode: XHCI Disable Compliance Mode +- fsps,usb-per-port-ctl: USB Per-Port Control +- fsps,usb30-mode: xHCI Mode + 0: Disable + 1: Enable + 2: Auto (default) +- fsps,port-usb20-enable: Enable USB2 ports +- fsps,port-usb20-over-current-pin: USB20 Over Current Pin +- fsps,usb-otg: XDCI Support + 0: Disable + 1: PCI_Mode (default) + 2: ACPI_mode +- fsps,hsic-support-enable: Enable XHCI HSIC Support +- fsps,port-usb30-enable: Enable USB3 ports +- fsps,port-usb30-over-current-pin: USB30 Over Current Pin +- fsps,ssic-port-enable: Enable XHCI SSIC Support +- fsps,dlane-pwr-gating: SSIC Dlane PowerGating +- fsps,vtd-enable: VT-d +- fsps,lock-down-global-smi: SMI Lock bit +- fsps,reset-wait-timer: HDAudio Delay Timer + 0x012C: (default) +- fsps,rtc-lock: RTC Lock Bits +- fsps,sata-test-mode: SATA Test Mode Selection +- fsps,ssic-rate: XHCI SSIC RATE + 1: A Series (default) + 2: B Series +- fsps,dynamic-power-gating: SMBus Dynamic Power Gating +- fsps,pcie-rp-ltr-max-snoop-latency: Max Snoop Latency + 0x0000: (default) +- fsps,pcie-rp-snoop-latency-override-mode: Snoop Latency Override + 0: Disable + 1: Enable + 2: Auto (default) +- fsps,pcie-rp-snoop-latency-override-value: Snoop Latency Value + 0x003C (default) +- fsps,pcie-rp-snoop-latency-override-multiplier: Snoop Latency Multiplier + 0: 1ns + 1: 32ns + 2: 1024ns (default) + 3: 32768ns + 4: 1048576ns + 5: 33554432ns +- fsps,skip-mp-init: Skip Multi-Processor Initialization +- fsps,dci-auto-detect: DCI Auto Detect +- fsps,pcie-rp-ltr-max-non-snoop-latency: Max Non-Snoop Latency + 0x0000: (default) +- fsps,pcie-rp-non-snoop-latency-override-mode: Non Snoop Latency Override +- fsps,tco-timer-halt-lock: Halt and Lock TCO Timer +- fsps,pwr-btn-override-period: Power Button Override Period + 000: 4s (default) + 001: 6s + 010: 8s + 011: 10s + 100: 12s + 101: 14s +- fsps,pcie-rp-non-snoop-latency-override-value: + 0x003C: (default) +- fsps,pcie-rp-non-snoop-latency-override-multiplier: Non Snoop Latency Value + 0: 1ns + 1: 32ns + 2: 1024ns (default) + 3: 32768ns + 4: 1048576ns + 5: 33554432ns +- fsps,pcie-rp-slot-power-limit-scale: PCIE Root Port Slot Power Limit Scale + 0x00: (default) +- fsps,pcie-rp-slot-power-limit-value: + 0x00: (default) +- fsps,disable-native-power-button: Power Button Native Mode Disable +- fsps,power-butter-debounce-mode: Power Button Debounce Mode +- fsps,sdio-tx-cmd-cntl: SDIO_TX_CMD_DLL_CNTL + 0x505: (default) +- fsps,sdio-tx-data-cntl1: SDIO_TX_DATA_DLL_CNTL1 + 0xE: (default) +- fsps,sdio-tx-data-cntl2: SDIO_TX_DATA_DLL_CNTL2 + 0x22272828: (default) +- fsps,sdio-rx-cmd-data-cntl1: SDIO_RX_CMD_DATA_DLL_CNTL1 + 0x16161616: (default) +- fsps,sdio-rx-cmd-data-cntl2: SDIO_RX_CMD_DATA_DLL_CNTL2 + 0x10000: (default) +- fsps,sdcard-tx-cmd-cntl: SDCARD_TX_CMD_DLL_CNTL + 0x505 (default) +- fsps,sdcard-tx-data-cntl1: SDCARD_TX_DATA_DLL_CNTL1 + 0xA13: (default) +- fsps,sdcard-tx-data-cntl2: SDCARD_TX_DATA_DLL_CNTL2 + 0x24242828: (default) +- fsps,sdcard-rx-cmd-data-cntl1: SDCARD_RX_CMD_DATA_DLL_CNTL1 + 0x73A3637 (default) +- fsps,sdcard-rx-strobe-cntl: SDCARD_RX_STROBE_DLL_CNTL + 0x0: (default) +- fsps,sdcard-rx-cmd-data-cntl2: SDCARD_RX_CMD_DATA_DLL_CNTL2 + 0x10000: (default) +- fsps,emmc-tx-cmd-cntl: EMMC_TX_CMD_DLL_CNTL + 0x505: (default) +- fsps,emmc-tx-data-cntl1: EMMC_TX_DATA_DLL_CNTL1 + 0xC11: (default) +- fsps,emmc-tx-data-cntl2: EMMC_TX_DATA_DLL_CNTL2 + 0x1C2A2927: (default) +- fsps,emmc-rx-cmd-data-cntl1: EMMC_RX_CMD_DATA_DLL_CNTL1 + 0x000D162F: (default) +- fsps,emmc-rx-strobe-cntl: EMMC_RX_STROBE_DLL_CNTL + 0x0a0a: (default) +- fsps,emmc-rx-cmd-data-cntl2: EMMC_RX_CMD_DATA_DLL_CNTL2 + 0x1003b: (default) +- fsps,emmc-master-sw-cntl: EMMC_MASTER_DLL_CNTL + 0x001: (default) +- fsps,pcie-rp-selectable-deemphasis: PCIe Selectable De-emphasis + 1: -3.5 dB (default) + 0: -6 dB +- fsps,monitor-mwait-enable: Monitor Mwait Enable +- fsps,hd-audio-dsp-uaa-compliance: Universal Audio Architecture + compliance for DSP enabled system +- fsps,ipc: IRQ Interrupt Polarity Control +- fsps,sata-ports-disable-dynamic-pg: Disable ModPHY dynamic power gate +- fsps,init-s3-cpu: Init CPU during S3 resume +- fsps,skip-punit-init: Skip P-unit Initialization +- fsps,port-usb20-per-port-tx-pe-half: PerPort Half Bit Pre-emphasis +- fsps,port-usb20-per-port-pe-txi-set: PerPort HS Pre-emphasis Bias +- fsps,port-usb20-per-port-txi-set: PerPort HS Transmitter Bias +- fsps,port-usb20-hs-skew-sel: Select the skew direction for HS transition +- fsps,port-usb20-i-usb-tx-emphasis-en: PerPort HS Transmitter Emphasis +- fsps,port-usb20-per-port-rxi-set: PerPort HS Receiver Bias +- fsps,port-usb20-hs-npre-drv-sel: Delay/skew's strength control for HS driver +- fsps,os-selection: OS Selection + 0: Windows + 1: Android + 3: Linux +- fsps,dptf-enabled: DPTF +- fsps,pwm-enabled: PWM Enabled + +Example: + +&fsp_s { + u-boot,dm-pre-proper; + + fsps,ish-enable = <0>; + fsps,enable-sata = <0>; + fsps,pcie-root-port-en = [00 00 00 00 00 01]; + fsps,pcie-rp-hot-plug = [00 00 00 00 00 01]; + fsps,i2c6-enable = <I2CX_ENABLE_DISABLED>; + fsps,i2c7-enable = <I2CX_ENABLE_DISABLED>; + fsps,hsuart3-enable = <HSUARTX_ENABLE_DISABLED>; + fsps,spi1-enable = <SPIX_ENABLE_DISABLED>; + fsps,spi2-enable = <SPIX_ENABLE_DISABLED>; + fsps,sdio-enabled = <0>; + ... +}; diff --git a/roms/u-boot/doc/device-tree-bindings/gpio/altera_pio.txt b/roms/u-boot/doc/device-tree-bindings/gpio/altera_pio.txt new file mode 100644 index 000000000..cf71eb282 --- /dev/null +++ b/roms/u-boot/doc/device-tree-bindings/gpio/altera_pio.txt @@ -0,0 +1,28 @@ +Altera GPIO controller bindings + +Required properties: +- compatible: + - "altr,pio-1.0" +- reg: Physical base address and length of the controller's registers. + +Optional properties: +- altr,gpio-bank-width: Width of the GPIO bank. This defines how many pins the + GPIO device has. Ranges between 1-32. Optional and defaults to 32 if not + specified. +- gpio-bank-name: bank name attached to this device. + +Example: + +user_led_pio_8out: gpio@0x4cc0 { + compatible = "altr,pio-1.0"; + reg = <0x00004cc0 0x00000010>; + resetvalue = <255>; + altr,gpio-bank-width = <8>; + #gpio-cells = <2>; + gpio-controller; + gpio-bank-name = "led"; +}; + +In this example, the gpio can be accessed as led[0..7] using gpio command of +u-boot. +==> gpio clear led0 diff --git a/roms/u-boot/doc/device-tree-bindings/gpio/bcm2835-gpio.txt b/roms/u-boot/doc/device-tree-bindings/gpio/bcm2835-gpio.txt new file mode 100644 index 000000000..21e0610b3 --- /dev/null +++ b/roms/u-boot/doc/device-tree-bindings/gpio/bcm2835-gpio.txt @@ -0,0 +1,5 @@ +* Broadcom BCM283x GPIO controller + +Required properties: +- compatible: must be "brcm,bcm2835-gpio" +- reg: exactly one register range with length 0xb4 diff --git a/roms/u-boot/doc/device-tree-bindings/gpio/fsl,mpc83xx-spisel-boot.txt b/roms/u-boot/doc/device-tree-bindings/gpio/fsl,mpc83xx-spisel-boot.txt new file mode 100644 index 000000000..52d8bb0a5 --- /dev/null +++ b/roms/u-boot/doc/device-tree-bindings/gpio/fsl,mpc83xx-spisel-boot.txt @@ -0,0 +1,22 @@ +MPC83xx SPISEL_BOOT gpio controller + +Provide access to MPC83xx SPISEL_BOOT signal as a gpio to allow it to be +easily bound as a SPI controller chip select. + +The SPISEL_BOOT signal is always an output. + +Required properties: + +- compatible: must be "fsl,mpc83xx-spisel-boot" or "fsl,mpc8309-spisel-boot". +- reg: must point to the SPI_CS register in the SoC register map. +- ngpios: number of gpios provided by driver, normally 1. + +Example: + + spisel_boot: spisel_boot@14c { + compatible = "fsl,mpc8309-spisel-boot"; + reg = <0x14c 0x04>; + #gpio-cells = <2>; + device_type = "gpio"; + ngpios = <1>; + }; diff --git a/roms/u-boot/doc/device-tree-bindings/gpio/gpio-msm.txt b/roms/u-boot/doc/device-tree-bindings/gpio/gpio-msm.txt new file mode 100644 index 000000000..70a2c7f0d --- /dev/null +++ b/roms/u-boot/doc/device-tree-bindings/gpio/gpio-msm.txt @@ -0,0 +1,23 @@ +Qualcomm Snapdragon GPIO controller + +Required properties: +- compatible : "qcom,msm8916-pinctrl", "qcom,apq8016-pinctrl" or + "qcom,ipq4019-pinctrl" +- reg : Physical base address and length of the controller's registers. + This controller is called "Top Level Mode Multiplexing" in + Qualcomm documentation. +- #gpio-cells : Should be one (pin number). +- gpio-controller : Marks the device node as a GPIO controller. +- gpio-count: Number of GPIO pins. +- gpio-bank-name: (optional) name of gpio bank. As default "soc" is used. + +Example: + +soc_gpios: pinctrl@1000000 { + compatible = "qcom,msm8916-pinctrl"; + reg = <0x1000000 0x300000>; + gpio-controller; + gpio-count = <122>; + gpio-bank-name="soc"; + #gpio-cells = <1>; +}; diff --git a/roms/u-boot/doc/device-tree-bindings/gpio/gpio-pcf857x.txt b/roms/u-boot/doc/device-tree-bindings/gpio/gpio-pcf857x.txt new file mode 100644 index 000000000..ada4e2973 --- /dev/null +++ b/roms/u-boot/doc/device-tree-bindings/gpio/gpio-pcf857x.txt @@ -0,0 +1,71 @@ +* PCF857x-compatible I/O expanders + +The PCF857x-compatible chips have "quasi-bidirectional" I/O lines that can be +driven high by a pull-up current source or driven low to ground. This combines +the direction and output level into a single bit per line, which can't be read +back. We can't actually know at initialization time whether a line is configured +(a) as output and driving the signal low/high, or (b) as input and reporting a +low/high value, without knowing the last value written since the chip came out +of reset (if any). The only reliable solution for setting up line direction is +thus to do it explicitly. + +Required Properties: + + - compatible: should be one of the following. + - "maxim,max7328": For the Maxim MAX7378 + - "maxim,max7329": For the Maxim MAX7329 + - "nxp,pca8574": For the NXP PCA8574 + - "nxp,pca8575": For the NXP PCA8575 + - "nxp,pca9670": For the NXP PCA9670 + - "nxp,pca9671": For the NXP PCA9671 + - "nxp,pca9672": For the NXP PCA9672 + - "nxp,pca9673": For the NXP PCA9673 + - "nxp,pca9674": For the NXP PCA9674 + - "nxp,pca9675": For the NXP PCA9675 + - "nxp,pcf8574": For the NXP PCF8574 + - "nxp,pcf8574a": For the NXP PCF8574A + - "nxp,pcf8575": For the NXP PCF8575 + - "ti,tca9554": For the TI TCA9554 + + - reg: I2C slave address. + + - gpio-controller: Marks the device node as a gpio controller. + - #gpio-cells: Should be 2. The first cell is the GPIO number and the second + cell specifies GPIO flags, as defined in <dt-bindings/gpio/gpio.h>. Only the + GPIO_ACTIVE_HIGH and GPIO_ACTIVE_LOW flags are supported. + +Optional Properties: + + - lines-initial-states: Bitmask that specifies the initial state of each + line. When a bit is set to zero, the corresponding line will be initialized to + the input (pulled-up) state. When the bit is set to one, the line will be + initialized the low-level output state. If the property is not specified + all lines will be initialized to the input state. + + The I/O expander can detect input state changes, and thus optionally act as + an interrupt controller. When the expander interrupt line is connected all the + following properties must be set. For more information please see the + interrupt controller device tree bindings documentation available at + Documentation/devicetree/bindings/interrupt-controller/interrupts.txt. + + - interrupt-controller: Identifies the node as an interrupt controller. + - #interrupt-cells: Number of cells to encode an interrupt source, shall be 2. + - interrupt-parent: phandle of the parent interrupt controller. + - interrupts: Interrupt specifier for the controllers interrupt. + + +Please refer to gpio.txt in this directory for details of the common GPIO +bindings used by client devices. + +Example: PCF8575 I/O expander node + + pcf8575: gpio@20 { + compatible = "nxp,pcf8575"; + reg = <0x20>; + interrupt-parent = <&irqpin2>; + interrupts = <3 0>; + gpio-controller; + #gpio-cells = <2>; + interrupt-controller; + #interrupt-cells = <2>; + }; diff --git a/roms/u-boot/doc/device-tree-bindings/gpio/gpio-samsung.txt b/roms/u-boot/doc/device-tree-bindings/gpio/gpio-samsung.txt new file mode 100644 index 000000000..5375625e8 --- /dev/null +++ b/roms/u-boot/doc/device-tree-bindings/gpio/gpio-samsung.txt @@ -0,0 +1,41 @@ +Samsung Exynos4 GPIO Controller + +Required properties: +- compatible: Compatible property value should be "samsung,exynos4-gpio>". + +- reg: Physical base address of the controller and length of memory mapped + region. + +- #gpio-cells: Should be 4. The syntax of the gpio specifier used by client nodes + should be the following with values derived from the SoC user manual. + <[phandle of the gpio controller node] + [pin number within the gpio controller] + [mux function] + [flags and pull up/down] + [drive strength]> + + Values for gpio specifier: + - Pin number: is a value between 0 to 7. + - Flags and Pull Up/Down: 0 - Pull Up/Down Disabled. + 1 - Pull Down Enabled. + 3 - Pull Up Enabled. + Bit 16 (0x00010000) - Input is active low. + - Drive Strength: 0 - 1x, + 1 - 3x, + 2 - 2x, + 3 - 4x + +- gpio-controller: Specifies that the node is a gpio controller. +- #address-cells: should be 1. +- #size-cells: should be 1. + +Example: + + gpa0: gpio-controller@11400000 { + #address-cells = <1>; + #size-cells = <1>; + compatible = "samsung,exynos4-gpio"; + reg = <0x11400000 0x20>; + #gpio-cells = <4>; + gpio-controller; + }; diff --git a/roms/u-boot/doc/device-tree-bindings/gpio/gpio.txt b/roms/u-boot/doc/device-tree-bindings/gpio/gpio.txt new file mode 100644 index 000000000..1481ed607 --- /dev/null +++ b/roms/u-boot/doc/device-tree-bindings/gpio/gpio.txt @@ -0,0 +1,324 @@ +Specifying GPIO information for devices +============================================ + +1) gpios property +----------------- + +GPIO properties should be named "[<name>-]gpios", with <name> being the purpose +of this GPIO for the device. While a non-existent <name> is considered valid +for compatibility reasons (resolving to the "gpios" property), it is not allowed +for new bindings. Also, GPIO properties named "[<name>-]gpio" are valid and old +bindings use it, but are only supported for compatibility reasons and should not +be used for newer bindings since it has been deprecated. + +GPIO properties can contain one or more GPIO phandles, but only in exceptional +cases should they contain more than one. If your device uses several GPIOs with +distinct functions, reference each of them under its own property, giving it a +meaningful name. The only case where an array of GPIOs is accepted is when +several GPIOs serve the same function (e.g. a parallel data line). + +The exact purpose of each gpios property must be documented in the device tree +binding of the device. + +The following example could be used to describe GPIO pins used as device enable +and bit-banged data signals: + + gpio1: gpio1 { + gpio-controller; + #gpio-cells = <2>; + }; + [...] + + data-gpios = <&gpio1 12 0>, + <&gpio1 13 0>, + <&gpio1 14 0>, + <&gpio1 15 0>; + +In the above example, &gpio1 uses 2 cells to specify a gpio. The first cell is +a local offset to the GPIO line and the second cell represent consumer flags, +such as if the consumer desire the line to be active low (inverted) or open +drain. This is the recommended practice. + +The exact meaning of each specifier cell is controller specific, and must be +documented in the device tree binding for the device, but it is strongly +recommended to use the two-cell approach. + +Most controllers are specifying a generic flag bitfield in the last cell, so +for these, use the macros defined in +include/dt-bindings/gpio/gpio.h whenever possible: + +Example of a node using GPIOs: + + node { + enable-gpios = <&qe_pio_e 18 GPIO_ACTIVE_HIGH>; + }; + +GPIO_ACTIVE_HIGH is 0, so in this example gpio-specifier is "18 0" and encodes +GPIO pin number, and GPIO flags as accepted by the "qe_pio_e" gpio-controller. + +Optional standard bitfield specifiers for the last cell: + +- Bit 0: 0 means active high, 1 means active low +- Bit 1: 0 mean push-pull wiring, see: + https://en.wikipedia.org/wiki/Push-pull_output + 1 means single-ended wiring, see: + https://en.wikipedia.org/wiki/Single-ended_triode +- Bit 2: 0 means open-source, 1 means open drain, see: + https://en.wikipedia.org/wiki/Open_collector +- Bit 3: 0 means the output should be maintained during sleep/low-power mode + 1 means the output state can be lost during sleep/low-power mode +- Bit 4: 0 means no pull-up resistor should be enabled + 1 means a pull-up resistor should be enabled + This setting only applies to hardware with a simple on/off + control for pull-up configuration. If the hardware has more + elaborate pull-up configuration, it should be represented + using a pin control binding. +- Bit 5: 0 means no pull-down resistor should be enabled + 1 means a pull-down resistor should be enabled + This setting only applies to hardware with a simple on/off + control for pull-down configuration. If the hardware has more + elaborate pull-down configuration, it should be represented + using a pin control binding. + +1.1) GPIO specifier best practices +---------------------------------- + +A gpio-specifier should contain a flag indicating the GPIO polarity; active- +high or active-low. If it does, the following best practices should be +followed: + +The gpio-specifier's polarity flag should represent the physical level at the +GPIO controller that achieves (or represents, for inputs) a logically asserted +value at the device. The exact definition of logically asserted should be +defined by the binding for the device. If the board inverts the signal between +the GPIO controller and the device, then the gpio-specifier will represent the +opposite physical level than the signal at the device's pin. + +When the device's signal polarity is configurable, the binding for the +device must either: + +a) Define a single static polarity for the signal, with the expectation that +any software using that binding would statically program the device to use +that signal polarity. + +The static choice of polarity may be either: + +a1) (Preferred) Dictated by a binding-specific DT property. + +or: + +a2) Defined statically by the DT binding itself. + +In particular, the polarity cannot be derived from the gpio-specifier, since +that would prevent the DT from separately representing the two orthogonal +concepts of configurable signal polarity in the device, and possible board- +level signal inversion. + +or: + +b) Pick a single option for device signal polarity, and document this choice +in the binding. The gpio-specifier should represent the polarity of the signal +(at the GPIO controller) assuming that the device is configured for this +particular signal polarity choice. If software chooses to program the device +to generate or receive a signal of the opposite polarity, software will be +responsible for correctly interpreting (inverting) the GPIO signal at the GPIO +controller. + +2) gpio-controller nodes +------------------------ + +Every GPIO controller node must contain both an empty "gpio-controller" +property, and a #gpio-cells integer property, which indicates the number of +cells in a gpio-specifier. + +Some system-on-chips (SoCs) use the concept of GPIO banks. A GPIO bank is an +instance of a hardware IP core on a silicon die, usually exposed to the +programmer as a coherent range of I/O addresses. Usually each such bank is +exposed in the device tree as an individual gpio-controller node, reflecting +the fact that the hardware was synthesized by reusing the same IP block a +few times over. + +Optionally, a GPIO controller may have a "ngpios" property. This property +indicates the number of in-use slots of available slots for GPIOs. The +typical example is something like this: the hardware register is 32 bits +wide, but only 18 of the bits have a physical counterpart. The driver is +generally written so that all 32 bits can be used, but the IP block is reused +in a lot of designs, some using all 32 bits, some using 18 and some using +12. In this case, setting "ngpios = <18>;" informs the driver that only the +first 18 GPIOs, at local offset 0 .. 17, are in use. + +If these GPIOs do not happen to be the first N GPIOs at offset 0...N-1, an +additional set of tuples is needed to specify which GPIOs are unusable, with +the gpio-reserved-ranges binding. This property indicates the start and size +of the GPIOs that can't be used. + +Optionally, a GPIO controller may have a "gpio-line-names" property. This is +an array of strings defining the names of the GPIO lines going out of the +GPIO controller. This name should be the most meaningful producer name +for the system, such as a rail name indicating the usage. Package names +such as pin name are discouraged: such lines have opaque names (since they +are by definition generic purpose) and such names are usually not very +helpful. For example "MMC-CD", "Red LED Vdd" and "ethernet reset" are +reasonable line names as they describe what the line is used for. "GPIO0" +is not a good name to give to a GPIO line. Placeholders are discouraged: +rather use the "" (blank string) if the use of the GPIO line is undefined +in your design. The names are assigned starting from line offset 0 from +left to right from the passed array. An incomplete array (where the number +of passed named are less than ngpios) will still be used up until the last +provided valid line index. + +Example: + +gpio-controller@00000000 { + compatible = "foo"; + reg = <0x00000000 0x1000>; + gpio-controller; + #gpio-cells = <2>; + ngpios = <18>; + gpio-reserved-ranges = <0 4>, <12 2>; + gpio-line-names = "MMC-CD", "MMC-WP", "VDD eth", "RST eth", "LED R", + "LED G", "LED B", "Col A", "Col B", "Col C", "Col D", + "Row A", "Row B", "Row C", "Row D", "NMI button", + "poweroff", "reset"; +} + +The GPIO chip may contain GPIO hog definitions. GPIO hogging is a mechanism +providing automatic GPIO request and configuration as part of the +gpio-controller's driver probe function. + +Each GPIO hog definition is represented as a child node of the GPIO controller. +Required properties: +- gpio-hog: A property specifying that this child node represents a GPIO hog. +- gpios: Store the GPIO information (id, flags, ...) for each GPIO to + affect. Shall contain an integer multiple of the number of cells + specified in its parent node (GPIO controller node). +Only one of the following properties scanned in the order shown below. +This means that when multiple properties are present they will be searched +in the order presented below and the first match is taken as the intended +configuration. +- input: A property specifying to set the GPIO direction as input. +- output-low A property specifying to set the GPIO direction as output with + the value low. +- output-high A property specifying to set the GPIO direction as output with + the value high. + +Optional properties: +- line-name: The GPIO label name. If not present the node name is used. + +Example of two SOC GPIO banks defined as gpio-controller nodes: + + qe_pio_a: gpio-controller@1400 { + compatible = "fsl,qe-pario-bank-a", "fsl,qe-pario-bank"; + reg = <0x1400 0x18>; + gpio-controller; + #gpio-cells = <2>; + }; + + qe_pio_e: gpio-controller@1460 { + compatible = "fsl,qe-pario-bank-e", "fsl,qe-pario-bank"; + reg = <0x1460 0x18>; + gpio-controller; + #gpio-cells = <2>; + }; + +2.1) gpio- and pin-controller interaction +----------------------------------------- + +Some or all of the GPIOs provided by a GPIO controller may be routed to pins +on the package via a pin controller. This allows muxing those pins between +GPIO and other functions. It is a fairly common practice among silicon +engineers. + +2.2) Ordinary (numerical) GPIO ranges +------------------------------------- + +It is useful to represent which GPIOs correspond to which pins on which pin +controllers. The gpio-ranges property described below represents this with +a discrete set of ranges mapping pins from the pin controller local number space +to pins in the GPIO controller local number space. + +The format is: <[pin controller phandle], [GPIO controller offset], + [pin controller offset], [number of pins]>; + +The GPIO controller offset pertains to the GPIO controller node containing the +range definition. + +The pin controller node referenced by the phandle must conform to the bindings +described in pinctrl/pinctrl-bindings.txt. + +Each offset runs from 0 to N. It is perfectly fine to pile any number of +ranges with just one pin-to-GPIO line mapping if the ranges are concocted, but +in practice these ranges are often lumped in discrete sets. + +Example: + + gpio-ranges = <&foo 0 20 10>, <&bar 10 50 20>; + +This means: +- pins 20..29 on pin controller "foo" is mapped to GPIO line 0..9 and +- pins 50..69 on pin controller "bar" is mapped to GPIO line 10..29 + + +Verbose example: + + qe_pio_e: gpio-controller@1460 { + #gpio-cells = <2>; + compatible = "fsl,qe-pario-bank-e", "fsl,qe-pario-bank"; + reg = <0x1460 0x18>; + gpio-controller; + gpio-ranges = <&pinctrl1 0 20 10>, <&pinctrl2 10 50 20>; + }; + +Here, a single GPIO controller has GPIOs 0..9 routed to pin controller +pinctrl1's pins 20..29, and GPIOs 10..29 routed to pin controller pinctrl2's +pins 50..69. + + +2.3) GPIO ranges from named pin groups +-------------------------------------- + +It is also possible to use pin groups for gpio ranges when pin groups are the +easiest and most convenient mapping. + +Both both <pinctrl-base> and <count> must set to 0 when using named pin groups +names. + +The property gpio-ranges-group-names must contain exactly one string for each +range. + +Elements of gpio-ranges-group-names must contain the name of a pin group +defined in the respective pin controller. The number of pins/GPIO lines in the +range is the number of pins in that pin group. The number of pins of that +group is defined int the implementation and not in the device tree. + +If numerical and named pin groups are mixed, the string corresponding to a +numerical pin range in gpio-ranges-group-names must be empty. + +Example: + + gpio_pio_i: gpio-controller@14b0 { + #gpio-cells = <2>; + compatible = "fsl,qe-pario-bank-e", "fsl,qe-pario-bank"; + reg = <0x1480 0x18>; + gpio-controller; + gpio-ranges = <&pinctrl1 0 20 10>, + <&pinctrl2 10 0 0>, + <&pinctrl1 15 0 10>, + <&pinctrl2 25 0 0>; + gpio-ranges-group-names = "", + "foo", + "", + "bar"; + }; + +Here, three GPIO ranges are defined referring to two pin controllers. + +pinctrl1 GPIO ranges are defined using pin numbers whereas the GPIO ranges +in pinctrl2 are defined using the pin groups named "foo" and "bar". + +Previous versions of this binding required all pin controller nodes that +were referenced by any gpio-ranges property to contain a property named +#gpio-range-cells with value <3>. This requirement is now deprecated. +However, that property may still exist in older device trees for +compatibility reasons, and would still be required even in new device +trees that need to be compatible with older software. diff --git a/roms/u-boot/doc/device-tree-bindings/gpio/intel,apl-gpio.txt b/roms/u-boot/doc/device-tree-bindings/gpio/intel,apl-gpio.txt new file mode 100644 index 000000000..8422ff63a --- /dev/null +++ b/roms/u-boot/doc/device-tree-bindings/gpio/intel,apl-gpio.txt @@ -0,0 +1,55 @@ +Intel Apollo Lake GPIO controller + +The Apollo Lake (APL) GPIO controller is used to control GPIO functions of +the pins. + +Required properties: +- compatible: "intel,apl-gpio" +- #gpio-cells: Should be 2. The syntax of the gpio specifier used by client + nodes should be the following with values derived from the SoC user manual. + <[phandle of the gpio controller node] + [pin number within the gpio controller] + [flags]> + + Values for gpio specifier: + - Pin number: is a GPIO pin number between 0 and 244 + - Flags: GPIO_ACTIVE_HIGH or GPIO_ACTIVE_LOW + +- gpio-controller: Specifies that the node is a gpio controller. + +Example: + +... +{ + p2sb: p2sb@d,0 { + reg = <0x02006810 0 0 0 0>; + compatible = "intel,p2sb"; + early-regs = <IOMAP_P2SB_BAR 0x100000>; + + north { + compatible = "intel,apl-pinctrl"; + intel,p2sb-port-id = <PID_GPIO_N>; + gpio_n: gpio-n { + compatible = "intel,gpio"; + gpio-controller; + #gpio-cells = <2>; + }; + }; + }; + + i2c_2: i2c2@16,2 { + compatible = "intel,apl-i2c", "snps,designware-i2c-pci"; + reg = <0x0200b210 0 0 0 0>; + #address-cells = <1>; + #size-cells = <0>; + clock-frequency = <400000>; + tpm@50 { + reg = <0x50>; + compatible = "google,cr50"; + u-boot,i2c-offset-len = <0>; + ready-gpios = <&gpio_n GPIO_28 GPIO_ACTIVE_LOW>; + }; + }; + +}; +... diff --git a/roms/u-boot/doc/device-tree-bindings/gpio/intel,x86-broadwell-pinctrl.txt b/roms/u-boot/doc/device-tree-bindings/gpio/intel,x86-broadwell-pinctrl.txt new file mode 100644 index 000000000..a644381e0 --- /dev/null +++ b/roms/u-boot/doc/device-tree-bindings/gpio/intel,x86-broadwell-pinctrl.txt @@ -0,0 +1,208 @@ +Intel x86 PINCTRL/GPIO controller + +Pin-muxing on broadwell devices can be described with a node for the PINCTRL +master node and a set of child nodes for each required pin state on the SoC. +These pin states use phandles and are referred to but a configuration section +which lists all pins in the device. + +The PINCTRL master node requires the following properties: +- compatible : "intel,x86-broadwell-pinctrl" + +Pin state nodes must be sub-nodes of the pinctrl master node. The must have +a phandle. They can contain the following optional properties: +- mode-gpio - forces the pin into GPIO mode +- output-value - sets the default output value of the GPIO, 0 (low, default) + or 1 (high) +- direction - sets the direction of the gpio, either PIN_INPUT (default) + or PIN_OUTPUT +- invert - the input pin is inverted +- trigger - sets the trigger type, either TRIGGER_EDGE (default) or + TRIGGER_LEVEL +- sense-disable - the input state sense is disabled +- owner 0 sets the owner of the pin, either OWNER_ACPI (default) or + ONWER_GPIO +- route - sets whether the pin is routed, either PIRQ_APIC_MASK or + PIRQ_APIC_ROUTE +- irq-enable - the interrupt is enabled +- reset-rsmrst - the pin will only be reset by RSMRST +- pirq-apic - the pin will be routed to the IOxAPIC + +The first pin state will be the default, so pins without a configuration will +use that. + +The pin configuration node is also a sub-node of the pinctrl master node, but +does not have a phandle. It has a single property: + +- config - configuration to use for each pin. Each entry has of 3 cells: + - GPIO number (0..94) + - phandle of configuration (above) + - interrupt number (0..15) + + There should be one entry for each pin (i.e. 95 entries). + But missing pins will receive the default configuration. + +Example: + +pch_pinctrl { + compatible = "intel,x86-broadwell-pinctrl"; + + /* Put this first: it is the default */ + gpio_unused: gpio-unused { + mode-gpio; + direction = <PIN_INPUT>; + owner = <OWNER_GPIO>; + sense-disable; + }; + + gpio_acpi_sci: acpi-sci { + mode-gpio; + direction = <PIN_INPUT>; + invert; + route = <ROUTE_SCI>; + }; + + gpio_acpi_smi: acpi-smi { + mode-gpio; + direction = <PIN_INPUT>; + invert; + route = <ROUTE_SMI>; + }; + + gpio_input: gpio-input { + mode-gpio; + direction = <PIN_INPUT>; + owner = <OWNER_GPIO>; + }; + + gpio_input_invert: gpio-input-invert { + mode-gpio; + direction = <PIN_INPUT>; + owner = <OWNER_GPIO>; + invert; + }; + + gpio_native: gpio-native { + }; + + gpio_out_high: gpio-out-high { + mode-gpio; + direction = <PIN_OUTPUT>; + output-value = <1>; + owner = <OWNER_GPIO>; + sense-disable; + }; + + gpio_out_low: gpio-out-low { + mode-gpio; + direction = <PIN_OUTPUT>; + output-value = <0>; + owner = <OWNER_GPIO>; + sense-disable; + }; + + gpio_pirq: gpio-pirq { + mode-gpio; + direction = <PIN_INPUT>; + owner = <OWNER_GPIO>; + pirq-apic = <PIRQ_APIC_ROUTE>; + }; + + soc_gpio@0 { + config = + <0 &gpio_unused 0>, /* unused */ + <1 &gpio_unused 0>, /* unused */ + <2 &gpio_unused 0>, /* unused */ + <3 &gpio_unused 0>, /* unused */ + <4 &gpio_native 0>, /* native: i2c0_sda_gpio4 */ + <5 &gpio_native 0>, /* native: i2c0_scl_gpio5 */ + <6 &gpio_native 0>, /* native: i2c1_sda_gpio6 */ + <7 &gpio_native 0>, /* native: i2c1_scl_gpio7 */ + <8 &gpio_acpi_sci 0>, /* pch_lte_wake_l */ + <9 &gpio_input_invert 0>,/* trackpad_int_l (wake) */ + <10 &gpio_acpi_sci 0>, /* pch_wlan_wake_l */ + <11 &gpio_unused 0>, /* unused */ + <12 &gpio_unused 0>, /* unused */ + <13 &gpio_pirq 3>, /* trackpad_int_l (pirql) */ + <14 &gpio_pirq 4>, /* touch_int_l (pirqm) */ + <15 &gpio_unused 0>, /* unused (strap) */ + <16 &gpio_input 0>, /* pch_wp */ + <17 &gpio_unused 0>, /* unused */ + <18 &gpio_unused 0>, /* unused */ + <19 &gpio_unused 0>, /* unused */ + <20 &gpio_native 0>, /* pcie_wlan_clkreq_l */ + <21 &gpio_out_high 0>, /* pp3300_ssd_en */ + <22 &gpio_unused 0>, /* unused */ + <23 &gpio_out_low 0>, /* pp3300_autobahn_en */ + <24 &gpio_unused 0>, /* unused */ + <25 &gpio_input 0>, /* ec_in_rw */ + <26 &gpio_unused 0>, /* unused */ + <27 &gpio_acpi_sci 0>, /* pch_wake_l */ + <28 &gpio_unused 0>, /* unused */ + <29 &gpio_unused 0>, /* unused */ + <30 &gpio_native 0>, /* native: pch_suswarn_l */ + <31 &gpio_native 0>, /* native: acok_buf */ + <32 &gpio_native 0>, /* native: lpc_clkrun_l */ + <33 &gpio_native 0>, /* native: ssd_devslp */ + <34 &gpio_acpi_smi 0>, /* ec_smi_l */ + <35 &gpio_acpi_smi 0>, /* pch_nmi_dbg_l (route in nmi_en) */ + <36 &gpio_acpi_sci 0>, /* ec_sci_l */ + <37 &gpio_unused 0>, /* unused */ + <38 &gpio_unused 0>, /* unused */ + <39 &gpio_unused 0>, /* unused */ + <40 &gpio_native 0>, /* native: pch_usb1_oc_l */ + <41 &gpio_native 0>, /* native: pch_usb2_oc_l */ + <42 &gpio_unused 0>, /* wlan_disable_l */ + <43 &gpio_out_high 0>, /* pp1800_codec_en */ + <44 &gpio_unused 0>, /* unused */ + <45 &gpio_acpi_sci 0>, /* dsp_int - codec wake */ + <46 &gpio_pirq 6>, /* hotword_det_l_3v3 (pirqo) - codec irq */ + <47 &gpio_out_low 0>, /* ssd_reset_l */ + <48 &gpio_unused 0>, /* unused */ + <49 &gpio_unused 0>, /* unused */ + <50 &gpio_unused 0>, /* unused */ + <51 &gpio_unused 0>, /* unused */ + <52 &gpio_input 0>, /* sim_det */ + <53 &gpio_unused 0>, /* unused */ + <54 &gpio_unused 0>, /* unused */ + <55 &gpio_unused 0>, /* unused */ + <56 &gpio_unused 0>, /* unused */ + <57 &gpio_out_high 0>, /* codec_reset_l */ + <58 &gpio_unused 0>, /* unused */ + <59 &gpio_out_high 0>, /* lte_disable_l */ + <60 &gpio_unused 0>, /* unused */ + <61 &gpio_native 0>, /* native: pch_sus_stat */ + <62 &gpio_native 0>, /* native: pch_susclk */ + <63 &gpio_native 0>, /* native: pch_slp_s5_l */ + <64 &gpio_unused 0>, /* unused */ + <65 &gpio_input 0>, /* ram_id3 */ + <66 &gpio_input 0>, /* ram_id3_old (strap) */ + <67 &gpio_input 0>, /* ram_id0 */ + <68 &gpio_input 0>, /* ram_id1 */ + <69 &gpio_input 0>, /* ram_id2 */ + <70 &gpio_unused 0>, /* unused */ + <71 &gpio_native 0>, /* native: modphy_en */ + <72 &gpio_unused 0>, /* unused */ + <73 &gpio_unused 0>, /* unused */ + <74 &gpio_unused 0>, /* unused */ + <75 &gpio_unused 0>, /* unused */ + <76 &gpio_unused 0>, /* unused */ + <77 &gpio_unused 0>, /* unused */ + <78 &gpio_unused 0>, /* unused */ + <79 &gpio_unused 0>, /* unused */ + <80 &gpio_unused 0>, /* unused */ + <81 &gpio_unused 0>, /* unused */ + <82 &gpio_native 0>, /* native: ec_rcin_l */ + <83 &gpio_native 0>, /* gspi0_cs */ + <84 &gpio_native 0>, /* gspi0_clk */ + <85 &gpio_native 0>, /* gspi0_miso */ + <86 &gpio_native 0>, /* gspi0_mosi (strap) */ + <87 &gpio_unused 0>, /* unused */ + <88 &gpio_unused 0>, /* unused */ + <89 &gpio_out_high 0>, /* pp3300_sd_en */ + <90 &gpio_unused 0>, /* unused */ + <91 &gpio_unused 0>, /* unused */ + <92 &gpio_unused 0>, /* unused */ + <93 &gpio_unused 0>, /* unused */ + <94 &gpio_unused 0 >; /* unused */ + }; +}; diff --git a/roms/u-boot/doc/device-tree-bindings/gpio/intel,x86-pinctrl.txt b/roms/u-boot/doc/device-tree-bindings/gpio/intel,x86-pinctrl.txt new file mode 100644 index 000000000..8c3a84caf --- /dev/null +++ b/roms/u-boot/doc/device-tree-bindings/gpio/intel,x86-pinctrl.txt @@ -0,0 +1,33 @@ +Intel x86 PINCTRL/GPIO controller + +Pin-muxing on x86 can be described with a node for the PINCTRL master +node and a set of child nodes for each pin on the SoC. + +The PINCTRL master node requires the following properties: +- compatible : "intel,x86-pinctrl" + +Pin nodes must be children of the pinctrl master node and can +contain the following properties: +- pad-offset - (required) offset in the IOBASE for the pin to configure +- gpio-offset - (required only when 'mode-gpio' is set) 2 cells + - offset in the GPIOBASE for the pin to configure + - the bit shift in this register (4 = bit 4) +- mode-gpio - (optional) standalone property to force the pin into GPIO mode +- mode-func - (optional) function number to assign to the pin. If + 'mode-gpio' is set, this property will be ignored. +in case of 'mode-gpio' property set: +- output-value - (optional) this set the default output value of the GPIO +- direction - (optional) this set the direction of the gpio +- pull-strength - (optional) this set the pull strength of the pin +- pull-assign - (optional) this set the pull assignement (up/down) of the pin +- invert - (optional) this input pin is inverted + +Example: + +pin_usb_host_en0@0 { + gpio-offset = <0x80 8>; + pad-offset = <0x260>; + mode-gpio; + output-value = <1>; + direction = <PIN_OUTPUT>; +}; diff --git a/roms/u-boot/doc/device-tree-bindings/gpio/mscc_sgpio.txt b/roms/u-boot/doc/device-tree-bindings/gpio/mscc_sgpio.txt new file mode 100644 index 000000000..3d344d64a --- /dev/null +++ b/roms/u-boot/doc/device-tree-bindings/gpio/mscc_sgpio.txt @@ -0,0 +1,45 @@ +Microsemi Corporation (MSCC) Serial GPIO driver + +The MSCC serial GPIO extends the number or GPIO's on the system by +means of 4 dedicated pins: one input, one output, one clock and one +strobe pin. By attaching a number of (external) shift registers, the +effective GPIO count can be extended by up to 128 GPIO's per +controller. + +Required properties: +- compatible : "mscc,luton-sgpio" or "mscc,ocelot-sgpio" +- clock: Reference clock used to generate clock divider setting. See + mscc,sgpio-frequency property. +- reg : Physical base address and length of the controller's registers. +- #gpio-cells : Should be two. The first cell is the pin number and the + second cell is used to specify optional parameters: + - bit 0 specifies polarity (0 for normal, 1 for inverted) +- gpio-controller : Marks the device node as a GPIO controller. +- gpio-ranges: Standard gpio range(s): phandle, gpio base, pinctrl base + and count. + +Optional properties: +- ngpios: See gpio.txt +- mscc,sgpio-frequency: The frequency at which the serial bitstream is + generated and sampled. Default: 12500000 (Hz). +- mscc,sgpio-ports: A bitmask (32 bits) of which ports are enabled in + the serialized gpio stream. One 'port' will transport from 1 to 4 + gpio bits. Default: 0xFFFFFFFF. + +Typically the pinctrl-0 and pinctrl-names properties will also be +present to enable the use of the SIO CLK, LD, DI and DO for some +regular GPIO pins. + +Example: + +sgpio: gpio@10700f8 { + compatible = "mscc,ocelot-sgpio"; + pinctrl-0 = <&sgpio_pins>; + pinctrl-names = "default"; + reg = <0x10700f8 0x100>; + gpio-controller; + #gpio-cells = <2>; + gpio-ranges = <&sgpio 0 0 64>; + mscc,sgpio-frequency = <12500>; + mscc,sgpio-ports = <0x000FFFFF>; +}; diff --git a/roms/u-boot/doc/device-tree-bindings/gpio/nvidia,tegra186-gpio.txt b/roms/u-boot/doc/device-tree-bindings/gpio/nvidia,tegra186-gpio.txt new file mode 100644 index 000000000..c82a2e221 --- /dev/null +++ b/roms/u-boot/doc/device-tree-bindings/gpio/nvidia,tegra186-gpio.txt @@ -0,0 +1,161 @@ +NVIDIA Tegra186 GPIO controllers + +Tegra186 contains two GPIO controllers; a main controller and an "AON" +controller. This binding document applies to both controllers. The register +layouts for the controllers share many similarities, but also some significant +differences. Hence, this document describes closely related but different +bindings and compatible values. + +The Tegra186 GPIO controller allows software to set the IO direction of, and +read/write the value of, numerous GPIO signals. Routing of GPIO signals to +package balls is under the control of a separate pin controller HW block. Two +major sets of registers exist: + +a) Security registers, which allow configuration of allowed access to the GPIO +register set. These registers exist in a single contiguous block of physical +address space. The size of this block, and the security features available, +varies between the different GPIO controllers. + +Access to this set of registers is not necessary in all circumstances. Code +that wishes to configure access to the GPIO registers needs access to these +registers to do so. Code which simply wishes to read or write GPIO data does not +need access to these registers. + +b) GPIO registers, which allow manipulation of the GPIO signals. In some GPIO +controllers, these registers are exposed via multiple "physical aliases" in +address space, each of which access the same underlying state. See the hardware +documentation for rationale. Any particular GPIO client is expected to access +just one of these physical aliases. + +Tegra HW documentation describes a unified naming convention for all GPIOs +implemented by the SoC. Each GPIO is assigned to a port, and a port may control +a number of GPIOs. Thus, each GPIO is named according to an alphabetical port +name and an integer GPIO name within the port. For example, GPIO_PA0, GPIO_PN6, +or GPIO_PCC3. + +The number of ports implemented by each GPIO controller varies. The number of +implemented GPIOs within each port varies. GPIO registers within a controller +are grouped and laid out according to the port they affect. + +The mapping from port name to the GPIO controller that implements that port, and +the mapping from port name to register offset within a controller, are both +extremely non-linear. The header file <dt-bindings/gpio/tegra186-gpio.h> +describes the port-level mapping. In that file, the naming convention for ports +matches the HW documentation. The values chosen for the names are alphabetically +sorted within a particular controller. Drivers need to map between the DT GPIO +IDs and HW register offsets using a lookup table. + +Each GPIO controller can generate a number of interrupt signals. Each signal +represents the aggregate status for all GPIOs within a set of ports. Thus, the +number of interrupt signals generated by a controller varies as a rough function +of the number of ports it implements. Note that the HW documentation refers to +both the overall controller HW module and the sets-of-ports as "controllers". + +Each GPIO controller in fact generates multiple interrupts signals for each set +of ports. Each GPIO may be configured to feed into a specific one of the +interrupt signals generated by a set-of-ports. The intent is for each generated +signal to be routed to a different CPU, thus allowing different CPUs to each +handle subsets of the interrupts within a port. The status of each of these +per-port-set signals is reported via a separate register. Thus, a driver needs +to know which status register to observe. This binding currently defines no +configuration mechanism for this. By default, drivers should use register +GPIO_${port}_INTERRUPT_STATUS_G1_0. Future revisions to the binding could +define a property to configure this. + +Required properties: +- compatible + Array of strings. + One of: + - "nvidia,tegra186-gpio". + - "nvidia,tegra186-gpio-aon". +- reg-names + Array of strings. + Contains a list of names for the register spaces described by the reg + property. May contain the following entries, in any order: + - "gpio": Mandatory. GPIO control registers. This may cover either: + a) The single physical alias that this OS should use. + b) All physical aliases that exist in the controller. This is + appropriate when the OS is responsible for managing assignment of + the physical aliases. + - "security": Optional. Security configuration registers. + Users of this binding MUST look up entries in the reg property by name, + using this reg-names property to do so. +- reg + Array of (physical base address, length) tuples. + Must contain one entry per entry in the reg-names property, in a matching + order. +- interrupts + Array of interrupt specifiers. + The interrupt outputs from the HW block, one per set of ports, in the + order the HW manual describes them. The number of entries required varies + depending on compatible value: + - "nvidia,tegra186-gpio": 6 entries. + - "nvidia,tegra186-gpio-aon": 1 entry. +- gpio-controller + Boolean. + Marks the device node as a GPIO controller/provider. +- #gpio-cells + Single-cell integer. + Must be <2>. + Indicates how many cells are used in a consumer's GPIO specifier. + In the specifier: + - The first cell is the pin number. + See <dt-bindings/gpio/tegra186-gpio.h>. + - The second cell contains flags: + - Bit 0 specifies polarity + - 0: Active-high (normal). + - 1: Active-low (inverted). +- interrupt-controller + Boolean. + Marks the device node as an interrupt controller/provider. +- #interrupt-cells + Single-cell integer. + Must be <2>. + Indicates how many cells are used in a consumer's interrupt specifier. + In the specifier: + - The first cell is the GPIO number. + See <dt-bindings/gpio/tegra186-gpio.h>. + - The second cell is contains flags: + - Bits [3:0] indicate trigger type and level: + - 1: Low-to-high edge triggered. + - 2: High-to-low edge triggered. + - 4: Active high level-sensitive. + - 8: Active low level-sensitive. + Valid combinations are 1, 2, 3, 4, 8. + +Example: + +#include <dt-bindings/interrupt-controller/irq.h> + +gpio@2200000 { + compatible = "nvidia,tegra186-gpio"; + reg-names = "security", "gpio"; + reg = + <0x0 0x2200000 0x0 0x10000>, + <0x0 0x2210000 0x0 0x10000>; + interrupts = + <0 47 IRQ_TYPE_LEVEL_HIGH>, + <0 50 IRQ_TYPE_LEVEL_HIGH>, + <0 53 IRQ_TYPE_LEVEL_HIGH>, + <0 56 IRQ_TYPE_LEVEL_HIGH>, + <0 59 IRQ_TYPE_LEVEL_HIGH>, + <0 180 IRQ_TYPE_LEVEL_HIGH>; + gpio-controller; + #gpio-cells = <2>; + interrupt-controller; + #interrupt-cells = <2>; +}; + +gpio@c2f0000 { + compatible = "nvidia,tegra186-gpio-aon"; + reg-names = "security", "gpio"; + reg = + <0x0 0xc2f0000 0x0 0x1000>, + <0x0 0xc2f1000 0x0 0x1000>; + interrupts = + <0 60 IRQ_TYPE_LEVEL_HIGH>; + gpio-controller; + #gpio-cells = <2>; + interrupt-controller; + #interrupt-cells = <2>; +}; diff --git a/roms/u-boot/doc/device-tree-bindings/gpio/nvidia,tegra20-gpio.txt b/roms/u-boot/doc/device-tree-bindings/gpio/nvidia,tegra20-gpio.txt new file mode 100644 index 000000000..023c9526e --- /dev/null +++ b/roms/u-boot/doc/device-tree-bindings/gpio/nvidia,tegra20-gpio.txt @@ -0,0 +1,40 @@ +NVIDIA Tegra GPIO controller + +Required properties: +- compatible : "nvidia,tegra<chip>-gpio" +- reg : Physical base address and length of the controller's registers. +- interrupts : The interrupt outputs from the controller. For Tegra20, + there should be 7 interrupts specified, and for Tegra30, there should + be 8 interrupts specified. +- #gpio-cells : Should be two. The first cell is the pin number and the + second cell is used to specify optional parameters: + - bit 0 specifies polarity (0 for normal, 1 for inverted) +- gpio-controller : Marks the device node as a GPIO controller. +- #interrupt-cells : Should be 2. + The first cell is the GPIO number. + The second cell is used to specify flags: + bits[3:0] trigger type and level flags: + 1 = low-to-high edge triggered. + 2 = high-to-low edge triggered. + 4 = active high level-sensitive. + 8 = active low level-sensitive. + Valid combinations are 1, 2, 3, 4, 8. +- interrupt-controller : Marks the device node as an interrupt controller. + +Example: + +gpio: gpio@6000d000 { + compatible = "nvidia,tegra20-gpio"; + reg = < 0x6000d000 0x1000 >; + interrupts = < 0 32 0x04 + 0 33 0x04 + 0 34 0x04 + 0 35 0x04 + 0 55 0x04 + 0 87 0x04 + 0 89 0x04 >; + #gpio-cells = <2>; + gpio-controller; + #interrupt-cells = <2>; + interrupt-controller; +}; diff --git a/roms/u-boot/doc/device-tree-bindings/gpio/pm8916_gpio.txt b/roms/u-boot/doc/device-tree-bindings/gpio/pm8916_gpio.txt new file mode 100644 index 000000000..58185b833 --- /dev/null +++ b/roms/u-boot/doc/device-tree-bindings/gpio/pm8916_gpio.txt @@ -0,0 +1,48 @@ +Driver for part of pm8916 PMIC - gpio and power/reset keys + +This device should be child of SPMI pmic. + +1) GPIO driver + +Required properties: +- compatible: "qcom,pm8916-gpio" +- reg: peripheral ID, size of register block +- gpio-controller +- gpio-count: number of GPIOs +- #gpio-cells: 2 + +Optional properties: +- gpio-bank-name: name of bank (as default "pm8916" is used) + +Example: + +pmic_gpios: gpios@c000 { + compatible = "qcom,pm8916-gpio"; + reg = <0xc000 0x400>; + gpio-controller; + gpio-count = <4>; + #gpio-cells = <2>; + gpio-bank-name="pmic"; +}; + + +2) Power/Reset key driver + +Required properties: +- compatible: "qcom,pm8916-pwrkey" +- reg: peripheral ID, size of register block +- gpio-controller +- #gpio-cells: 2 + +Optional properties: +- gpio-bank-name: name of bank (as default "pm8916_key" is used) + + +Example: + +pmic_pon: pon@800 { + compatible = "qcom,pm8916-pwrkey"; + reg = <0x800 0x96>; + #gpio-cells = <2>; + gpio-controller; +}; diff --git a/roms/u-boot/doc/device-tree-bindings/gpio/snps,creg-gpio.txt b/roms/u-boot/doc/device-tree-bindings/gpio/snps,creg-gpio.txt new file mode 100644 index 000000000..46ceb65c5 --- /dev/null +++ b/roms/u-boot/doc/device-tree-bindings/gpio/snps,creg-gpio.txt @@ -0,0 +1,43 @@ +GPIO via CREG (control registers) driver + +31 9 7 5 0 < bit number +| | | | | +[ not used | gpio-1 | gpio-0 | <-shift-> ] < 32 bit register + ^ ^ + | | + write 0x2 == set output to "1" (activate) + write 0x3 == set output to "0" (deactivate) + +Required properties: +- compatible : "snps,creg-gpio" +- reg : Exactly one register range with length 0x4. +- #gpio-cells : Should be one - the pin number. +- gpio-controller : Marks the device node as a GPIO controller. +- gpio-count: Number of GPIO pins. +- gpio-bit-per-line: Number of bits per gpio line (see picture). +- gpio-first-shift: Shift (in bits) of the first GPIO field in register + (see picture). +- gpio-activate-val: Value should be set in corresponding field to set + output to "1" (see picture). Applied to all GPIO ports. +- gpio-deactivate-val: Value should be set in corresponding field to set + output to "0" (see picture). Applied to all GPIO ports. + +Optional properties: +- gpio-bank-name: name of bank (as default driver name is used is used) +- gpio-default-val: array of default output values (must me 0 or 1) + +Example (see picture): + +gpio: gpio@f00014b0 { + compatible = "snps,creg-gpio"; + reg = <0xf00014b0 0x4>; + gpio-controller; + #gpio-cells = <1>; + gpio-bank-name = "hsdk-spi-cs"; + gpio-count = <2>; + gpio-first-shift = <5>; + gpio-bit-per-line = <2>; + gpio-activate-val = <2>; + gpio-deactivate-val = <3>; + gpio-default-val = <1 1>; +}; diff --git a/roms/u-boot/doc/device-tree-bindings/gpu/nvidia,tegra20-host1x.txt b/roms/u-boot/doc/device-tree-bindings/gpu/nvidia,tegra20-host1x.txt new file mode 100644 index 000000000..b48f4ef31 --- /dev/null +++ b/roms/u-boot/doc/device-tree-bindings/gpu/nvidia,tegra20-host1x.txt @@ -0,0 +1,372 @@ +NVIDIA Tegra host1x + +Required properties: +- compatible: "nvidia,tegra<chip>-host1x" +- reg: Physical base address and length of the controller's registers. +- interrupts: The interrupt outputs from the controller. +- #address-cells: The number of cells used to represent physical base addresses + in the host1x address space. Should be 1. +- #size-cells: The number of cells used to represent the size of an address + range in the host1x address space. Should be 1. +- ranges: The mapping of the host1x address space to the CPU address space. +- clocks: Must contain one entry, for the module clock. + See ../clocks/clock-bindings.txt for details. +- resets: Must contain an entry for each entry in reset-names. + See ../reset/reset.txt for details. +- reset-names: Must include the following entries: + - host1x + +The host1x top-level node defines a number of children, each representing one +of the following host1x client modules: + +- mpe: video encoder + + Required properties: + - compatible: "nvidia,tegra<chip>-mpe" + - reg: Physical base address and length of the controller's registers. + - interrupts: The interrupt outputs from the controller. + - clocks: Must contain one entry, for the module clock. + See ../clocks/clock-bindings.txt for details. + - resets: Must contain an entry for each entry in reset-names. + See ../reset/reset.txt for details. + - reset-names: Must include the following entries: + - mpe + +- vi: video input + + Required properties: + - compatible: "nvidia,tegra<chip>-vi" + - reg: Physical base address and length of the controller's registers. + - interrupts: The interrupt outputs from the controller. + - clocks: Must contain one entry, for the module clock. + See ../clocks/clock-bindings.txt for details. + - resets: Must contain an entry for each entry in reset-names. + See ../reset/reset.txt for details. + - reset-names: Must include the following entries: + - vi + +- epp: encoder pre-processor + + Required properties: + - compatible: "nvidia,tegra<chip>-epp" + - reg: Physical base address and length of the controller's registers. + - interrupts: The interrupt outputs from the controller. + - clocks: Must contain one entry, for the module clock. + See ../clocks/clock-bindings.txt for details. + - resets: Must contain an entry for each entry in reset-names. + See ../reset/reset.txt for details. + - reset-names: Must include the following entries: + - epp + +- isp: image signal processor + + Required properties: + - compatible: "nvidia,tegra<chip>-isp" + - reg: Physical base address and length of the controller's registers. + - interrupts: The interrupt outputs from the controller. + - clocks: Must contain one entry, for the module clock. + See ../clocks/clock-bindings.txt for details. + - resets: Must contain an entry for each entry in reset-names. + See ../reset/reset.txt for details. + - reset-names: Must include the following entries: + - isp + +- gr2d: 2D graphics engine + + Required properties: + - compatible: "nvidia,tegra<chip>-gr2d" + - reg: Physical base address and length of the controller's registers. + - interrupts: The interrupt outputs from the controller. + - clocks: Must contain one entry, for the module clock. + See ../clocks/clock-bindings.txt for details. + - resets: Must contain an entry for each entry in reset-names. + See ../reset/reset.txt for details. + - reset-names: Must include the following entries: + - 2d + +- gr3d: 3D graphics engine + + Required properties: + - compatible: "nvidia,tegra<chip>-gr3d" + - reg: Physical base address and length of the controller's registers. + - clocks: Must contain an entry for each entry in clock-names. + See ../clocks/clock-bindings.txt for details. + - clock-names: Must include the following entries: + (This property may be omitted if the only clock in the list is "3d") + - 3d + This MUST be the first entry. + - 3d2 (Only required on SoCs with two 3D clocks) + - resets: Must contain an entry for each entry in reset-names. + See ../reset/reset.txt for details. + - reset-names: Must include the following entries: + - 3d + - 3d2 (Only required on SoCs with two 3D clocks) + +- dc: display controller + + Required properties: + - compatible: "nvidia,tegra<chip>-dc" + - reg: Physical base address and length of the controller's registers. + - interrupts: The interrupt outputs from the controller. + - clocks: Must contain an entry for each entry in clock-names. + See ../clocks/clock-bindings.txt for details. + - clock-names: Must include the following entries: + - dc + This MUST be the first entry. + - parent + - resets: Must contain an entry for each entry in reset-names. + See ../reset/reset.txt for details. + - reset-names: Must include the following entries: + - dc + - nvidia,head: The number of the display controller head. This is used to + setup the various types of output to receive video data from the given + head. + + Each display controller node has a child node, named "rgb", that represents + the RGB output associated with the controller. It can take the following + optional properties: + - nvidia,ddc-i2c-bus: phandle of an I2C controller used for DDC EDID probing + - nvidia,hpd-gpio: specifies a GPIO used for hotplug detection + - nvidia,edid: supplies a binary EDID blob + - nvidia,panel: phandle of a display panel + +- hdmi: High Definition Multimedia Interface + + Required properties: + - compatible: "nvidia,tegra<chip>-hdmi" + - reg: Physical base address and length of the controller's registers. + - interrupts: The interrupt outputs from the controller. + - hdmi-supply: supply for the +5V HDMI connector pin + - vdd-supply: regulator for supply voltage + - pll-supply: regulator for PLL + - clocks: Must contain an entry for each entry in clock-names. + See ../clocks/clock-bindings.txt for details. + - clock-names: Must include the following entries: + - hdmi + This MUST be the first entry. + - parent + - resets: Must contain an entry for each entry in reset-names. + See ../reset/reset.txt for details. + - reset-names: Must include the following entries: + - hdmi + + Optional properties: + - nvidia,ddc-i2c-bus: phandle of an I2C controller used for DDC EDID probing + - nvidia,hpd-gpio: specifies a GPIO used for hotplug detection + - nvidia,edid: supplies a binary EDID blob + - nvidia,panel: phandle of a display panel + +- tvo: TV encoder output + + Required properties: + - compatible: "nvidia,tegra<chip>-tvo" + - reg: Physical base address and length of the controller's registers. + - interrupts: The interrupt outputs from the controller. + - clocks: Must contain one entry, for the module clock. + See ../clocks/clock-bindings.txt for details. + +- dsi: display serial interface + + Required properties: + - compatible: "nvidia,tegra<chip>-dsi" + - reg: Physical base address and length of the controller's registers. + - clocks: Must contain an entry for each entry in clock-names. + See ../clocks/clock-bindings.txt for details. + - clock-names: Must include the following entries: + - dsi + This MUST be the first entry. + - lp + - parent + - resets: Must contain an entry for each entry in reset-names. + See ../reset/reset.txt for details. + - reset-names: Must include the following entries: + - dsi + - avdd-dsi-supply: phandle of a supply that powers the DSI controller + - nvidia,mipi-calibrate: Should contain a phandle and a specifier specifying + which pads are used by this DSI output and need to be calibrated. See also + ../mipi/nvidia,tegra114-mipi.txt. + + Optional properties: + - nvidia,ddc-i2c-bus: phandle of an I2C controller used for DDC EDID probing + - nvidia,hpd-gpio: specifies a GPIO used for hotplug detection + - nvidia,edid: supplies a binary EDID blob + - nvidia,panel: phandle of a display panel + +- sor: serial output resource + + Required properties: + - compatible: "nvidia,tegra124-sor" + - reg: Physical base address and length of the controller's registers. + - interrupts: The interrupt outputs from the controller. + - clocks: Must contain an entry for each entry in clock-names. + See ../clocks/clock-bindings.txt for details. + - clock-names: Must include the following entries: + - sor: clock input for the SOR hardware + - parent: input for the pixel clock + - dp: reference clock for the SOR clock + - safe: safe reference for the SOR clock during power up + - resets: Must contain an entry for each entry in reset-names. + See ../reset/reset.txt for details. + - reset-names: Must include the following entries: + - sor + + Optional properties: + - nvidia,ddc-i2c-bus: phandle of an I2C controller used for DDC EDID probing + - nvidia,hpd-gpio: specifies a GPIO used for hotplug detection + - nvidia,edid: supplies a binary EDID blob + - nvidia,panel: phandle of a display panel + + Optional properties when driving an eDP output: + - nvidia,dpaux: phandle to a DispayPort AUX interface + +- dpaux: DisplayPort AUX interface + - compatible: "nvidia,tegra124-dpaux" + - reg: Physical base address and length of the controller's registers. + - interrupts: The interrupt outputs from the controller. + - clocks: Must contain an entry for each entry in clock-names. + See ../clocks/clock-bindings.txt for details. + - clock-names: Must include the following entries: + - dpaux: clock input for the DPAUX hardware + - parent: reference clock + - resets: Must contain an entry for each entry in reset-names. + See ../reset/reset.txt for details. + - reset-names: Must include the following entries: + - dpaux + - vdd-supply: phandle of a supply that powers the DisplayPort link + +Example: + +/ { + ... + + host1x { + compatible = "nvidia,tegra20-host1x", "simple-bus"; + reg = <0x50000000 0x00024000>; + interrupts = <0 65 0x04 /* mpcore syncpt */ + 0 67 0x04>; /* mpcore general */ + clocks = <&tegra_car TEGRA20_CLK_HOST1X>; + resets = <&tegra_car 28>; + reset-names = "host1x"; + + #address-cells = <1>; + #size-cells = <1>; + + ranges = <0x54000000 0x54000000 0x04000000>; + + mpe { + compatible = "nvidia,tegra20-mpe"; + reg = <0x54040000 0x00040000>; + interrupts = <0 68 0x04>; + clocks = <&tegra_car TEGRA20_CLK_MPE>; + resets = <&tegra_car 60>; + reset-names = "mpe"; + }; + + vi { + compatible = "nvidia,tegra20-vi"; + reg = <0x54080000 0x00040000>; + interrupts = <0 69 0x04>; + clocks = <&tegra_car TEGRA20_CLK_VI>; + resets = <&tegra_car 100>; + reset-names = "vi"; + }; + + epp { + compatible = "nvidia,tegra20-epp"; + reg = <0x540c0000 0x00040000>; + interrupts = <0 70 0x04>; + clocks = <&tegra_car TEGRA20_CLK_EPP>; + resets = <&tegra_car 19>; + reset-names = "epp"; + }; + + isp { + compatible = "nvidia,tegra20-isp"; + reg = <0x54100000 0x00040000>; + interrupts = <0 71 0x04>; + clocks = <&tegra_car TEGRA20_CLK_ISP>; + resets = <&tegra_car 23>; + reset-names = "isp"; + }; + + gr2d { + compatible = "nvidia,tegra20-gr2d"; + reg = <0x54140000 0x00040000>; + interrupts = <0 72 0x04>; + clocks = <&tegra_car TEGRA20_CLK_GR2D>; + resets = <&tegra_car 21>; + reset-names = "2d"; + }; + + gr3d { + compatible = "nvidia,tegra20-gr3d"; + reg = <0x54180000 0x00040000>; + clocks = <&tegra_car TEGRA20_CLK_GR3D>; + resets = <&tegra_car 24>; + reset-names = "3d"; + }; + + dc@54200000 { + compatible = "nvidia,tegra20-dc"; + reg = <0x54200000 0x00040000>; + interrupts = <0 73 0x04>; + clocks = <&tegra_car TEGRA20_CLK_DISP1>, + <&tegra_car TEGRA20_CLK_PLL_P>; + clock-names = "dc", "parent"; + resets = <&tegra_car 27>; + reset-names = "dc"; + + rgb { + status = "disabled"; + }; + }; + + dc@54240000 { + compatible = "nvidia,tegra20-dc"; + reg = <0x54240000 0x00040000>; + interrupts = <0 74 0x04>; + clocks = <&tegra_car TEGRA20_CLK_DISP2>, + <&tegra_car TEGRA20_CLK_PLL_P>; + clock-names = "dc", "parent"; + resets = <&tegra_car 26>; + reset-names = "dc"; + + rgb { + status = "disabled"; + }; + }; + + hdmi { + compatible = "nvidia,tegra20-hdmi"; + reg = <0x54280000 0x00040000>; + interrupts = <0 75 0x04>; + clocks = <&tegra_car TEGRA20_CLK_HDMI>, + <&tegra_car TEGRA20_CLK_PLL_D_OUT0>; + clock-names = "hdmi", "parent"; + resets = <&tegra_car 51>; + reset-names = "hdmi"; + status = "disabled"; + }; + + tvo { + compatible = "nvidia,tegra20-tvo"; + reg = <0x542c0000 0x00040000>; + interrupts = <0 76 0x04>; + clocks = <&tegra_car TEGRA20_CLK_TVO>; + status = "disabled"; + }; + + dsi { + compatible = "nvidia,tegra20-dsi"; + reg = <0x54300000 0x00040000>; + clocks = <&tegra_car TEGRA20_CLK_DSI>, + <&tegra_car TEGRA20_CLK_PLL_D_OUT0>; + clock-names = "dsi", "parent"; + resets = <&tegra_car 48>; + reset-names = "dsi"; + status = "disabled"; + }; + }; + + ... +}; diff --git a/roms/u-boot/doc/device-tree-bindings/i2c/generic-acpi.txt b/roms/u-boot/doc/device-tree-bindings/i2c/generic-acpi.txt new file mode 100644 index 000000000..3510a71b5 --- /dev/null +++ b/roms/u-boot/doc/device-tree-bindings/i2c/generic-acpi.txt @@ -0,0 +1,42 @@ +I2C generic device +================== + +This is used only to generate ACPI tables for an I2C device. + +Required properties : + + - compatible : "i2c-chip"; + - reg : I2C chip address + - acpi,hid : HID name for the device + +Optional properies in addition to device.txt: + + - reset-gpios : GPIO used to assert reset to the device + - irq-gpios : GPIO used for interrupt (if Interrupt is not used) + - stop-gpios : GPIO used to stop the device + - interrupts-extended : Interrupt to use for the device + - reset-delay-ms : Delay after de-asserting reset, in ms + - reset-off-delay-ms : Delay after asserting reset (during power off) + - enable-delay-ms : Delay after asserting enable + - enable-off-delay-ms : Delay after de-asserting enable (during power off) + - stop-delay-ms : Delay after de-aserting stop + - stop-off-delay-ms : Delay after asserting stop (during power off) + - hid-descr-addr : HID register offset (for Human Interface Devices) + +Example +------- + + elan-touchscreen@10 { + compatible = "i2c-chip"; + reg = <0x10>; + acpi,hid = "ELAN0001"; + acpi,ddn = "ELAN Touchscreen"; + interrupts-extended = <&acpi_gpe GPIO_21_IRQ + IRQ_TYPE_EDGE_FALLING>; + linux,probed; + reset-gpios = <&gpio_n GPIO_36 GPIO_ACTIVE_HIGH>; + reset-delay-ms = <20>; + enable-gpios = <&gpio_n GPIO_152 GPIO_ACTIVE_HIGH>; + enable-delay-ms = <1>; + acpi,has-power-resource; + }; diff --git a/roms/u-boot/doc/device-tree-bindings/i2c/i2c-at91.txt b/roms/u-boot/doc/device-tree-bindings/i2c/i2c-at91.txt new file mode 100644 index 000000000..2065b7341 --- /dev/null +++ b/roms/u-boot/doc/device-tree-bindings/i2c/i2c-at91.txt @@ -0,0 +1,26 @@ +I2C for Atmel platforms + +Required properties : +- compatible : Must be "atmel,at91rm9200-i2c", "atmel,at91sam9261-i2c", + "atmel,at91sam9260-i2c", "atmel,at91sam9g20-i2c", "atmel,at91sam9g10-i2c", + "atmel,at91sam9x5-i2c", "atmel,sama5d4-i2c" or "atmel,sama5d2-i2c". +- reg: physical base address of the controller and length of memory mapped + region. +- #address-cells = <1>; +- #size-cells = <0>; +- clocks: phandles to input clocks. + +Optional properties: +- clock-frequency: Desired I2C bus frequency in Hz, default value is 100000. +- Child nodes conforming to i2c bus binding. + +Examples : + +i2c0: i2c@f8028000 { + compatible = "atmel,sama5d2-i2c"; + reg = <0xf8028000 0x100>; + #address-cells = <1>; + #size-cells = <0>; + clocks = <&twi0_clk>; + clock-frequency = <100000>; +}; diff --git a/roms/u-boot/doc/device-tree-bindings/i2c/i2c-cdns.txt b/roms/u-boot/doc/device-tree-bindings/i2c/i2c-cdns.txt new file mode 100644 index 000000000..202e0b762 --- /dev/null +++ b/roms/u-boot/doc/device-tree-bindings/i2c/i2c-cdns.txt @@ -0,0 +1,20 @@ +Cadence I2C controller Device Tree Bindings +------------------------------------------- + +Required properties: +- compatible : Should be "cdns,i2c-r1p10" or "xlnx,zynq-spi-r1p10". +- reg : Physical base address and size of I2C registers map. +- interrupts : Property with a value describing the interrupt + number. +- interrupt-parent : Must be core interrupt controller +- clocks : Clock phandles (see clock bindings for details). + +Example: + i2c0: i2c@e0004000 { + compatible = "cdns,i2c-r1p10"; + reg = <0xe0004000 0x1000>; + clocks = <&clkc 38>; + interrupts = <0 25 4>; + interrupt-parent = <&intc>; + status = "disabled"; + }; diff --git a/roms/u-boot/doc/device-tree-bindings/i2c/i2c-cortina.txt b/roms/u-boot/doc/device-tree-bindings/i2c/i2c-cortina.txt new file mode 100644 index 000000000..59d523582 --- /dev/null +++ b/roms/u-boot/doc/device-tree-bindings/i2c/i2c-cortina.txt @@ -0,0 +1,18 @@ +* I2C for Cortina platforms + +Required properties : +- compatible : Must be "cortina,ca-i2c" +- reg : Offset and length of the register set for the device + +Recommended properties : +- clock-frequency : desired I2C bus clock frequency in Hz. If not specified, + default value is 100000. Possible values are 100000, + 400000 and 1000000. + +Examples : + + i2c: i2c@f4329120 { + compatible = "cortina,ca-i2c"; + reg = <0x0 0xf4329120 0x28>; + clock-frequency = <400000>; + }; diff --git a/roms/u-boot/doc/device-tree-bindings/i2c/i2c-designware.txt b/roms/u-boot/doc/device-tree-bindings/i2c/i2c-designware.txt new file mode 100644 index 000000000..be766be81 --- /dev/null +++ b/roms/u-boot/doc/device-tree-bindings/i2c/i2c-designware.txt @@ -0,0 +1,73 @@ +* Synopsys DesignWare I2C + +Required properties : + + - compatible : should be "snps,designware-i2c" + or "mscc,ocelot-i2c" with "snps,designware-i2c" for fallback + - reg : Offset and length of the register set for the device + - interrupts : <IRQ> where IRQ is the interrupt number. + - clocks : phandles for the clocks, see the description of clock-names below. + The phandle for the "ic_clk" clock is required. The phandle for the "pclk" + clock is optional. If a single clock is specified but no clock-name, it is + the "ic_clk" clock. If both clocks are listed, the "ic_clk" must be first. + +Recommended properties : + + - clock-frequency : desired I2C bus clock frequency in Hz. + +Optional properties : + + - clock-names : Contains the names of the clocks: + "ic_clk", for the core clock used to generate the external I2C clock. + "pclk", the interface clock, required for register access. + + - reg : for "mscc,ocelot-i2c", a second register set to configure the SDA hold + time, named ICPU_CFG:TWI_DELAY in the datasheet. + + - i2c-sda-hold-time-ns : should contain the SDA hold time in nanoseconds. + This option is only supported in hardware blocks version 1.11a or newer and + on Microsemi SoCs ("mscc,ocelot-i2c" compatible). + + - i2c-scl-falling-time-ns : should contain the SCL falling time in nanoseconds. + This value which is by default 300ns is used to compute the tLOW period. + + - i2c-sda-falling-time-ns : should contain the SDA falling time in nanoseconds. + This value which is by default 300ns is used to compute the tHIGH period. + +Examples : + + i2c@f0000 { + #address-cells = <1>; + #size-cells = <0>; + compatible = "snps,designware-i2c"; + reg = <0xf0000 0x1000>; + interrupts = <11>; + clock-frequency = <400000>; + }; + + i2c@1120000 { + #address-cells = <1>; + #size-cells = <0>; + compatible = "snps,designware-i2c"; + reg = <0x1120000 0x1000>; + interrupt-parent = <&ictl>; + interrupts = <12 1>; + clock-frequency = <400000>; + i2c-sda-hold-time-ns = <300>; + i2c-sda-falling-time-ns = <300>; + i2c-scl-falling-time-ns = <300>; + };x + + i2c@1120000 { + #address-cells = <1>; + #size-cells = <0>; + reg = <0x2000 0x100>; + clock-frequency = <400000>; + clocks = <&i2cclk>; + interrupts = <0>; + + eeprom@64 { + compatible = "linux,slave-24c02"; + reg = <0x40000064>; + }; + }; diff --git a/roms/u-boot/doc/device-tree-bindings/i2c/i2c-gpio.txt b/roms/u-boot/doc/device-tree-bindings/i2c/i2c-gpio.txt new file mode 100644 index 000000000..b06b82993 --- /dev/null +++ b/roms/u-boot/doc/device-tree-bindings/i2c/i2c-gpio.txt @@ -0,0 +1,41 @@ +I2C gpio device binding +======================= + +Driver: +- drivers/i2c/i2c-gpio.c + +Software i2c device-tree node properties: +Required: +* #address-cells = <1>; +* #size-cells = <0>; +* compatible = "i2c-gpio"; +* gpios = <sda ...>, <scl ...>; + +Optional: +* i2c-gpio,delay-us = <5>; + The resulting transfer speed can be adjusted by setting the delay[us] + between gpio-toggle operations. Speed [Hz] = 1000000 / 4 * udelay[us], + It not defined, then default is 5us (~50KHz). +* i2c-gpio,deblock + Run deblocking sequence when the driver gets probed. +* i2c-gpio,scl-output-only; + Set if SCL is an output only + +Example: + +i2c-gpio@1 { + #address-cells = <1>; + #size-cells = <0>; + + compatible = "i2c-gpio"; + gpios = <&gpd1 0 GPIO_ACTIVE_HIGH>, /* SDA */ + <&gpd1 1 GPIO_ACTIVE_HIGH>; /* CLK */ + + i2c-gpio,delay-us = <5>; + + some_device@5 { + compatible = "some_device"; + reg = <0x5>; + ... + }; +}; diff --git a/roms/u-boot/doc/device-tree-bindings/i2c/i2c-mux.txt b/roms/u-boot/doc/device-tree-bindings/i2c/i2c-mux.txt new file mode 100644 index 000000000..af84cce5c --- /dev/null +++ b/roms/u-boot/doc/device-tree-bindings/i2c/i2c-mux.txt @@ -0,0 +1,60 @@ +Common i2c bus multiplexer/switch properties. + +An i2c bus multiplexer/switch will have several child busses that are +numbered uniquely in a device dependent manner. The nodes for an i2c bus +multiplexer/switch will have one child node for each child +bus. + +Required properties: +- #address-cells = <1>; +- #size-cells = <0>; + +Required properties for child nodes: +- #address-cells = <1>; +- #size-cells = <0>; +- reg : The sub-bus number. + +Optional properties for child nodes: +- Other properties specific to the multiplexer/switch hardware. +- Child nodes conforming to i2c bus binding + + +Example : + + /* + An NXP pca9548 8 channel I2C multiplexer at address 0x70 + with two NXP pca8574 GPIO expanders attached, one each to + ports 3 and 4. + */ + + mux@70 { + compatible = "nxp,pca9548"; + reg = <0x70>; + #address-cells = <1>; + #size-cells = <0>; + + i2c@3 { + #address-cells = <1>; + #size-cells = <0>; + reg = <3>; + + gpio1: gpio@38 { + compatible = "nxp,pca8574"; + reg = <0x38>; + #gpio-cells = <2>; + gpio-controller; + }; + }; + i2c@4 { + #address-cells = <1>; + #size-cells = <0>; + reg = <4>; + + gpio2: gpio@38 { + compatible = "nxp,pca8574"; + reg = <0x38>; + #gpio-cells = <2>; + gpio-controller; + }; + }; + }; diff --git a/roms/u-boot/doc/device-tree-bindings/i2c/i2c-stm32.txt b/roms/u-boot/doc/device-tree-bindings/i2c/i2c-stm32.txt new file mode 100644 index 000000000..df03743ac --- /dev/null +++ b/roms/u-boot/doc/device-tree-bindings/i2c/i2c-stm32.txt @@ -0,0 +1,30 @@ +* I2C controller embedded in STMicroelectronis STM32 platforms + +Required properties : +- compatible : Must be "st,stm32f7-i2c" +- reg : Offset and length of the register set for the device +- resets: Must contain the phandle to the reset controller +- clocks: Must contain the input clock of the I2C instance +- A pinctrl state named "default" must be defined to set pins in mode of + operation for I2C transfer +- #address-cells = <1>; +- #size-cells = <0>; + +Optional properties : +- clock-frequency : Desired I2C bus clock frequency in Hz. If not specified, + the default 100 kHz frequency will be used. As only Normal, Fast and Fast+ + modes are implemented, possible values are 100000, 400000 and 1000000. + +Example : + + i2c1: i2c@40005400 { + compatible = "st,stm32f7-i2c"; + reg = <0x40005400 0x400>; + resets = <&rcc 181>; + clocks = <&clk_pclk1>; + pinctrl-names = "default"; + pinctrl-0 = <&pinctrl_i2c1>; + clock-frequency = <400000>; + #address-cells = <1>; + #size-cells = <0>; + }; diff --git a/roms/u-boot/doc/device-tree-bindings/i2c/i2c.txt b/roms/u-boot/doc/device-tree-bindings/i2c/i2c.txt new file mode 100644 index 000000000..9698e4899 --- /dev/null +++ b/roms/u-boot/doc/device-tree-bindings/i2c/i2c.txt @@ -0,0 +1,46 @@ +U-Boot I2C +---------- + +U-Boot's I2C model has the concept of an offset within a chip (I2C target +device). The offset can be up to 4 bytes long, but is normally 1 byte, +meaning that offsets from 0 to 255 are supported by the chip. This often +corresponds to register numbers. + +Apart from the controller-specific I2C bindings, U-Boot supports a special +property which allows the chip offset length to be selected. + +Optional properties: +- u-boot,i2c-offset-len - length of chip offset in bytes. If omitted the + default value of 1 is used. +- u-boot,i2c-transaction-bytes - the length of single I2C transaction on + the bus. Some devices require more than single byte transmission + (e.g. mc34708 mfd). This information is necessary to correctly + initialize (put into idle state) I2C bus after soft reset. +- gpios = <sda ...>, <scl ...>; + pinctrl-names = "default", "gpio"; + pinctrl-0 = <&i2c_xfer>; + pinctrl-1 = <&i2c_gpio>; + Pin description for I2C bus software deblocking. + + +Example +------- + +i2c4: i2c@12ca0000 { + cros-ec@1e { + reg = <0x1e>; + compatible = "google,cros-ec"; + i2c-max-frequency = <100000>; + u-boot,i2c-offset-len = <0>; + u-boot,i2c-transaction-bytes = <3>; + ec-interrupt = <&gpx1 6 GPIO_ACTIVE_LOW>; + }; +}; + +&i2c1 { + pinctrl-names = "default", "gpio"; + pinctrl-0 = <&i2c1_xfer>; + pinctrl-1 = <&i2c1_gpio>; + gpios = <&gpio1 26 GPIO_ACTIVE_LOW>, /* SDA */ + <&gpio1 27 GPIO_ACTIVE_LOW>; /* SCL */ +}; diff --git a/roms/u-boot/doc/device-tree-bindings/i2c/nvidia,tegra186-bpmp-i2c.txt b/roms/u-boot/doc/device-tree-bindings/i2c/nvidia,tegra186-bpmp-i2c.txt new file mode 100644 index 000000000..ab240e10d --- /dev/null +++ b/roms/u-boot/doc/device-tree-bindings/i2c/nvidia,tegra186-bpmp-i2c.txt @@ -0,0 +1,42 @@ +NVIDIA Tegra186 BPMP I2C controller + +In Tegra186, the BPMP (Boot and Power Management Processor) owns certain HW +devices, such as the I2C controller for the power management I2C bus. Software +running on other CPUs must perform IPC to the BPMP in order to execute +transactions on that I2C bus. This binding describes an I2C bus that is +accessed in such a fashion. + +The BPMP I2C node must be located directly inside the main BPMP node. See +../firmware/nvidia,tegra186-bpmp.txt for details of the BPMP binding. + +This node represents an I2C controller. See ../i2c/i2c.txt for details of the +core I2C binding. + +Required properties: +- compatible: + Array of strings. + One of: + - "nvidia,tegra186-bpmp-i2c". +- #address-cells: Address cells for I2C device address. + Single-cell integer. + Must be <1>. +- #size-cells: + Single-cell integer. + Must be <0>. +- nvidia,bpmp-bus-id: + Single-cell integer. + Indicates the I2C bus number this DT node represent, as defined by the + BPMP firmware. + +Example: + +bpmp { + ... + + i2c { + compatible = "nvidia,tegra186-bpmp-i2c"; + #address-cells = <1>; + #size-cells = <0>; + nvidia,bpmp-bus-id = <5>; + }; +}; diff --git a/roms/u-boot/doc/device-tree-bindings/i2c/nx_i2c.txt b/roms/u-boot/doc/device-tree-bindings/i2c/nx_i2c.txt new file mode 100644 index 000000000..9f3abe78e --- /dev/null +++ b/roms/u-boot/doc/device-tree-bindings/i2c/nx_i2c.txt @@ -0,0 +1,28 @@ +I2C controller embedded in Nexell's/Samsung's SoC S5P4418 and S5P6818 + +Driver: +- drivers/i2c/nx_i2c.c + +Required properties: +- #address-cells = <1>; +- #size-cells = <0>; +- compatible = "nexell,s5pxx18-i2c"; +- reg = <i2c_base 0x100>; + Where i2c_base has to be the base address of the i2c-register set. + I2C0: 0xc00a4000 + I2C1: 0xc00a5000 + I2C2: 0xc00a6000 + +Optional properties: +- clock-frequency: Desired I2C bus frequency in Hz, default value is 100000. +- i2c-sda-delay-ns (S5P6818 only): SDA delay in ns, default value is 0. +- Child nodes conforming to i2c bus binding. + +Example: + i2c0:i2c@c00a4000 { + #address-cells = <1>; + #size-cells = <0>; + compatible = "nexell,s5pxx18-i2c"; + reg = <0xc00a4000 0x100>; + clock-frequency = <400000>; + }; diff --git a/roms/u-boot/doc/device-tree-bindings/i2c/octeon-i2c.txt b/roms/u-boot/doc/device-tree-bindings/i2c/octeon-i2c.txt new file mode 100644 index 000000000..9c1908ec2 --- /dev/null +++ b/roms/u-boot/doc/device-tree-bindings/i2c/octeon-i2c.txt @@ -0,0 +1,24 @@ +* I2C controller embedded in Marvell Octeon platforms + +Required properties : +- compatible : Must be "cavium,octeon-7890-twsi" or a compatible string +- reg : Offset and length of the register set for the device +- clocks: Must contain the input clock of the I2C instance +- #address-cells = <1>; +- #size-cells = <0>; + +Optional properties : +- clock-frequency : Desired I2C bus clock frequency in Hz. If not specified, + the default 100 kHz frequency will be used. As only Normal, Fast and Fast+ + modes are implemented, possible values are 100000, 400000 and 1000000. + +Example : + + i2c0: i2c@1180000001000 { + #address-cells = <1>; + #size-cells = <0>; + compatible = "cavium,octeon-7890-twsi"; + reg = <0x11800 0x00001000 0x0 0x200>; + clock-frequency = <100000>; + clocks = <&sclk>; + }; diff --git a/roms/u-boot/doc/device-tree-bindings/i2c/tegra20-i2c.txt b/roms/u-boot/doc/device-tree-bindings/i2c/tegra20-i2c.txt new file mode 100644 index 000000000..72649dffa --- /dev/null +++ b/roms/u-boot/doc/device-tree-bindings/i2c/tegra20-i2c.txt @@ -0,0 +1,23 @@ +(Placeholder note while we locate the kernel Tegra20 bindings) + +Added in U-Boot: + +Required properties: + - clocks : Two clocks must be given, each as a phandle to the Tegra's + CAR node and the clock number as a parameter: + - the I2C clock to use for the peripheral + - the pll_p_out3 clock, which can be used for fast operation. This + does not change and is the same for all I2C nodes. + +Example: +(TODO: merge with existing example): + + i2c@7000c400 { + #address-cells = <1>; + #size-cells = <0>; + compatible = "nvidia,tegra20-i2c"; + reg = <0x7000C400 0x100>; + interrupts = < 116 >; + /* PERIPH_ID_I2C2, PLL_P_OUT3 */ + clocks = <&tegra_car 54>, <&tegra_car 124>; + }; diff --git a/roms/u-boot/doc/device-tree-bindings/input/adc-keys.txt b/roms/u-boot/doc/device-tree-bindings/input/adc-keys.txt new file mode 100644 index 000000000..6c8be6a9a --- /dev/null +++ b/roms/u-boot/doc/device-tree-bindings/input/adc-keys.txt @@ -0,0 +1,67 @@ +ADC attached resistor ladder buttons +------------------------------------ + +Required properties: + - compatible: "adc-keys" + - io-channels: Phandle to an ADC channel + - io-channel-names = "buttons"; + - keyup-threshold-microvolt: Voltage above or equal to which all the keys are + considered up. + +Optional properties: + - poll-interval: Poll interval time in milliseconds + - autorepeat: Boolean, Enable auto repeat feature of Linux input + subsystem. + +Each button (key) is represented as a sub-node of "adc-keys": + +Required subnode-properties: + - label: Descriptive name of the key. + - linux,code: Keycode to emit. + - press-threshold-microvolt: voltage above or equal to which this key is + considered pressed. + +No two values of press-threshold-microvolt may be the same. +All values of press-threshold-microvolt must be less than +keyup-threshold-microvolt. + +Example: + +#include <dt-bindings/input/input.h> + + adc-keys { + compatible = "adc-keys"; + io-channels = <&lradc 0>; + io-channel-names = "buttons"; + keyup-threshold-microvolt = <2000000>; + + button-up { + label = "Volume Up"; + linux,code = <KEY_VOLUMEUP>; + press-threshold-microvolt = <1500000>; + }; + + button-down { + label = "Volume Down"; + linux,code = <KEY_VOLUMEDOWN>; + press-threshold-microvolt = <1000000>; + }; + + button-enter { + label = "Enter"; + linux,code = <KEY_ENTER>; + press-threshold-microvolt = <500000>; + }; + }; + ++--------------------------------+------------------------+ +| 2.000.000 <= value | no key pressed | ++--------------------------------+------------------------+ +| 1.500.000 <= value < 2.000.000 | KEY_VOLUMEUP pressed | ++--------------------------------+------------------------+ +| 1.000.000 <= value < 1.500.000 | KEY_VOLUMEDOWN pressed | ++--------------------------------+------------------------+ +| 500.000 <= value < 1.000.000 | KEY_ENTER pressed | ++--------------------------------+------------------------+ +| value < 500.000 | no key pressed | ++--------------------------------+------------------------+ diff --git a/roms/u-boot/doc/device-tree-bindings/input/cros-ec-keyb.txt b/roms/u-boot/doc/device-tree-bindings/input/cros-ec-keyb.txt new file mode 100644 index 000000000..0f6355ce3 --- /dev/null +++ b/roms/u-boot/doc/device-tree-bindings/input/cros-ec-keyb.txt @@ -0,0 +1,72 @@ +ChromeOS EC Keyboard + +Google's ChromeOS EC Keyboard is a simple matrix keyboard implemented on +a separate EC (Embedded Controller) device. It provides a message for reading +key scans from the EC. These are then converted into keycodes for processing +by the kernel. + +This binding is based on matrix-keymap.txt and extends/modifies it as follows: + +Required properties: +- compatible: "google,cros-ec-keyb" + +Optional properties: +- google,needs-ghost-filter: True to enable a ghost filter for the matrix +keyboard. This is recommended if the EC does not have its own logic or +hardware for this. + + +Example: + +cros-ec-keyb { + compatible = "google,cros-ec-keyb"; + keypad,num-rows = <8>; + keypad,num-columns = <13>; + google,needs-ghost-filter; + /* + * Keymap entries take the form of 0xRRCCKKKK where + * RR=Row CC=Column KKKK=Key Code + * The values below are for a US keyboard layout and + * are taken from the Linux driver. Note that the + * 102ND key is not used for US keyboards. + */ + linux,keymap = < + /* CAPSLCK F1 B F10 */ + 0x0001003a 0x0002003b 0x00030030 0x00040044 + /* N = R_ALT ESC */ + 0x00060031 0x0008000d 0x000a0064 0x01010001 + /* F4 G F7 H */ + 0x0102003e 0x01030022 0x01040041 0x01060023 + /* ' F9 BKSPACE L_CTRL */ + 0x01080028 0x01090043 0x010b000e 0x0200001d + /* TAB F3 T F6 */ + 0x0201000f 0x0202003d 0x02030014 0x02040040 + /* ] Y 102ND [ */ + 0x0205001b 0x02060015 0x02070056 0x0208001a + /* F8 GRAVE F2 5 */ + 0x02090042 0x03010029 0x0302003c 0x03030006 + /* F5 6 - \ */ + 0x0304003f 0x03060007 0x0308000c 0x030b002b + /* R_CTRL A D F */ + 0x04000061 0x0401001e 0x04020020 0x04030021 + /* S K J ; */ + 0x0404001f 0x04050025 0x04060024 0x04080027 + /* L ENTER Z C */ + 0x04090026 0x040b001c 0x0501002c 0x0502002e + /* V X , M */ + 0x0503002f 0x0504002d 0x05050033 0x05060032 + /* L_SHIFT / . SPACE */ + 0x0507002a 0x05080035 0x05090034 0x050B0039 + /* 1 3 4 2 */ + 0x06010002 0x06020004 0x06030005 0x06040003 + /* 8 7 0 9 */ + 0x06050009 0x06060008 0x0608000b 0x0609000a + /* L_ALT DOWN RIGHT Q */ + 0x060a0038 0x060b006c 0x060c006a 0x07010010 + /* E R W I */ + 0x07020012 0x07030013 0x07040011 0x07050017 + /* U R_SHIFT P O */ + 0x07060016 0x07070036 0x07080019 0x07090018 + /* UP LEFT */ + 0x070b0067 0x070c0069>; +}; diff --git a/roms/u-boot/doc/device-tree-bindings/input/hid-over-i2c.txt b/roms/u-boot/doc/device-tree-bindings/input/hid-over-i2c.txt new file mode 100644 index 000000000..c76bafaf9 --- /dev/null +++ b/roms/u-boot/doc/device-tree-bindings/input/hid-over-i2c.txt @@ -0,0 +1,44 @@ +* HID over I2C Device-Tree bindings + +HID over I2C provides support for various Human Interface Devices over the +I2C bus. These devices can be for example touchpads, keyboards, touch screens +or sensors. + +The specification has been written by Microsoft and is currently available here: +http://msdn.microsoft.com/en-us/library/windows/hardware/hh852380.aspx + +If this binding is used, the kernel module i2c-hid will handle the communication +with the device and the generic hid core layer will handle the protocol. + +Required properties: +- compatible: must be "hid-over-i2c" +- reg: i2c slave address +- hid-descr-addr: HID descriptor address +- interrupts: interrupt line + +Additional optional properties: + +Some devices may support additional optional properties to help with, e.g., +power sequencing. The following properties can be supported by one or more +device-specific compatible properties, which should be used in addition to the +"hid-over-i2c" string. + +- compatible: + * "wacom,w9013" (Wacom W9013 digitizer). Supports: + - vdd-supply (3.3V) + - vddl-supply (1.8V) + - post-power-on-delay-ms + +- vdd-supply: phandle of the regulator that provides the supply voltage. +- post-power-on-delay-ms: time required by the device after enabling its regulators + or powering it on, before it is ready for communication. + +Example: + + i2c-hid-dev@2c { + compatible = "hid-over-i2c"; + reg = <0x2c>; + hid-descr-addr = <0x0020>; + interrupt-parent = <&gpx3>; + interrupts = <3 2>; + }; diff --git a/roms/u-boot/doc/device-tree-bindings/input/i8042.txt b/roms/u-boot/doc/device-tree-bindings/input/i8042.txt new file mode 100644 index 000000000..cd079c274 --- /dev/null +++ b/roms/u-boot/doc/device-tree-bindings/input/i8042.txt @@ -0,0 +1,10 @@ +i8042 Keyboard + +The Intel i8042 is a keyboard controller used on many x86 PCs. + +Required properties: +- compatible: "intel,i8042-keyboard" + +Optional properties: +- intel,duplicate-por: Indicates that a keyboard reset may result in a + duplicate POR byte, which should be ignored. diff --git a/roms/u-boot/doc/device-tree-bindings/interrupt-controller/intel,acpi-gpe.txt b/roms/u-boot/doc/device-tree-bindings/interrupt-controller/intel,acpi-gpe.txt new file mode 100644 index 000000000..2fe02d8a2 --- /dev/null +++ b/roms/u-boot/doc/device-tree-bindings/interrupt-controller/intel,acpi-gpe.txt @@ -0,0 +1,30 @@ +* Intel Advanced Configuration and Power Interface General Purpose Events + +This describes an interrupt controller which provides access to GPEs supported +by the SoC. + +Required properties: + +- compatible : "intel,acpi-gpe" +- interrupt-controller : Identifies the node as an interrupt controller +- #interrupt-cells : The number of cells to define the interrupts. Must be 2: + cell 0: interrupt number (normally >=32 since GPEs below that are reserved) + cell 1: 0 (flags, but none are currently defined) +- reg : The register bank for the controller (set this to the ACPI base). + +Example: + + general-purpose-events { + reg = <IOMAP_ACPI_BASE IOMAP_ACPI_SIZE>; + compatible = "intel,acpi-gpe"; + interrupt-controller; + #interrupt-cells = <2>; + }; + + ... + tpm@50 { + reg = <0x50>; + compatible = "google,cr50"; + ready-gpios = <&gpio_n 0x1c GPIO_ACTIVE_LOW>; + interrupts-extended = <&acpi_gpe 0x3c 0>; + }; diff --git a/roms/u-boot/doc/device-tree-bindings/interrupt-controller/interrupts.txt b/roms/u-boot/doc/device-tree-bindings/interrupt-controller/interrupts.txt new file mode 100644 index 000000000..38a399a6b --- /dev/null +++ b/roms/u-boot/doc/device-tree-bindings/interrupt-controller/interrupts.txt @@ -0,0 +1,131 @@ +Specifying interrupt information for devices +============================================ + +1) Interrupt client nodes +------------------------- + +Nodes that describe devices which generate interrupts must contain an +"interrupts" property, an "interrupts-extended" property, or both. If both are +present, the latter should take precedence; the former may be provided simply +for compatibility with software that does not recognize the latter. These +properties contain a list of interrupt specifiers, one per output interrupt. The +format of the interrupt specifier is determined by the interrupt controller to +which the interrupts are routed; see section 2 below for details. + + Example: + interrupt-parent = <&intc1>; + interrupts = <5 0>, <6 0>; + +The "interrupt-parent" property is used to specify the controller to which +interrupts are routed and contains a single phandle referring to the interrupt +controller node. This property is inherited, so it may be specified in an +interrupt client node or in any of its parent nodes. Interrupts listed in the +"interrupts" property are always in reference to the node's interrupt parent. + +The "interrupts-extended" property is a special form; useful when a node needs +to reference multiple interrupt parents or a different interrupt parent than +the inherited one. Each entry in this property contains both the parent phandle +and the interrupt specifier. + + Example: + interrupts-extended = <&intc1 5 1>, <&intc2 1 0>; + +(NOTE: only this 'special form' is supported in U-Boot) + + +2) Interrupt controller nodes +----------------------------- + +A device is marked as an interrupt controller with the "interrupt-controller" +property. This is a empty, boolean property. An additional "#interrupt-cells" +property defines the number of cells needed to specify a single interrupt. + +It is the responsibility of the interrupt controller's binding to define the +length and format of the interrupt specifier. The following two variants are +commonly used: + + a) one cell + ----------- + The #interrupt-cells property is set to 1 and the single cell defines the + index of the interrupt within the controller. + + Example: + + vic: intc@10140000 { + compatible = "arm,versatile-vic"; + interrupt-controller; + #interrupt-cells = <1>; + reg = <0x10140000 0x1000>; + }; + + sic: intc@10003000 { + compatible = "arm,versatile-sic"; + interrupt-controller; + #interrupt-cells = <1>; + reg = <0x10003000 0x1000>; + interrupt-parent = <&vic>; + interrupts = <31>; /* Cascaded to vic */ + }; + + b) two cells + ------------ + The #interrupt-cells property is set to 2 and the first cell defines the + index of the interrupt within the controller, while the second cell is used + to specify any of the following flags: + - bits[3:0] trigger type and level flags + 1 = low-to-high edge triggered + 2 = high-to-low edge triggered + 4 = active high level-sensitive + 8 = active low level-sensitive + + Example: + + i2c@7000c000 { + gpioext: gpio-adnp@41 { + compatible = "ad,gpio-adnp"; + reg = <0x41>; + + interrupt-parent = <&gpio>; + interrupts = <160 1>; + + gpio-controller; + #gpio-cells = <1>; + + interrupt-controller; + #interrupt-cells = <2>; + + nr-gpios = <64>; + }; + + sx8634@2b { + compatible = "smtc,sx8634"; + reg = <0x2b>; + + interrupt-parent = <&gpioext>; + interrupts = <3 0x8>; + + #address-cells = <1>; + #size-cells = <0>; + + threshold = <0x40>; + sensitivity = <7>; + }; + }; + + +Example of special form (supported by U-Boot): + + acpi_gpe: general-purpose-events { + reg = <IOMAP_ACPI_BASE IOMAP_ACPI_SIZE>; + compatible = "intel,acpi-gpe"; + interrupt-controller; + #interrupt-cells = <2>; + }; + + tpm@50 { + reg = <0x50>; + compatible = "google,cr50"; + u-boot,i2c-offset-len = <0>; + ready-gpio = <&gpio_n 28 GPIO_ACTIVE_LOW>; + interrupts-extended = <&acpi_gpe 0x3c 0>; + }; diff --git a/roms/u-boot/doc/device-tree-bindings/leds/common.txt b/roms/u-boot/doc/device-tree-bindings/leds/common.txt new file mode 100644 index 000000000..2d88816dd --- /dev/null +++ b/roms/u-boot/doc/device-tree-bindings/leds/common.txt @@ -0,0 +1,23 @@ +Common leds properties. + +Optional properties for child nodes: +- label : The label for this LED. If omitted, the label is + taken from the node name (excluding the unit address). + +- linux,default-trigger : This parameter, if present, is a + string defining the trigger assigned to the LED. Current triggers are: + "backlight" - LED will act as a back-light, controlled by the framebuffer + system + "default-on" - LED will turn on (but for leds-gpio see "default-state" + property in Documentation/devicetree/bindings/gpio/led.txt) + "heartbeat" - LED "double" flashes at a load average based rate + "ide-disk" - LED indicates disk activity + "timer" - LED flashes at a fixed, configurable rate + +Examples: + +system-status { + label = "Status"; + linux,default-trigger = "heartbeat"; + ... +}; diff --git a/roms/u-boot/doc/device-tree-bindings/leds/leds-bcm6328.txt b/roms/u-boot/doc/device-tree-bindings/leds/leds-bcm6328.txt new file mode 100644 index 000000000..7f5597b73 --- /dev/null +++ b/roms/u-boot/doc/device-tree-bindings/leds/leds-bcm6328.txt @@ -0,0 +1,106 @@ +LEDs connected to Broadcom BCM6328 controller + +This controller is present on BCM6318, BCM6328, BCM6362 and BCM63268. +In these SoCs it's possible to control LEDs both as GPIOs or by hardware. +However, on some devices there are Serial LEDs (LEDs connected to a 74x164 +controller), which can either be controlled by software (exporting the 74x164 +as spi-gpio. See Documentation/devicetree/bindings/gpio/gpio-74x164.txt), or +by hardware using this driver. +Some of these Serial LEDs are hardware controlled (e.g. ethernet LEDs) and +exporting the 74x164 as spi-gpio prevents those LEDs to be hardware +controlled, so the only chance to keep them working is by using this driver. + +Required properties: + - compatible : should be "brcm,bcm6328-leds". + - #address-cells : must be 1. + - #size-cells : must be 0. + - reg : BCM6328 LED controller address and size. + +Optional properties: + - brcm,serial-leds : Boolean, enables Serial LEDs. + Default : false + - brcm,serial-mux : Boolean, enables Serial LEDs multiplexing. + Default : false + - brcm,serial-clk-low : Boolean, makes clock signal active low. + Default : false + - brcm,serial-dat-low : Boolean, makes data signal active low. + Default : false + - brcm,serial-shift-inv : Boolean, inverts Serial LEDs shift direction. + Default : false + +Each LED is represented as a sub-node of the brcm,bcm6328-leds device. + +LED sub-node required properties: + - reg : LED pin number (only LEDs 0 to 23 are valid). + +LED sub-node optional properties: + - label : see Documentation/devicetree/bindings/leds/common.txt + - active-low : Boolean, makes LED active low. + Default : false + +Examples: +Scenario 1 : BCM6328 with 4 GPIO LEDs + leds0: led-controller@10000800 { + compatible = "brcm,bcm6328-leds"; + #address-cells = <1>; + #size-cells = <0>; + reg = <0x10000800 0x24>; + + alarm_red@2 { + reg = <2>; + active-low; + label = "red:alarm"; + }; + inet_green@3 { + reg = <3>; + active-low; + label = "green:inet"; + }; + power_green@4 { + reg = <4>; + active-low; + label = "green:power"; + }; + }; + +Scenario 2 : BCM63268 with Serial LEDs + leds0: led-controller@10001900 { + compatible = "brcm,bcm6328-leds"; + #address-cells = <1>; + #size-cells = <0>; + reg = <0x10001900 0x24>; + brcm,serial-leds; + brcm,serial-dat-low; + brcm,serial-shift-inv; + + inet_red@2 { + reg = <2>; + active-low; + label = "red:inet"; + }; + dsl_green@3 { + reg = <3>; + active-low; + label = "green:dsl"; + }; + usb_green@4 { + reg = <4>; + active-low; + label = "green:usb"; + }; + wps_green@7 { + reg = <7>; + active-low; + label = "green:wps"; + }; + inet_green@8 { + reg = <8>; + active-low; + label = "green:inet"; + }; + power_green@20 { + reg = <20>; + active-low; + label = "green:power"; + }; + }; diff --git a/roms/u-boot/doc/device-tree-bindings/leds/leds-bcm6358.txt b/roms/u-boot/doc/device-tree-bindings/leds/leds-bcm6358.txt new file mode 100644 index 000000000..e394d9ebb --- /dev/null +++ b/roms/u-boot/doc/device-tree-bindings/leds/leds-bcm6358.txt @@ -0,0 +1,141 @@ +LEDs connected to Broadcom BCM6358 controller + +This controller is present on BCM6358 and BCM6368. +In these SoCs there are Serial LEDs (LEDs connected to a 74x164 controller), +which can either be controlled by software (exporting the 74x164 as spi-gpio. +See Documentation/devicetree/bindings/gpio/gpio-74x164.txt), or +by hardware using this driver. + +Required properties: + - compatible : should be "brcm,bcm6358-leds". + - #address-cells : must be 1. + - #size-cells : must be 0. + - reg : BCM6358 LED controller address and size. + +Optional properties: + - brcm,clk-div : SCK signal divider. Possible values are 1, 2, 4 and 8. + Default : 1 + - brcm,clk-dat-low : Boolean, makes clock and data signals active low. + Default : false + +Each LED is represented as a sub-node of the brcm,bcm6358-leds device. + +LED sub-node required properties: + - reg : LED pin number (only LEDs 0 to 31 are valid). + +LED sub-node optional properties: + - label : see Documentation/devicetree/bindings/leds/common.txt + - active-low : Boolean, makes LED active low. + Default : false + +Examples: +Scenario 1 : BCM6358 + leds0: led-controller@fffe00d0 { + compatible = "brcm,bcm6358-leds"; + #address-cells = <1>; + #size-cells = <0>; + reg = <0xfffe00d0 0x8>; + + alarm_white { + reg = <0>; + active-low; + label = "white:alarm"; + }; + tv_white { + reg = <2>; + active-low; + label = "white:tv"; + }; + tel_white { + reg = <3>; + active-low; + label = "white:tel"; + }; + adsl_white { + reg = <4>; + active-low; + label = "white:adsl"; + }; + }; + +Scenario 2 : BCM6368 + leds0: led-controller@100000d0 { + compatible = "brcm,bcm6358-leds"; + #address-cells = <1>; + #size-cells = <0>; + reg = <0x100000d0 0x8>; + brcm,pol-low; + brcm,clk-div = <4>; + + power_red { + reg = <0>; + active-low; + label = "red:power"; + }; + power_green { + reg = <1>; + active-low; + label = "green:power"; + default-state = "on"; + }; + power_blue { + reg = <2>; + label = "blue:power"; + }; + broadband_red { + reg = <3>; + active-low; + label = "red:broadband"; + }; + broadband_green { + reg = <4>; + label = "green:broadband"; + }; + broadband_blue { + reg = <5>; + active-low; + label = "blue:broadband"; + }; + wireless_red { + reg = <6>; + active-low; + label = "red:wireless"; + }; + wireless_green { + reg = <7>; + active-low; + label = "green:wireless"; + }; + wireless_blue { + reg = <8>; + label = "blue:wireless"; + }; + phone_red { + reg = <9>; + active-low; + label = "red:phone"; + }; + phone_green { + reg = <10>; + active-low; + label = "green:phone"; + }; + phone_blue { + reg = <11>; + label = "blue:phone"; + }; + upgrading_red { + reg = <12>; + active-low; + label = "red:upgrading"; + }; + upgrading_green { + reg = <13>; + active-low; + label = "green:upgrading"; + }; + upgrading_blue { + reg = <14>; + label = "blue:upgrading"; + }; + }; diff --git a/roms/u-boot/doc/device-tree-bindings/leds/leds-bcm6858.txt b/roms/u-boot/doc/device-tree-bindings/leds/leds-bcm6858.txt new file mode 100644 index 000000000..ea2fe2370 --- /dev/null +++ b/roms/u-boot/doc/device-tree-bindings/leds/leds-bcm6858.txt @@ -0,0 +1,51 @@ +LEDs connected to Broadcom BCM6858 controller + +This controller is present on BCM6858, BCM6328, BCM6362 and BCM63268. +In these SoCs it's possible to control LEDs both as GPIOs or by hardware. + +Required properties: + - compatible : should be "brcm,bcm6858-leds". + - #address-cells : must be 1. + - #size-cells : must be 0. + - reg : BCM6858 LED controller address and size. + +Optional properties: + - brcm,serial-led-msb-first : Boolean, msb data come out first on serial data pin + Default : false + - brcm,serial-led-en-pol : Boolean, serial led polarity (true => active high) + Default : false + - brcm,serial-led-clk-pol : Boolean, serial clock polarity (true => active high) + Default : false + - brcm,serial-led-data-ppol : Boolean, serial data polarity (true => active high) + Default : false + - brcm,serial-shift-inv : Boolean, led test mode + Default : false + +Each LED is represented as a sub-node of the brcm,bcm6858-leds device. + +LED sub-node required properties: + - reg : LED pin number (only LEDs 0 to 32 are valid). + +LED sub-node optional properties: + - label : see Documentation/devicetree/bindings/leds/common.txt + - active-low : Boolean, makes LED active low. + Default : false + +Examples: +BCM6328 with 2 GPIO LEDs + leds0: led-controller@ff800800 { + compatible = "brcm,bcm6858-leds"; + #address-cells = <1>; + #size-cells = <0>; + reg = <0x0 0xff800800 0x0 0xe4>; + + led@2 { + reg = <2>; + label = "green:inet"; + }; + + led@5 { + reg = <5>; + label = "red:alarm"; + }; + }; diff --git a/roms/u-boot/doc/device-tree-bindings/leds/leds-gpio.txt b/roms/u-boot/doc/device-tree-bindings/leds/leds-gpio.txt new file mode 100644 index 000000000..df1b3080f --- /dev/null +++ b/roms/u-boot/doc/device-tree-bindings/leds/leds-gpio.txt @@ -0,0 +1,52 @@ +LEDs connected to GPIO lines + +Required properties: +- compatible : should be "gpio-leds". + +Each LED is represented as a sub-node of the gpio-leds device. Each +node's name represents the name of the corresponding LED. + +LED sub-node properties: +- gpios : Should specify the LED's GPIO, see "gpios property" in + Documentation/devicetree/bindings/gpio/gpio.txt. Active low LEDs should be + indicated using flags in the GPIO specifier. +- label : (optional) + see Documentation/devicetree/bindings/leds/common.txt +- linux,default-trigger : (optional) + see Documentation/devicetree/bindings/leds/common.txt +- default-state: (optional) The initial state of the LED. Valid + values are "on", "off", and "keep". If the LED is already on or off + and the default-state property is set the to same value, then no + glitch should be produced where the LED momentarily turns off (or + on). The "keep" setting will keep the LED at whatever its current + state is, without producing a glitch. The default is off if this + property is not present. + +Examples: + +leds { + compatible = "gpio-leds"; + hdd { + label = "IDE Activity"; + gpios = <&mcu_pio 0 1>; /* Active low */ + linux,default-trigger = "ide-disk"; + }; + + fault { + gpios = <&mcu_pio 1 0>; + /* Keep LED on if BIOS detected hardware fault */ + default-state = "keep"; + }; +}; + +run-control { + compatible = "gpio-leds"; + red { + gpios = <&mpc8572 6 0>; + default-state = "off"; + }; + green { + gpios = <&mpc8572 7 0>; + default-state = "on"; + }; +}; diff --git a/roms/u-boot/doc/device-tree-bindings/mailbox/k3-secure-proxy.txt b/roms/u-boot/doc/device-tree-bindings/mailbox/k3-secure-proxy.txt new file mode 100644 index 000000000..f3add0d4e --- /dev/null +++ b/roms/u-boot/doc/device-tree-bindings/mailbox/k3-secure-proxy.txt @@ -0,0 +1,40 @@ +Texas Instruments' K3 Secure Proxy +=================================== + +The Texas Instruments' K3 Secure Proxy is a mailbox controller that has +configurable threads maintained by System power processor. Each thread +has different address space that can be used to send or receive messages. + +Secure Proxy Device Node: +=========================== +Required properties: +-------------------- +- compatible: Shall be: "ti,am654-secure-proxy" +- reg-names data - Map the data region + scfg - Map the secure configuration region + rt - Map the Realtime region. +- reg: Contains the register map per reg-names. +- #mbox-cells Shall be 1. Contains the thread ID. + +Example: +-------- + +secproxy: secproxy@285b0000 { + compatible = "ti,am654-secure-proxy"; + reg = <0x2a380000 0x80000>, + <0x2a400000 0x80000>, + <0x2a480000 0x80000>; + reg-names = "rt", "scfg", "data"; + #mbox-cells = <1>; +}; + +client: + +systemcontroller: systemcontroller { + [...] + # RX thread ID is 4. + # TX thread ID is 5. + mboxes= <&secproxy 4>, + <&secproxy 5>; + [...] +}; diff --git a/roms/u-boot/doc/device-tree-bindings/mailbox/mailbox.txt b/roms/u-boot/doc/device-tree-bindings/mailbox/mailbox.txt new file mode 100644 index 000000000..be05b9746 --- /dev/null +++ b/roms/u-boot/doc/device-tree-bindings/mailbox/mailbox.txt @@ -0,0 +1,32 @@ +* Generic Mailbox Controller and client driver bindings + +Generic binding to provide a way for Mailbox controller drivers to +assign appropriate mailbox channel to client drivers. + +* Mailbox Controller + +Required property: +- #mbox-cells: Must be at least 1. Number of cells in a mailbox + specifier. + +Example: + mailbox: mailbox { + ... + #mbox-cells = <1>; + }; + + +* Mailbox Client + +Required property: +- mboxes: List of phandle and mailbox channel specifiers. + +Optional property: +- mbox-names: List of identifier strings for each mailbox channel. + +Example: + pwr_cntrl: power { + ... + mbox-names = "pwr-ctrl", "rpc"; + mboxes = <&mailbox 0 &mailbox 1>; + }; diff --git a/roms/u-boot/doc/device-tree-bindings/mailbox/nvidia,tegra186-hsp.txt b/roms/u-boot/doc/device-tree-bindings/mailbox/nvidia,tegra186-hsp.txt new file mode 100644 index 000000000..a91523806 --- /dev/null +++ b/roms/u-boot/doc/device-tree-bindings/mailbox/nvidia,tegra186-hsp.txt @@ -0,0 +1,52 @@ +NVIDIA Tegra Hardware Synchronization Primitives (HSP) + +The HSP modules are used for the processors to share resources and communicate +together. It provides a set of hardware synchronization primitives for +interprocessor communication. So the interprocessor communication (IPC) +protocols can use hardware synchronization primitives, when operating between +two processors not in an SMP relationship. + +The features that HSP supported are shared mailboxes, shared semaphores, +arbitrated semaphores and doorbells. + +Required properties: +- name : Should be hsp +- compatible + Array of strings. + one of: + - "nvidia,tegra186-hsp" +- reg : Offset and length of the register set for the device. +- interrupt-names + Array of strings. + Contains a list of names for the interrupts described by the interrupt + property. May contain the following entries, in any order: + - "doorbell" + Users of this binding MUST look up entries in the interrupt property + by name, using this interrupt-names property to do so. +- interrupts + Array of interrupt specifiers. + Must contain one entry per entry in the interrupt-names property, + in a matching order. +- #mbox-cells : Should be 2. + +The mbox specifier of the "mboxes" property in the client node should +contain two data. The first one should be the HSP type and the second +one should be the ID that the client is going to use. Those information +can be found in the following file. + +- <dt-bindings/mailbox/tegra186-hsp.h>. + +Example: + +hsp_top0: hsp@3c00000 { + compatible = "nvidia,tegra186-hsp"; + reg = <0x0 0x03c00000 0x0 0xa0000>; + interrupts = <GIC_SPI 176 IRQ_TYPE_LEVEL_HIGH>; + interrupt-names = "doorbell"; + #mbox-cells = <2>; +}; + +client { + ... + mboxes = <&hsp_top0 HSP_MBOX_TYPE_DB HSP_DB_MASTER_XXX>; +}; diff --git a/roms/u-boot/doc/device-tree-bindings/memory-controller/k3-j721e-ddrss.txt b/roms/u-boot/doc/device-tree-bindings/memory-controller/k3-j721e-ddrss.txt new file mode 100644 index 000000000..c4cf26eaa --- /dev/null +++ b/roms/u-boot/doc/device-tree-bindings/memory-controller/k3-j721e-ddrss.txt @@ -0,0 +1,2242 @@ +Texas Instruments' K3 J721E DDRSS +================================== +The J721E DDR subsystem comprises DDR controller, DDR PHY and wrapper +logic to integrate these blocks in the device. The DDR subsystem is +used to provide an interface to external SDRAM devices which can be +utilized for storing program or data. + +DDRSS device node: +================== +Required properties: +-------------------- +- compatible: Shall be: "ti,j721e-ddrss" for j721e, j7200 + "ti,am64-ddrss" for am642 +- reg-names cfg - Map the controller configuration region + ctrl_mmr_lp4 - Map LP4 register region in ctrl mmr +- reg: Contains the register map per reg-names. +- power-domains: Should contain two entries: + - an entry to TISCI DDR CFG device + - an entry to TISCI DDR DATA. + This property is as per the binding, + doc/device-tree-bindings/power/ti,sci-pm-domain.txt +- clocks: Should contain two entries. + - An entry to DDRSS clock + - An rntry to SoC bypass clock + Should be defined as per the appropriate clock bindings + consumer usage in + doc/device-tree-bindings/clock/ti,sci-clk.txt +- ti,ddr-freq1: First frequency set point +- ti,ddr-freq2: Second frequency set point +- ti,ddr-fhs-cnt: Number of times to communicate to DDR for frequency handshake. +- ti,ctl-data: An array containing the controller settings. +- ti,pi-data: An array containing the phy independent block settings +- ti,phy-data: An array containing the ddr phy settings. + +Example (J721E): +================ + +memorycontroller: memorycontroller@0298e000 { + compatible = "ti,j721e-ddrss"; + reg = <0x0 0x02990000 0x0 0x4000>, + <0x0 0x0114000 0x0 0x100>; + reg-names = "cfg", "ctrl_mmr_lp4"; + power-domains = <&k3_pds 47 TI_SCI_PD_SHARED>, + <&k3_pds 90 TI_SCI_PD_SHARED>; + clocks = <&k3_clks 47 2>, <&k3_clks 30 9>; + ti,ddr-freq1 = <DDRSS_PLL_FREQUENCY_1>; + ti,ddr-freq2 = <DDRSS_PLL_FREQUENCY_2>; + ti,ddr-fhs-cnt = <DDRSS_PLL_FHS_CNT>; + + u-boot,dm-spl; + + ti,ctl-data = < + DDRSS_CTL_00_DATA + DDRSS_CTL_01_DATA + DDRSS_CTL_02_DATA + DDRSS_CTL_03_DATA + DDRSS_CTL_04_DATA + DDRSS_CTL_05_DATA + DDRSS_CTL_06_DATA + DDRSS_CTL_07_DATA + DDRSS_CTL_08_DATA + DDRSS_CTL_09_DATA + DDRSS_CTL_10_DATA + DDRSS_CTL_11_DATA + DDRSS_CTL_12_DATA + DDRSS_CTL_13_DATA + DDRSS_CTL_14_DATA + DDRSS_CTL_15_DATA + DDRSS_CTL_16_DATA + DDRSS_CTL_17_DATA + DDRSS_CTL_18_DATA + DDRSS_CTL_19_DATA + DDRSS_CTL_20_DATA + DDRSS_CTL_21_DATA + DDRSS_CTL_22_DATA + DDRSS_CTL_23_DATA + DDRSS_CTL_24_DATA + DDRSS_CTL_25_DATA + DDRSS_CTL_26_DATA + DDRSS_CTL_27_DATA + DDRSS_CTL_28_DATA + DDRSS_CTL_29_DATA + DDRSS_CTL_30_DATA + DDRSS_CTL_31_DATA + DDRSS_CTL_32_DATA + DDRSS_CTL_33_DATA + DDRSS_CTL_34_DATA + DDRSS_CTL_35_DATA + DDRSS_CTL_36_DATA + DDRSS_CTL_37_DATA + DDRSS_CTL_38_DATA + DDRSS_CTL_39_DATA + DDRSS_CTL_40_DATA + DDRSS_CTL_41_DATA + DDRSS_CTL_42_DATA + DDRSS_CTL_43_DATA + DDRSS_CTL_44_DATA + DDRSS_CTL_45_DATA + DDRSS_CTL_46_DATA + DDRSS_CTL_47_DATA + DDRSS_CTL_48_DATA + DDRSS_CTL_49_DATA + DDRSS_CTL_50_DATA + DDRSS_CTL_51_DATA + DDRSS_CTL_52_DATA + DDRSS_CTL_53_DATA + DDRSS_CTL_54_DATA + DDRSS_CTL_55_DATA + DDRSS_CTL_56_DATA + DDRSS_CTL_57_DATA + DDRSS_CTL_58_DATA + DDRSS_CTL_59_DATA + DDRSS_CTL_60_DATA + DDRSS_CTL_61_DATA + DDRSS_CTL_62_DATA + DDRSS_CTL_63_DATA + DDRSS_CTL_64_DATA + DDRSS_CTL_65_DATA + DDRSS_CTL_66_DATA + DDRSS_CTL_67_DATA + DDRSS_CTL_68_DATA + DDRSS_CTL_69_DATA + DDRSS_CTL_70_DATA + DDRSS_CTL_71_DATA + DDRSS_CTL_72_DATA + DDRSS_CTL_73_DATA + DDRSS_CTL_74_DATA + DDRSS_CTL_75_DATA + DDRSS_CTL_76_DATA + DDRSS_CTL_77_DATA + DDRSS_CTL_78_DATA + DDRSS_CTL_79_DATA + DDRSS_CTL_80_DATA + DDRSS_CTL_81_DATA + DDRSS_CTL_82_DATA + DDRSS_CTL_83_DATA + DDRSS_CTL_84_DATA + DDRSS_CTL_85_DATA + DDRSS_CTL_86_DATA + DDRSS_CTL_87_DATA + DDRSS_CTL_88_DATA + DDRSS_CTL_89_DATA + DDRSS_CTL_90_DATA + DDRSS_CTL_91_DATA + DDRSS_CTL_92_DATA + DDRSS_CTL_93_DATA + DDRSS_CTL_94_DATA + DDRSS_CTL_95_DATA + DDRSS_CTL_96_DATA + DDRSS_CTL_97_DATA + DDRSS_CTL_98_DATA + DDRSS_CTL_99_DATA + DDRSS_CTL_100_DATA + DDRSS_CTL_101_DATA + DDRSS_CTL_102_DATA + DDRSS_CTL_103_DATA + DDRSS_CTL_104_DATA + DDRSS_CTL_105_DATA + DDRSS_CTL_106_DATA + DDRSS_CTL_107_DATA + DDRSS_CTL_108_DATA + DDRSS_CTL_109_DATA + DDRSS_CTL_110_DATA + DDRSS_CTL_111_DATA + DDRSS_CTL_112_DATA + DDRSS_CTL_113_DATA + DDRSS_CTL_114_DATA + DDRSS_CTL_115_DATA + DDRSS_CTL_116_DATA + DDRSS_CTL_117_DATA + DDRSS_CTL_118_DATA + DDRSS_CTL_119_DATA + DDRSS_CTL_120_DATA + DDRSS_CTL_121_DATA + DDRSS_CTL_122_DATA + DDRSS_CTL_123_DATA + DDRSS_CTL_124_DATA + DDRSS_CTL_125_DATA + DDRSS_CTL_126_DATA + DDRSS_CTL_127_DATA + DDRSS_CTL_128_DATA + DDRSS_CTL_129_DATA + DDRSS_CTL_130_DATA + DDRSS_CTL_131_DATA + DDRSS_CTL_132_DATA + DDRSS_CTL_133_DATA + DDRSS_CTL_134_DATA + DDRSS_CTL_135_DATA + DDRSS_CTL_136_DATA + DDRSS_CTL_137_DATA + DDRSS_CTL_138_DATA + DDRSS_CTL_139_DATA + DDRSS_CTL_140_DATA + DDRSS_CTL_141_DATA + DDRSS_CTL_142_DATA + DDRSS_CTL_143_DATA + DDRSS_CTL_144_DATA + DDRSS_CTL_145_DATA + DDRSS_CTL_146_DATA + DDRSS_CTL_147_DATA + DDRSS_CTL_148_DATA + DDRSS_CTL_149_DATA + DDRSS_CTL_150_DATA + DDRSS_CTL_151_DATA + DDRSS_CTL_152_DATA + DDRSS_CTL_153_DATA + DDRSS_CTL_154_DATA + DDRSS_CTL_155_DATA + DDRSS_CTL_156_DATA + DDRSS_CTL_157_DATA + DDRSS_CTL_158_DATA + DDRSS_CTL_159_DATA + DDRSS_CTL_160_DATA + DDRSS_CTL_161_DATA + DDRSS_CTL_162_DATA + DDRSS_CTL_163_DATA + DDRSS_CTL_164_DATA + DDRSS_CTL_165_DATA + DDRSS_CTL_166_DATA + DDRSS_CTL_167_DATA + DDRSS_CTL_168_DATA + DDRSS_CTL_169_DATA + DDRSS_CTL_170_DATA + DDRSS_CTL_171_DATA + DDRSS_CTL_172_DATA + DDRSS_CTL_173_DATA + DDRSS_CTL_174_DATA + DDRSS_CTL_175_DATA + DDRSS_CTL_176_DATA + DDRSS_CTL_177_DATA + DDRSS_CTL_178_DATA + DDRSS_CTL_179_DATA + DDRSS_CTL_180_DATA + DDRSS_CTL_181_DATA + DDRSS_CTL_182_DATA + DDRSS_CTL_183_DATA + DDRSS_CTL_184_DATA + DDRSS_CTL_185_DATA + DDRSS_CTL_186_DATA + DDRSS_CTL_187_DATA + DDRSS_CTL_188_DATA + DDRSS_CTL_189_DATA + DDRSS_CTL_190_DATA + DDRSS_CTL_191_DATA + DDRSS_CTL_192_DATA + DDRSS_CTL_193_DATA + DDRSS_CTL_194_DATA + DDRSS_CTL_195_DATA + DDRSS_CTL_196_DATA + DDRSS_CTL_197_DATA + DDRSS_CTL_198_DATA + DDRSS_CTL_199_DATA + DDRSS_CTL_200_DATA + DDRSS_CTL_201_DATA + DDRSS_CTL_202_DATA + DDRSS_CTL_203_DATA + DDRSS_CTL_204_DATA + DDRSS_CTL_205_DATA + DDRSS_CTL_206_DATA + DDRSS_CTL_207_DATA + DDRSS_CTL_208_DATA + DDRSS_CTL_209_DATA + DDRSS_CTL_210_DATA + DDRSS_CTL_211_DATA + DDRSS_CTL_212_DATA + DDRSS_CTL_213_DATA + DDRSS_CTL_214_DATA + DDRSS_CTL_215_DATA + DDRSS_CTL_216_DATA + DDRSS_CTL_217_DATA + DDRSS_CTL_218_DATA + DDRSS_CTL_219_DATA + DDRSS_CTL_220_DATA + DDRSS_CTL_221_DATA + DDRSS_CTL_222_DATA + DDRSS_CTL_223_DATA + DDRSS_CTL_224_DATA + DDRSS_CTL_225_DATA + DDRSS_CTL_226_DATA + DDRSS_CTL_227_DATA + DDRSS_CTL_228_DATA + DDRSS_CTL_229_DATA + DDRSS_CTL_230_DATA + DDRSS_CTL_231_DATA + DDRSS_CTL_232_DATA + DDRSS_CTL_233_DATA + DDRSS_CTL_234_DATA + DDRSS_CTL_235_DATA + DDRSS_CTL_236_DATA + DDRSS_CTL_237_DATA + DDRSS_CTL_238_DATA + DDRSS_CTL_239_DATA + DDRSS_CTL_240_DATA + DDRSS_CTL_241_DATA + DDRSS_CTL_242_DATA + DDRSS_CTL_243_DATA + DDRSS_CTL_244_DATA + DDRSS_CTL_245_DATA + DDRSS_CTL_246_DATA + DDRSS_CTL_247_DATA + DDRSS_CTL_248_DATA + DDRSS_CTL_249_DATA + DDRSS_CTL_250_DATA + DDRSS_CTL_251_DATA + DDRSS_CTL_252_DATA + DDRSS_CTL_253_DATA + DDRSS_CTL_254_DATA + DDRSS_CTL_255_DATA + DDRSS_CTL_256_DATA + DDRSS_CTL_257_DATA + DDRSS_CTL_258_DATA + DDRSS_CTL_259_DATA + DDRSS_CTL_260_DATA + DDRSS_CTL_261_DATA + DDRSS_CTL_262_DATA + DDRSS_CTL_263_DATA + DDRSS_CTL_264_DATA + DDRSS_CTL_265_DATA + DDRSS_CTL_266_DATA + DDRSS_CTL_267_DATA + DDRSS_CTL_268_DATA + DDRSS_CTL_269_DATA + DDRSS_CTL_270_DATA + DDRSS_CTL_271_DATA + DDRSS_CTL_272_DATA + DDRSS_CTL_273_DATA + DDRSS_CTL_274_DATA + DDRSS_CTL_275_DATA + DDRSS_CTL_276_DATA + DDRSS_CTL_277_DATA + DDRSS_CTL_278_DATA + DDRSS_CTL_279_DATA + DDRSS_CTL_280_DATA + DDRSS_CTL_281_DATA + DDRSS_CTL_282_DATA + DDRSS_CTL_283_DATA + DDRSS_CTL_284_DATA + DDRSS_CTL_285_DATA + DDRSS_CTL_286_DATA + DDRSS_CTL_287_DATA + DDRSS_CTL_288_DATA + DDRSS_CTL_289_DATA + DDRSS_CTL_290_DATA + DDRSS_CTL_291_DATA + DDRSS_CTL_292_DATA + DDRSS_CTL_293_DATA + DDRSS_CTL_294_DATA + DDRSS_CTL_295_DATA + DDRSS_CTL_296_DATA + DDRSS_CTL_297_DATA + DDRSS_CTL_298_DATA + DDRSS_CTL_299_DATA + DDRSS_CTL_300_DATA + DDRSS_CTL_301_DATA + DDRSS_CTL_302_DATA + DDRSS_CTL_303_DATA + DDRSS_CTL_304_DATA + DDRSS_CTL_305_DATA + DDRSS_CTL_306_DATA + DDRSS_CTL_307_DATA + DDRSS_CTL_308_DATA + DDRSS_CTL_309_DATA + DDRSS_CTL_310_DATA + DDRSS_CTL_311_DATA + DDRSS_CTL_312_DATA + DDRSS_CTL_313_DATA + DDRSS_CTL_314_DATA + DDRSS_CTL_315_DATA + DDRSS_CTL_316_DATA + DDRSS_CTL_317_DATA + DDRSS_CTL_318_DATA + DDRSS_CTL_319_DATA + DDRSS_CTL_320_DATA + DDRSS_CTL_321_DATA + DDRSS_CTL_322_DATA + DDRSS_CTL_323_DATA + DDRSS_CTL_324_DATA + DDRSS_CTL_325_DATA + DDRSS_CTL_326_DATA + DDRSS_CTL_327_DATA + DDRSS_CTL_328_DATA + DDRSS_CTL_329_DATA + DDRSS_CTL_330_DATA + DDRSS_CTL_331_DATA + DDRSS_CTL_332_DATA + DDRSS_CTL_333_DATA + DDRSS_CTL_334_DATA + DDRSS_CTL_335_DATA + DDRSS_CTL_336_DATA + DDRSS_CTL_337_DATA + DDRSS_CTL_338_DATA + DDRSS_CTL_339_DATA + DDRSS_CTL_340_DATA + DDRSS_CTL_341_DATA + DDRSS_CTL_342_DATA + DDRSS_CTL_343_DATA + DDRSS_CTL_344_DATA + DDRSS_CTL_345_DATA + DDRSS_CTL_346_DATA + DDRSS_CTL_347_DATA + DDRSS_CTL_348_DATA + DDRSS_CTL_349_DATA + DDRSS_CTL_350_DATA + DDRSS_CTL_351_DATA + DDRSS_CTL_352_DATA + DDRSS_CTL_353_DATA + DDRSS_CTL_354_DATA + DDRSS_CTL_355_DATA + DDRSS_CTL_356_DATA + DDRSS_CTL_357_DATA + DDRSS_CTL_358_DATA + DDRSS_CTL_359_DATA + DDRSS_CTL_360_DATA + DDRSS_CTL_361_DATA + DDRSS_CTL_362_DATA + DDRSS_CTL_363_DATA + DDRSS_CTL_364_DATA + DDRSS_CTL_365_DATA + DDRSS_CTL_366_DATA + DDRSS_CTL_367_DATA + DDRSS_CTL_368_DATA + DDRSS_CTL_369_DATA + DDRSS_CTL_370_DATA + DDRSS_CTL_371_DATA + DDRSS_CTL_372_DATA + DDRSS_CTL_373_DATA + DDRSS_CTL_374_DATA + DDRSS_CTL_375_DATA + DDRSS_CTL_376_DATA + DDRSS_CTL_377_DATA + DDRSS_CTL_378_DATA + DDRSS_CTL_379_DATA + DDRSS_CTL_380_DATA + DDRSS_CTL_381_DATA + DDRSS_CTL_382_DATA + DDRSS_CTL_383_DATA + DDRSS_CTL_384_DATA + DDRSS_CTL_385_DATA + DDRSS_CTL_386_DATA + DDRSS_CTL_387_DATA + DDRSS_CTL_388_DATA + DDRSS_CTL_389_DATA + DDRSS_CTL_390_DATA + DDRSS_CTL_391_DATA + DDRSS_CTL_392_DATA + DDRSS_CTL_393_DATA + DDRSS_CTL_394_DATA + DDRSS_CTL_395_DATA + DDRSS_CTL_396_DATA + DDRSS_CTL_397_DATA + DDRSS_CTL_398_DATA + DDRSS_CTL_399_DATA + DDRSS_CTL_400_DATA + DDRSS_CTL_401_DATA + DDRSS_CTL_402_DATA + DDRSS_CTL_403_DATA + DDRSS_CTL_404_DATA + DDRSS_CTL_405_DATA + DDRSS_CTL_406_DATA + DDRSS_CTL_407_DATA + DDRSS_CTL_408_DATA + DDRSS_CTL_409_DATA + DDRSS_CTL_410_DATA + DDRSS_CTL_411_DATA + DDRSS_CTL_412_DATA + DDRSS_CTL_413_DATA + DDRSS_CTL_414_DATA + DDRSS_CTL_415_DATA + DDRSS_CTL_416_DATA + DDRSS_CTL_417_DATA + DDRSS_CTL_418_DATA + DDRSS_CTL_419_DATA + DDRSS_CTL_420_DATA + DDRSS_CTL_421_DATA + DDRSS_CTL_422_DATA + DDRSS_CTL_423_DATA + DDRSS_CTL_424_DATA + DDRSS_CTL_425_DATA + DDRSS_CTL_426_DATA + DDRSS_CTL_427_DATA + DDRSS_CTL_428_DATA + DDRSS_CTL_429_DATA + DDRSS_CTL_430_DATA + DDRSS_CTL_431_DATA + DDRSS_CTL_432_DATA + DDRSS_CTL_433_DATA + DDRSS_CTL_434_DATA + DDRSS_CTL_435_DATA + DDRSS_CTL_436_DATA + DDRSS_CTL_437_DATA + DDRSS_CTL_438_DATA + DDRSS_CTL_439_DATA + DDRSS_CTL_440_DATA + DDRSS_CTL_441_DATA + DDRSS_CTL_442_DATA + DDRSS_CTL_443_DATA + DDRSS_CTL_444_DATA + DDRSS_CTL_445_DATA + DDRSS_CTL_446_DATA + DDRSS_CTL_447_DATA + DDRSS_CTL_448_DATA + DDRSS_CTL_449_DATA + DDRSS_CTL_450_DATA + DDRSS_CTL_451_DATA + DDRSS_CTL_452_DATA + DDRSS_CTL_453_DATA + DDRSS_CTL_454_DATA + DDRSS_CTL_455_DATA + DDRSS_CTL_456_DATA + DDRSS_CTL_457_DATA + DDRSS_CTL_458_DATA + >; + + ti,pi-data = < + DDRSS_PI_00_DATA + DDRSS_PI_01_DATA + DDRSS_PI_02_DATA + DDRSS_PI_03_DATA + DDRSS_PI_04_DATA + DDRSS_PI_05_DATA + DDRSS_PI_06_DATA + DDRSS_PI_07_DATA + DDRSS_PI_08_DATA + DDRSS_PI_09_DATA + DDRSS_PI_10_DATA + DDRSS_PI_11_DATA + DDRSS_PI_12_DATA + DDRSS_PI_13_DATA + DDRSS_PI_14_DATA + DDRSS_PI_15_DATA + DDRSS_PI_16_DATA + DDRSS_PI_17_DATA + DDRSS_PI_18_DATA + DDRSS_PI_19_DATA + DDRSS_PI_20_DATA + DDRSS_PI_21_DATA + DDRSS_PI_22_DATA + DDRSS_PI_23_DATA + DDRSS_PI_24_DATA + DDRSS_PI_25_DATA + DDRSS_PI_26_DATA + DDRSS_PI_27_DATA + DDRSS_PI_28_DATA + DDRSS_PI_29_DATA + DDRSS_PI_30_DATA + DDRSS_PI_31_DATA + DDRSS_PI_32_DATA + DDRSS_PI_33_DATA + DDRSS_PI_34_DATA + DDRSS_PI_35_DATA + DDRSS_PI_36_DATA + DDRSS_PI_37_DATA + DDRSS_PI_38_DATA + DDRSS_PI_39_DATA + DDRSS_PI_40_DATA + DDRSS_PI_41_DATA + DDRSS_PI_42_DATA + DDRSS_PI_43_DATA + DDRSS_PI_44_DATA + DDRSS_PI_45_DATA + DDRSS_PI_46_DATA + DDRSS_PI_47_DATA + DDRSS_PI_48_DATA + DDRSS_PI_49_DATA + DDRSS_PI_50_DATA + DDRSS_PI_51_DATA + DDRSS_PI_52_DATA + DDRSS_PI_53_DATA + DDRSS_PI_54_DATA + DDRSS_PI_55_DATA + DDRSS_PI_56_DATA + DDRSS_PI_57_DATA + DDRSS_PI_58_DATA + DDRSS_PI_59_DATA + DDRSS_PI_60_DATA + DDRSS_PI_61_DATA + DDRSS_PI_62_DATA + DDRSS_PI_63_DATA + DDRSS_PI_64_DATA + DDRSS_PI_65_DATA + DDRSS_PI_66_DATA + DDRSS_PI_67_DATA + DDRSS_PI_68_DATA + DDRSS_PI_69_DATA + DDRSS_PI_70_DATA + DDRSS_PI_71_DATA + DDRSS_PI_72_DATA + DDRSS_PI_73_DATA + DDRSS_PI_74_DATA + DDRSS_PI_75_DATA + DDRSS_PI_76_DATA + DDRSS_PI_77_DATA + DDRSS_PI_78_DATA + DDRSS_PI_79_DATA + DDRSS_PI_80_DATA + DDRSS_PI_81_DATA + DDRSS_PI_82_DATA + DDRSS_PI_83_DATA + DDRSS_PI_84_DATA + DDRSS_PI_85_DATA + DDRSS_PI_86_DATA + DDRSS_PI_87_DATA + DDRSS_PI_88_DATA + DDRSS_PI_89_DATA + DDRSS_PI_90_DATA + DDRSS_PI_91_DATA + DDRSS_PI_92_DATA + DDRSS_PI_93_DATA + DDRSS_PI_94_DATA + DDRSS_PI_95_DATA + DDRSS_PI_96_DATA + DDRSS_PI_97_DATA + DDRSS_PI_98_DATA + DDRSS_PI_99_DATA + DDRSS_PI_100_DATA + DDRSS_PI_101_DATA + DDRSS_PI_102_DATA + DDRSS_PI_103_DATA + DDRSS_PI_104_DATA + DDRSS_PI_105_DATA + DDRSS_PI_106_DATA + DDRSS_PI_107_DATA + DDRSS_PI_108_DATA + DDRSS_PI_109_DATA + DDRSS_PI_110_DATA + DDRSS_PI_111_DATA + DDRSS_PI_112_DATA + DDRSS_PI_113_DATA + DDRSS_PI_114_DATA + DDRSS_PI_115_DATA + DDRSS_PI_116_DATA + DDRSS_PI_117_DATA + DDRSS_PI_118_DATA + DDRSS_PI_119_DATA + DDRSS_PI_120_DATA + DDRSS_PI_121_DATA + DDRSS_PI_122_DATA + DDRSS_PI_123_DATA + DDRSS_PI_124_DATA + DDRSS_PI_125_DATA + DDRSS_PI_126_DATA + DDRSS_PI_127_DATA + DDRSS_PI_128_DATA + DDRSS_PI_129_DATA + DDRSS_PI_130_DATA + DDRSS_PI_131_DATA + DDRSS_PI_132_DATA + DDRSS_PI_133_DATA + DDRSS_PI_134_DATA + DDRSS_PI_135_DATA + DDRSS_PI_136_DATA + DDRSS_PI_137_DATA + DDRSS_PI_138_DATA + DDRSS_PI_139_DATA + DDRSS_PI_140_DATA + DDRSS_PI_141_DATA + DDRSS_PI_142_DATA + DDRSS_PI_143_DATA + DDRSS_PI_144_DATA + DDRSS_PI_145_DATA + DDRSS_PI_146_DATA + DDRSS_PI_147_DATA + DDRSS_PI_148_DATA + DDRSS_PI_149_DATA + DDRSS_PI_150_DATA + DDRSS_PI_151_DATA + DDRSS_PI_152_DATA + DDRSS_PI_153_DATA + DDRSS_PI_154_DATA + DDRSS_PI_155_DATA + DDRSS_PI_156_DATA + DDRSS_PI_157_DATA + DDRSS_PI_158_DATA + DDRSS_PI_159_DATA + DDRSS_PI_160_DATA + DDRSS_PI_161_DATA + DDRSS_PI_162_DATA + DDRSS_PI_163_DATA + DDRSS_PI_164_DATA + DDRSS_PI_165_DATA + DDRSS_PI_166_DATA + DDRSS_PI_167_DATA + DDRSS_PI_168_DATA + DDRSS_PI_169_DATA + DDRSS_PI_170_DATA + DDRSS_PI_171_DATA + DDRSS_PI_172_DATA + DDRSS_PI_173_DATA + DDRSS_PI_174_DATA + DDRSS_PI_175_DATA + DDRSS_PI_176_DATA + DDRSS_PI_177_DATA + DDRSS_PI_178_DATA + DDRSS_PI_179_DATA + DDRSS_PI_180_DATA + DDRSS_PI_181_DATA + DDRSS_PI_182_DATA + DDRSS_PI_183_DATA + DDRSS_PI_184_DATA + DDRSS_PI_185_DATA + DDRSS_PI_186_DATA + DDRSS_PI_187_DATA + DDRSS_PI_188_DATA + DDRSS_PI_189_DATA + DDRSS_PI_190_DATA + DDRSS_PI_191_DATA + DDRSS_PI_192_DATA + DDRSS_PI_193_DATA + DDRSS_PI_194_DATA + DDRSS_PI_195_DATA + DDRSS_PI_196_DATA + DDRSS_PI_197_DATA + DDRSS_PI_198_DATA + DDRSS_PI_199_DATA + DDRSS_PI_200_DATA + DDRSS_PI_201_DATA + DDRSS_PI_202_DATA + DDRSS_PI_203_DATA + DDRSS_PI_204_DATA + DDRSS_PI_205_DATA + DDRSS_PI_206_DATA + DDRSS_PI_207_DATA + DDRSS_PI_208_DATA + DDRSS_PI_209_DATA + DDRSS_PI_210_DATA + DDRSS_PI_211_DATA + DDRSS_PI_212_DATA + DDRSS_PI_213_DATA + DDRSS_PI_214_DATA + DDRSS_PI_215_DATA + DDRSS_PI_216_DATA + DDRSS_PI_217_DATA + DDRSS_PI_218_DATA + DDRSS_PI_219_DATA + DDRSS_PI_220_DATA + DDRSS_PI_221_DATA + DDRSS_PI_222_DATA + DDRSS_PI_223_DATA + DDRSS_PI_224_DATA + DDRSS_PI_225_DATA + DDRSS_PI_226_DATA + DDRSS_PI_227_DATA + DDRSS_PI_228_DATA + DDRSS_PI_229_DATA + DDRSS_PI_230_DATA + DDRSS_PI_231_DATA + DDRSS_PI_232_DATA + DDRSS_PI_233_DATA + DDRSS_PI_234_DATA + DDRSS_PI_235_DATA + DDRSS_PI_236_DATA + DDRSS_PI_237_DATA + DDRSS_PI_238_DATA + DDRSS_PI_239_DATA + DDRSS_PI_240_DATA + DDRSS_PI_241_DATA + DDRSS_PI_242_DATA + DDRSS_PI_243_DATA + DDRSS_PI_244_DATA + DDRSS_PI_245_DATA + DDRSS_PI_246_DATA + DDRSS_PI_247_DATA + DDRSS_PI_248_DATA + DDRSS_PI_249_DATA + DDRSS_PI_250_DATA + DDRSS_PI_251_DATA + DDRSS_PI_252_DATA + DDRSS_PI_253_DATA + DDRSS_PI_254_DATA + DDRSS_PI_255_DATA + DDRSS_PI_256_DATA + DDRSS_PI_257_DATA + DDRSS_PI_258_DATA + DDRSS_PI_259_DATA + DDRSS_PI_260_DATA + DDRSS_PI_261_DATA + DDRSS_PI_262_DATA + DDRSS_PI_263_DATA + DDRSS_PI_264_DATA + DDRSS_PI_265_DATA + DDRSS_PI_266_DATA + DDRSS_PI_267_DATA + DDRSS_PI_268_DATA + DDRSS_PI_269_DATA + DDRSS_PI_270_DATA + DDRSS_PI_271_DATA + DDRSS_PI_272_DATA + DDRSS_PI_273_DATA + DDRSS_PI_274_DATA + DDRSS_PI_275_DATA + DDRSS_PI_276_DATA + DDRSS_PI_277_DATA + DDRSS_PI_278_DATA + DDRSS_PI_279_DATA + DDRSS_PI_280_DATA + DDRSS_PI_281_DATA + DDRSS_PI_282_DATA + DDRSS_PI_283_DATA + DDRSS_PI_284_DATA + DDRSS_PI_285_DATA + DDRSS_PI_286_DATA + DDRSS_PI_287_DATA + DDRSS_PI_288_DATA + DDRSS_PI_289_DATA + DDRSS_PI_290_DATA + DDRSS_PI_291_DATA + DDRSS_PI_292_DATA + DDRSS_PI_293_DATA + DDRSS_PI_294_DATA + DDRSS_PI_295_DATA + DDRSS_PI_296_DATA + DDRSS_PI_297_DATA + DDRSS_PI_298_DATA + DDRSS_PI_299_DATA + >; + + ti,phy-data = < + DDRSS_PHY_00_DATA + DDRSS_PHY_01_DATA + DDRSS_PHY_02_DATA + DDRSS_PHY_03_DATA + DDRSS_PHY_04_DATA + DDRSS_PHY_05_DATA + DDRSS_PHY_06_DATA + DDRSS_PHY_07_DATA + DDRSS_PHY_08_DATA + DDRSS_PHY_09_DATA + DDRSS_PHY_10_DATA + DDRSS_PHY_11_DATA + DDRSS_PHY_12_DATA + DDRSS_PHY_13_DATA + DDRSS_PHY_14_DATA + DDRSS_PHY_15_DATA + DDRSS_PHY_16_DATA + DDRSS_PHY_17_DATA + DDRSS_PHY_18_DATA + DDRSS_PHY_19_DATA + DDRSS_PHY_20_DATA + DDRSS_PHY_21_DATA + DDRSS_PHY_22_DATA + DDRSS_PHY_23_DATA + DDRSS_PHY_24_DATA + DDRSS_PHY_25_DATA + DDRSS_PHY_26_DATA + DDRSS_PHY_27_DATA + DDRSS_PHY_28_DATA + DDRSS_PHY_29_DATA + DDRSS_PHY_30_DATA + DDRSS_PHY_31_DATA + DDRSS_PHY_32_DATA + DDRSS_PHY_33_DATA + DDRSS_PHY_34_DATA + DDRSS_PHY_35_DATA + DDRSS_PHY_36_DATA + DDRSS_PHY_37_DATA + DDRSS_PHY_38_DATA + DDRSS_PHY_39_DATA + DDRSS_PHY_40_DATA + DDRSS_PHY_41_DATA + DDRSS_PHY_42_DATA + DDRSS_PHY_43_DATA + DDRSS_PHY_44_DATA + DDRSS_PHY_45_DATA + DDRSS_PHY_46_DATA + DDRSS_PHY_47_DATA + DDRSS_PHY_48_DATA + DDRSS_PHY_49_DATA + DDRSS_PHY_50_DATA + DDRSS_PHY_51_DATA + DDRSS_PHY_52_DATA + DDRSS_PHY_53_DATA + DDRSS_PHY_54_DATA + DDRSS_PHY_55_DATA + DDRSS_PHY_56_DATA + DDRSS_PHY_57_DATA + DDRSS_PHY_58_DATA + DDRSS_PHY_59_DATA + DDRSS_PHY_60_DATA + DDRSS_PHY_61_DATA + DDRSS_PHY_62_DATA + DDRSS_PHY_63_DATA + DDRSS_PHY_64_DATA + DDRSS_PHY_65_DATA + DDRSS_PHY_66_DATA + DDRSS_PHY_67_DATA + DDRSS_PHY_68_DATA + DDRSS_PHY_69_DATA + DDRSS_PHY_70_DATA + DDRSS_PHY_71_DATA + DDRSS_PHY_72_DATA + DDRSS_PHY_73_DATA + DDRSS_PHY_74_DATA + DDRSS_PHY_75_DATA + DDRSS_PHY_76_DATA + DDRSS_PHY_77_DATA + DDRSS_PHY_78_DATA + DDRSS_PHY_79_DATA + DDRSS_PHY_80_DATA + DDRSS_PHY_81_DATA + DDRSS_PHY_82_DATA + DDRSS_PHY_83_DATA + DDRSS_PHY_84_DATA + DDRSS_PHY_85_DATA + DDRSS_PHY_86_DATA + DDRSS_PHY_87_DATA + DDRSS_PHY_88_DATA + DDRSS_PHY_89_DATA + DDRSS_PHY_90_DATA + DDRSS_PHY_91_DATA + DDRSS_PHY_92_DATA + DDRSS_PHY_93_DATA + DDRSS_PHY_94_DATA + DDRSS_PHY_95_DATA + DDRSS_PHY_96_DATA + DDRSS_PHY_97_DATA + DDRSS_PHY_98_DATA + DDRSS_PHY_99_DATA + DDRSS_PHY_100_DATA + DDRSS_PHY_101_DATA + DDRSS_PHY_102_DATA + DDRSS_PHY_103_DATA + DDRSS_PHY_104_DATA + DDRSS_PHY_105_DATA + DDRSS_PHY_106_DATA + DDRSS_PHY_107_DATA + DDRSS_PHY_108_DATA + DDRSS_PHY_109_DATA + DDRSS_PHY_110_DATA + DDRSS_PHY_111_DATA + DDRSS_PHY_112_DATA + DDRSS_PHY_113_DATA + DDRSS_PHY_114_DATA + DDRSS_PHY_115_DATA + DDRSS_PHY_116_DATA + DDRSS_PHY_117_DATA + DDRSS_PHY_118_DATA + DDRSS_PHY_119_DATA + DDRSS_PHY_120_DATA + DDRSS_PHY_121_DATA + DDRSS_PHY_122_DATA + DDRSS_PHY_123_DATA + DDRSS_PHY_124_DATA + DDRSS_PHY_125_DATA + DDRSS_PHY_126_DATA + DDRSS_PHY_127_DATA + DDRSS_PHY_128_DATA + DDRSS_PHY_129_DATA + DDRSS_PHY_130_DATA + DDRSS_PHY_131_DATA + DDRSS_PHY_132_DATA + DDRSS_PHY_133_DATA + DDRSS_PHY_134_DATA + DDRSS_PHY_135_DATA + DDRSS_PHY_136_DATA + DDRSS_PHY_137_DATA + DDRSS_PHY_138_DATA + DDRSS_PHY_139_DATA + DDRSS_PHY_140_DATA + DDRSS_PHY_141_DATA + DDRSS_PHY_142_DATA + DDRSS_PHY_143_DATA + DDRSS_PHY_144_DATA + DDRSS_PHY_145_DATA + DDRSS_PHY_146_DATA + DDRSS_PHY_147_DATA + DDRSS_PHY_148_DATA + DDRSS_PHY_149_DATA + DDRSS_PHY_150_DATA + DDRSS_PHY_151_DATA + DDRSS_PHY_152_DATA + DDRSS_PHY_153_DATA + DDRSS_PHY_154_DATA + DDRSS_PHY_155_DATA + DDRSS_PHY_156_DATA + DDRSS_PHY_157_DATA + DDRSS_PHY_158_DATA + DDRSS_PHY_159_DATA + DDRSS_PHY_160_DATA + DDRSS_PHY_161_DATA + DDRSS_PHY_162_DATA + DDRSS_PHY_163_DATA + DDRSS_PHY_164_DATA + DDRSS_PHY_165_DATA + DDRSS_PHY_166_DATA + DDRSS_PHY_167_DATA + DDRSS_PHY_168_DATA + DDRSS_PHY_169_DATA + DDRSS_PHY_170_DATA + DDRSS_PHY_171_DATA + DDRSS_PHY_172_DATA + DDRSS_PHY_173_DATA + DDRSS_PHY_174_DATA + DDRSS_PHY_175_DATA + DDRSS_PHY_176_DATA + DDRSS_PHY_177_DATA + DDRSS_PHY_178_DATA + DDRSS_PHY_179_DATA + DDRSS_PHY_180_DATA + DDRSS_PHY_181_DATA + DDRSS_PHY_182_DATA + DDRSS_PHY_183_DATA + DDRSS_PHY_184_DATA + DDRSS_PHY_185_DATA + DDRSS_PHY_186_DATA + DDRSS_PHY_187_DATA + DDRSS_PHY_188_DATA + DDRSS_PHY_189_DATA + DDRSS_PHY_190_DATA + DDRSS_PHY_191_DATA + DDRSS_PHY_192_DATA + DDRSS_PHY_193_DATA + DDRSS_PHY_194_DATA + DDRSS_PHY_195_DATA + DDRSS_PHY_196_DATA + DDRSS_PHY_197_DATA + DDRSS_PHY_198_DATA + DDRSS_PHY_199_DATA + DDRSS_PHY_200_DATA + DDRSS_PHY_201_DATA + DDRSS_PHY_202_DATA + DDRSS_PHY_203_DATA + DDRSS_PHY_204_DATA + DDRSS_PHY_205_DATA + DDRSS_PHY_206_DATA + DDRSS_PHY_207_DATA + DDRSS_PHY_208_DATA + DDRSS_PHY_209_DATA + DDRSS_PHY_210_DATA + DDRSS_PHY_211_DATA + DDRSS_PHY_212_DATA + DDRSS_PHY_213_DATA + DDRSS_PHY_214_DATA + DDRSS_PHY_215_DATA + DDRSS_PHY_216_DATA + DDRSS_PHY_217_DATA + DDRSS_PHY_218_DATA + DDRSS_PHY_219_DATA + DDRSS_PHY_220_DATA + DDRSS_PHY_221_DATA + DDRSS_PHY_222_DATA + DDRSS_PHY_223_DATA + DDRSS_PHY_224_DATA + DDRSS_PHY_225_DATA + DDRSS_PHY_226_DATA + DDRSS_PHY_227_DATA + DDRSS_PHY_228_DATA + DDRSS_PHY_229_DATA + DDRSS_PHY_230_DATA + DDRSS_PHY_231_DATA + DDRSS_PHY_232_DATA + DDRSS_PHY_233_DATA + DDRSS_PHY_234_DATA + DDRSS_PHY_235_DATA + DDRSS_PHY_236_DATA + DDRSS_PHY_237_DATA + DDRSS_PHY_238_DATA + DDRSS_PHY_239_DATA + DDRSS_PHY_240_DATA + DDRSS_PHY_241_DATA + DDRSS_PHY_242_DATA + DDRSS_PHY_243_DATA + DDRSS_PHY_244_DATA + DDRSS_PHY_245_DATA + DDRSS_PHY_246_DATA + DDRSS_PHY_247_DATA + DDRSS_PHY_248_DATA + DDRSS_PHY_249_DATA + DDRSS_PHY_250_DATA + DDRSS_PHY_251_DATA + DDRSS_PHY_252_DATA + DDRSS_PHY_253_DATA + DDRSS_PHY_254_DATA + DDRSS_PHY_255_DATA + DDRSS_PHY_256_DATA + DDRSS_PHY_257_DATA + DDRSS_PHY_258_DATA + DDRSS_PHY_259_DATA + DDRSS_PHY_260_DATA + DDRSS_PHY_261_DATA + DDRSS_PHY_262_DATA + DDRSS_PHY_263_DATA + DDRSS_PHY_264_DATA + DDRSS_PHY_265_DATA + DDRSS_PHY_266_DATA + DDRSS_PHY_267_DATA + DDRSS_PHY_268_DATA + DDRSS_PHY_269_DATA + DDRSS_PHY_270_DATA + DDRSS_PHY_271_DATA + DDRSS_PHY_272_DATA + DDRSS_PHY_273_DATA + DDRSS_PHY_274_DATA + DDRSS_PHY_275_DATA + DDRSS_PHY_276_DATA + DDRSS_PHY_277_DATA + DDRSS_PHY_278_DATA + DDRSS_PHY_279_DATA + DDRSS_PHY_280_DATA + DDRSS_PHY_281_DATA + DDRSS_PHY_282_DATA + DDRSS_PHY_283_DATA + DDRSS_PHY_284_DATA + DDRSS_PHY_285_DATA + DDRSS_PHY_286_DATA + DDRSS_PHY_287_DATA + DDRSS_PHY_288_DATA + DDRSS_PHY_289_DATA + DDRSS_PHY_290_DATA + DDRSS_PHY_291_DATA + DDRSS_PHY_292_DATA + DDRSS_PHY_293_DATA + DDRSS_PHY_294_DATA + DDRSS_PHY_295_DATA + DDRSS_PHY_296_DATA + DDRSS_PHY_297_DATA + DDRSS_PHY_298_DATA + DDRSS_PHY_299_DATA + DDRSS_PHY_300_DATA + DDRSS_PHY_301_DATA + DDRSS_PHY_302_DATA + DDRSS_PHY_303_DATA + DDRSS_PHY_304_DATA + DDRSS_PHY_305_DATA + DDRSS_PHY_306_DATA + DDRSS_PHY_307_DATA + DDRSS_PHY_308_DATA + DDRSS_PHY_309_DATA + DDRSS_PHY_310_DATA + DDRSS_PHY_311_DATA + DDRSS_PHY_312_DATA + DDRSS_PHY_313_DATA + DDRSS_PHY_314_DATA + DDRSS_PHY_315_DATA + DDRSS_PHY_316_DATA + DDRSS_PHY_317_DATA + DDRSS_PHY_318_DATA + DDRSS_PHY_319_DATA + DDRSS_PHY_320_DATA + DDRSS_PHY_321_DATA + DDRSS_PHY_322_DATA + DDRSS_PHY_323_DATA + DDRSS_PHY_324_DATA + DDRSS_PHY_325_DATA + DDRSS_PHY_326_DATA + DDRSS_PHY_327_DATA + DDRSS_PHY_328_DATA + DDRSS_PHY_329_DATA + DDRSS_PHY_330_DATA + DDRSS_PHY_331_DATA + DDRSS_PHY_332_DATA + DDRSS_PHY_333_DATA + DDRSS_PHY_334_DATA + DDRSS_PHY_335_DATA + DDRSS_PHY_336_DATA + DDRSS_PHY_337_DATA + DDRSS_PHY_338_DATA + DDRSS_PHY_339_DATA + DDRSS_PHY_340_DATA + DDRSS_PHY_341_DATA + DDRSS_PHY_342_DATA + DDRSS_PHY_343_DATA + DDRSS_PHY_344_DATA + DDRSS_PHY_345_DATA + DDRSS_PHY_346_DATA + DDRSS_PHY_347_DATA + DDRSS_PHY_348_DATA + DDRSS_PHY_349_DATA + DDRSS_PHY_350_DATA + DDRSS_PHY_351_DATA + DDRSS_PHY_352_DATA + DDRSS_PHY_353_DATA + DDRSS_PHY_354_DATA + DDRSS_PHY_355_DATA + DDRSS_PHY_356_DATA + DDRSS_PHY_357_DATA + DDRSS_PHY_358_DATA + DDRSS_PHY_359_DATA + DDRSS_PHY_360_DATA + DDRSS_PHY_361_DATA + DDRSS_PHY_362_DATA + DDRSS_PHY_363_DATA + DDRSS_PHY_364_DATA + DDRSS_PHY_365_DATA + DDRSS_PHY_366_DATA + DDRSS_PHY_367_DATA + DDRSS_PHY_368_DATA + DDRSS_PHY_369_DATA + DDRSS_PHY_370_DATA + DDRSS_PHY_371_DATA + DDRSS_PHY_372_DATA + DDRSS_PHY_373_DATA + DDRSS_PHY_374_DATA + DDRSS_PHY_375_DATA + DDRSS_PHY_376_DATA + DDRSS_PHY_377_DATA + DDRSS_PHY_378_DATA + DDRSS_PHY_379_DATA + DDRSS_PHY_380_DATA + DDRSS_PHY_381_DATA + DDRSS_PHY_382_DATA + DDRSS_PHY_383_DATA + DDRSS_PHY_384_DATA + DDRSS_PHY_385_DATA + DDRSS_PHY_386_DATA + DDRSS_PHY_387_DATA + DDRSS_PHY_388_DATA + DDRSS_PHY_389_DATA + DDRSS_PHY_390_DATA + DDRSS_PHY_391_DATA + DDRSS_PHY_392_DATA + DDRSS_PHY_393_DATA + DDRSS_PHY_394_DATA + DDRSS_PHY_395_DATA + DDRSS_PHY_396_DATA + DDRSS_PHY_397_DATA + DDRSS_PHY_398_DATA + DDRSS_PHY_399_DATA + DDRSS_PHY_400_DATA + DDRSS_PHY_401_DATA + DDRSS_PHY_402_DATA + DDRSS_PHY_403_DATA + DDRSS_PHY_404_DATA + DDRSS_PHY_405_DATA + DDRSS_PHY_406_DATA + DDRSS_PHY_407_DATA + DDRSS_PHY_408_DATA + DDRSS_PHY_409_DATA + DDRSS_PHY_410_DATA + DDRSS_PHY_411_DATA + DDRSS_PHY_412_DATA + DDRSS_PHY_413_DATA + DDRSS_PHY_414_DATA + DDRSS_PHY_415_DATA + DDRSS_PHY_416_DATA + DDRSS_PHY_417_DATA + DDRSS_PHY_418_DATA + DDRSS_PHY_419_DATA + DDRSS_PHY_420_DATA + DDRSS_PHY_421_DATA + DDRSS_PHY_422_DATA + DDRSS_PHY_423_DATA + DDRSS_PHY_424_DATA + DDRSS_PHY_425_DATA + DDRSS_PHY_426_DATA + DDRSS_PHY_427_DATA + DDRSS_PHY_428_DATA + DDRSS_PHY_429_DATA + DDRSS_PHY_430_DATA + DDRSS_PHY_431_DATA + DDRSS_PHY_432_DATA + DDRSS_PHY_433_DATA + DDRSS_PHY_434_DATA + DDRSS_PHY_435_DATA + DDRSS_PHY_436_DATA + DDRSS_PHY_437_DATA + DDRSS_PHY_438_DATA + DDRSS_PHY_439_DATA + DDRSS_PHY_440_DATA + DDRSS_PHY_441_DATA + DDRSS_PHY_442_DATA + DDRSS_PHY_443_DATA + DDRSS_PHY_444_DATA + DDRSS_PHY_445_DATA + DDRSS_PHY_446_DATA + DDRSS_PHY_447_DATA + DDRSS_PHY_448_DATA + DDRSS_PHY_449_DATA + DDRSS_PHY_450_DATA + DDRSS_PHY_451_DATA + DDRSS_PHY_452_DATA + DDRSS_PHY_453_DATA + DDRSS_PHY_454_DATA + DDRSS_PHY_455_DATA + DDRSS_PHY_456_DATA + DDRSS_PHY_457_DATA + DDRSS_PHY_458_DATA + DDRSS_PHY_459_DATA + DDRSS_PHY_460_DATA + DDRSS_PHY_461_DATA + DDRSS_PHY_462_DATA + DDRSS_PHY_463_DATA + DDRSS_PHY_464_DATA + DDRSS_PHY_465_DATA + DDRSS_PHY_466_DATA + DDRSS_PHY_467_DATA + DDRSS_PHY_468_DATA + DDRSS_PHY_469_DATA + DDRSS_PHY_470_DATA + DDRSS_PHY_471_DATA + DDRSS_PHY_472_DATA + DDRSS_PHY_473_DATA + DDRSS_PHY_474_DATA + DDRSS_PHY_475_DATA + DDRSS_PHY_476_DATA + DDRSS_PHY_477_DATA + DDRSS_PHY_478_DATA + DDRSS_PHY_479_DATA + DDRSS_PHY_480_DATA + DDRSS_PHY_481_DATA + DDRSS_PHY_482_DATA + DDRSS_PHY_483_DATA + DDRSS_PHY_484_DATA + DDRSS_PHY_485_DATA + DDRSS_PHY_486_DATA + DDRSS_PHY_487_DATA + DDRSS_PHY_488_DATA + DDRSS_PHY_489_DATA + DDRSS_PHY_490_DATA + DDRSS_PHY_491_DATA + DDRSS_PHY_492_DATA + DDRSS_PHY_493_DATA + DDRSS_PHY_494_DATA + DDRSS_PHY_495_DATA + DDRSS_PHY_496_DATA + DDRSS_PHY_497_DATA + DDRSS_PHY_498_DATA + DDRSS_PHY_499_DATA + DDRSS_PHY_500_DATA + DDRSS_PHY_501_DATA + DDRSS_PHY_502_DATA + DDRSS_PHY_503_DATA + DDRSS_PHY_504_DATA + DDRSS_PHY_505_DATA + DDRSS_PHY_506_DATA + DDRSS_PHY_507_DATA + DDRSS_PHY_508_DATA + DDRSS_PHY_509_DATA + DDRSS_PHY_510_DATA + DDRSS_PHY_511_DATA + DDRSS_PHY_512_DATA + DDRSS_PHY_513_DATA + DDRSS_PHY_514_DATA + DDRSS_PHY_515_DATA + DDRSS_PHY_516_DATA + DDRSS_PHY_517_DATA + DDRSS_PHY_518_DATA + DDRSS_PHY_519_DATA + DDRSS_PHY_520_DATA + DDRSS_PHY_521_DATA + DDRSS_PHY_522_DATA + DDRSS_PHY_523_DATA + DDRSS_PHY_524_DATA + DDRSS_PHY_525_DATA + DDRSS_PHY_526_DATA + DDRSS_PHY_527_DATA + DDRSS_PHY_528_DATA + DDRSS_PHY_529_DATA + DDRSS_PHY_530_DATA + DDRSS_PHY_531_DATA + DDRSS_PHY_532_DATA + DDRSS_PHY_533_DATA + DDRSS_PHY_534_DATA + DDRSS_PHY_535_DATA + DDRSS_PHY_536_DATA + DDRSS_PHY_537_DATA + DDRSS_PHY_538_DATA + DDRSS_PHY_539_DATA + DDRSS_PHY_540_DATA + DDRSS_PHY_541_DATA + DDRSS_PHY_542_DATA + DDRSS_PHY_543_DATA + DDRSS_PHY_544_DATA + DDRSS_PHY_545_DATA + DDRSS_PHY_546_DATA + DDRSS_PHY_547_DATA + DDRSS_PHY_548_DATA + DDRSS_PHY_549_DATA + DDRSS_PHY_550_DATA + DDRSS_PHY_551_DATA + DDRSS_PHY_552_DATA + DDRSS_PHY_553_DATA + DDRSS_PHY_554_DATA + DDRSS_PHY_555_DATA + DDRSS_PHY_556_DATA + DDRSS_PHY_557_DATA + DDRSS_PHY_558_DATA + DDRSS_PHY_559_DATA + DDRSS_PHY_560_DATA + DDRSS_PHY_561_DATA + DDRSS_PHY_562_DATA + DDRSS_PHY_563_DATA + DDRSS_PHY_564_DATA + DDRSS_PHY_565_DATA + DDRSS_PHY_566_DATA + DDRSS_PHY_567_DATA + DDRSS_PHY_568_DATA + DDRSS_PHY_569_DATA + DDRSS_PHY_570_DATA + DDRSS_PHY_571_DATA + DDRSS_PHY_572_DATA + DDRSS_PHY_573_DATA + DDRSS_PHY_574_DATA + DDRSS_PHY_575_DATA + DDRSS_PHY_576_DATA + DDRSS_PHY_577_DATA + DDRSS_PHY_578_DATA + DDRSS_PHY_579_DATA + DDRSS_PHY_580_DATA + DDRSS_PHY_581_DATA + DDRSS_PHY_582_DATA + DDRSS_PHY_583_DATA + DDRSS_PHY_584_DATA + DDRSS_PHY_585_DATA + DDRSS_PHY_586_DATA + DDRSS_PHY_587_DATA + DDRSS_PHY_588_DATA + DDRSS_PHY_589_DATA + DDRSS_PHY_590_DATA + DDRSS_PHY_591_DATA + DDRSS_PHY_592_DATA + DDRSS_PHY_593_DATA + DDRSS_PHY_594_DATA + DDRSS_PHY_595_DATA + DDRSS_PHY_596_DATA + DDRSS_PHY_597_DATA + DDRSS_PHY_598_DATA + DDRSS_PHY_599_DATA + DDRSS_PHY_600_DATA + DDRSS_PHY_601_DATA + DDRSS_PHY_602_DATA + DDRSS_PHY_603_DATA + DDRSS_PHY_604_DATA + DDRSS_PHY_605_DATA + DDRSS_PHY_606_DATA + DDRSS_PHY_607_DATA + DDRSS_PHY_608_DATA + DDRSS_PHY_609_DATA + DDRSS_PHY_610_DATA + DDRSS_PHY_611_DATA + DDRSS_PHY_612_DATA + DDRSS_PHY_613_DATA + DDRSS_PHY_614_DATA + DDRSS_PHY_615_DATA + DDRSS_PHY_616_DATA + DDRSS_PHY_617_DATA + DDRSS_PHY_618_DATA + DDRSS_PHY_619_DATA + DDRSS_PHY_620_DATA + DDRSS_PHY_621_DATA + DDRSS_PHY_622_DATA + DDRSS_PHY_623_DATA + DDRSS_PHY_624_DATA + DDRSS_PHY_625_DATA + DDRSS_PHY_626_DATA + DDRSS_PHY_627_DATA + DDRSS_PHY_628_DATA + DDRSS_PHY_629_DATA + DDRSS_PHY_630_DATA + DDRSS_PHY_631_DATA + DDRSS_PHY_632_DATA + DDRSS_PHY_633_DATA + DDRSS_PHY_634_DATA + DDRSS_PHY_635_DATA + DDRSS_PHY_636_DATA + DDRSS_PHY_637_DATA + DDRSS_PHY_638_DATA + DDRSS_PHY_639_DATA + DDRSS_PHY_640_DATA + DDRSS_PHY_641_DATA + DDRSS_PHY_642_DATA + DDRSS_PHY_643_DATA + DDRSS_PHY_644_DATA + DDRSS_PHY_645_DATA + DDRSS_PHY_646_DATA + DDRSS_PHY_647_DATA + DDRSS_PHY_648_DATA + DDRSS_PHY_649_DATA + DDRSS_PHY_650_DATA + DDRSS_PHY_651_DATA + DDRSS_PHY_652_DATA + DDRSS_PHY_653_DATA + DDRSS_PHY_654_DATA + DDRSS_PHY_655_DATA + DDRSS_PHY_656_DATA + DDRSS_PHY_657_DATA + DDRSS_PHY_658_DATA + DDRSS_PHY_659_DATA + DDRSS_PHY_660_DATA + DDRSS_PHY_661_DATA + DDRSS_PHY_662_DATA + DDRSS_PHY_663_DATA + DDRSS_PHY_664_DATA + DDRSS_PHY_665_DATA + DDRSS_PHY_666_DATA + DDRSS_PHY_667_DATA + DDRSS_PHY_668_DATA + DDRSS_PHY_669_DATA + DDRSS_PHY_670_DATA + DDRSS_PHY_671_DATA + DDRSS_PHY_672_DATA + DDRSS_PHY_673_DATA + DDRSS_PHY_674_DATA + DDRSS_PHY_675_DATA + DDRSS_PHY_676_DATA + DDRSS_PHY_677_DATA + DDRSS_PHY_678_DATA + DDRSS_PHY_679_DATA + DDRSS_PHY_680_DATA + DDRSS_PHY_681_DATA + DDRSS_PHY_682_DATA + DDRSS_PHY_683_DATA + DDRSS_PHY_684_DATA + DDRSS_PHY_685_DATA + DDRSS_PHY_686_DATA + DDRSS_PHY_687_DATA + DDRSS_PHY_688_DATA + DDRSS_PHY_689_DATA + DDRSS_PHY_690_DATA + DDRSS_PHY_691_DATA + DDRSS_PHY_692_DATA + DDRSS_PHY_693_DATA + DDRSS_PHY_694_DATA + DDRSS_PHY_695_DATA + DDRSS_PHY_696_DATA + DDRSS_PHY_697_DATA + DDRSS_PHY_698_DATA + DDRSS_PHY_699_DATA + DDRSS_PHY_700_DATA + DDRSS_PHY_701_DATA + DDRSS_PHY_702_DATA + DDRSS_PHY_703_DATA + DDRSS_PHY_704_DATA + DDRSS_PHY_705_DATA + DDRSS_PHY_706_DATA + DDRSS_PHY_707_DATA + DDRSS_PHY_708_DATA + DDRSS_PHY_709_DATA + DDRSS_PHY_710_DATA + DDRSS_PHY_711_DATA + DDRSS_PHY_712_DATA + DDRSS_PHY_713_DATA + DDRSS_PHY_714_DATA + DDRSS_PHY_715_DATA + DDRSS_PHY_716_DATA + DDRSS_PHY_717_DATA + DDRSS_PHY_718_DATA + DDRSS_PHY_719_DATA + DDRSS_PHY_720_DATA + DDRSS_PHY_721_DATA + DDRSS_PHY_722_DATA + DDRSS_PHY_723_DATA + DDRSS_PHY_724_DATA + DDRSS_PHY_725_DATA + DDRSS_PHY_726_DATA + DDRSS_PHY_727_DATA + DDRSS_PHY_728_DATA + DDRSS_PHY_729_DATA + DDRSS_PHY_730_DATA + DDRSS_PHY_731_DATA + DDRSS_PHY_732_DATA + DDRSS_PHY_733_DATA + DDRSS_PHY_734_DATA + DDRSS_PHY_735_DATA + DDRSS_PHY_736_DATA + DDRSS_PHY_737_DATA + DDRSS_PHY_738_DATA + DDRSS_PHY_739_DATA + DDRSS_PHY_740_DATA + DDRSS_PHY_741_DATA + DDRSS_PHY_742_DATA + DDRSS_PHY_743_DATA + DDRSS_PHY_744_DATA + DDRSS_PHY_745_DATA + DDRSS_PHY_746_DATA + DDRSS_PHY_747_DATA + DDRSS_PHY_748_DATA + DDRSS_PHY_749_DATA + DDRSS_PHY_750_DATA + DDRSS_PHY_751_DATA + DDRSS_PHY_752_DATA + DDRSS_PHY_753_DATA + DDRSS_PHY_754_DATA + DDRSS_PHY_755_DATA + DDRSS_PHY_756_DATA + DDRSS_PHY_757_DATA + DDRSS_PHY_758_DATA + DDRSS_PHY_759_DATA + DDRSS_PHY_760_DATA + DDRSS_PHY_761_DATA + DDRSS_PHY_762_DATA + DDRSS_PHY_763_DATA + DDRSS_PHY_764_DATA + DDRSS_PHY_765_DATA + DDRSS_PHY_766_DATA + DDRSS_PHY_767_DATA + DDRSS_PHY_768_DATA + DDRSS_PHY_769_DATA + DDRSS_PHY_770_DATA + DDRSS_PHY_771_DATA + DDRSS_PHY_772_DATA + DDRSS_PHY_773_DATA + DDRSS_PHY_774_DATA + DDRSS_PHY_775_DATA + DDRSS_PHY_776_DATA + DDRSS_PHY_777_DATA + DDRSS_PHY_778_DATA + DDRSS_PHY_779_DATA + DDRSS_PHY_780_DATA + DDRSS_PHY_781_DATA + DDRSS_PHY_782_DATA + DDRSS_PHY_783_DATA + DDRSS_PHY_784_DATA + DDRSS_PHY_785_DATA + DDRSS_PHY_786_DATA + DDRSS_PHY_787_DATA + DDRSS_PHY_788_DATA + DDRSS_PHY_789_DATA + DDRSS_PHY_790_DATA + DDRSS_PHY_791_DATA + DDRSS_PHY_792_DATA + DDRSS_PHY_793_DATA + DDRSS_PHY_794_DATA + DDRSS_PHY_795_DATA + DDRSS_PHY_796_DATA + DDRSS_PHY_797_DATA + DDRSS_PHY_798_DATA + DDRSS_PHY_799_DATA + DDRSS_PHY_800_DATA + DDRSS_PHY_801_DATA + DDRSS_PHY_802_DATA + DDRSS_PHY_803_DATA + DDRSS_PHY_804_DATA + DDRSS_PHY_805_DATA + DDRSS_PHY_806_DATA + DDRSS_PHY_807_DATA + DDRSS_PHY_808_DATA + DDRSS_PHY_809_DATA + DDRSS_PHY_810_DATA + DDRSS_PHY_811_DATA + DDRSS_PHY_812_DATA + DDRSS_PHY_813_DATA + DDRSS_PHY_814_DATA + DDRSS_PHY_815_DATA + DDRSS_PHY_816_DATA + DDRSS_PHY_817_DATA + DDRSS_PHY_818_DATA + DDRSS_PHY_819_DATA + DDRSS_PHY_820_DATA + DDRSS_PHY_821_DATA + DDRSS_PHY_822_DATA + DDRSS_PHY_823_DATA + DDRSS_PHY_824_DATA + DDRSS_PHY_825_DATA + DDRSS_PHY_826_DATA + DDRSS_PHY_827_DATA + DDRSS_PHY_828_DATA + DDRSS_PHY_829_DATA + DDRSS_PHY_830_DATA + DDRSS_PHY_831_DATA + DDRSS_PHY_832_DATA + DDRSS_PHY_833_DATA + DDRSS_PHY_834_DATA + DDRSS_PHY_835_DATA + DDRSS_PHY_836_DATA + DDRSS_PHY_837_DATA + DDRSS_PHY_838_DATA + DDRSS_PHY_839_DATA + DDRSS_PHY_840_DATA + DDRSS_PHY_841_DATA + DDRSS_PHY_842_DATA + DDRSS_PHY_843_DATA + DDRSS_PHY_844_DATA + DDRSS_PHY_845_DATA + DDRSS_PHY_846_DATA + DDRSS_PHY_847_DATA + DDRSS_PHY_848_DATA + DDRSS_PHY_849_DATA + DDRSS_PHY_850_DATA + DDRSS_PHY_851_DATA + DDRSS_PHY_852_DATA + DDRSS_PHY_853_DATA + DDRSS_PHY_854_DATA + DDRSS_PHY_855_DATA + DDRSS_PHY_856_DATA + DDRSS_PHY_857_DATA + DDRSS_PHY_858_DATA + DDRSS_PHY_859_DATA + DDRSS_PHY_860_DATA + DDRSS_PHY_861_DATA + DDRSS_PHY_862_DATA + DDRSS_PHY_863_DATA + DDRSS_PHY_864_DATA + DDRSS_PHY_865_DATA + DDRSS_PHY_866_DATA + DDRSS_PHY_867_DATA + DDRSS_PHY_868_DATA + DDRSS_PHY_869_DATA + DDRSS_PHY_870_DATA + DDRSS_PHY_871_DATA + DDRSS_PHY_872_DATA + DDRSS_PHY_873_DATA + DDRSS_PHY_874_DATA + DDRSS_PHY_875_DATA + DDRSS_PHY_876_DATA + DDRSS_PHY_877_DATA + DDRSS_PHY_878_DATA + DDRSS_PHY_879_DATA + DDRSS_PHY_880_DATA + DDRSS_PHY_881_DATA + DDRSS_PHY_882_DATA + DDRSS_PHY_883_DATA + DDRSS_PHY_884_DATA + DDRSS_PHY_885_DATA + DDRSS_PHY_886_DATA + DDRSS_PHY_887_DATA + DDRSS_PHY_888_DATA + DDRSS_PHY_889_DATA + DDRSS_PHY_890_DATA + DDRSS_PHY_891_DATA + DDRSS_PHY_892_DATA + DDRSS_PHY_893_DATA + DDRSS_PHY_894_DATA + DDRSS_PHY_895_DATA + DDRSS_PHY_896_DATA + DDRSS_PHY_897_DATA + DDRSS_PHY_898_DATA + DDRSS_PHY_899_DATA + DDRSS_PHY_900_DATA + DDRSS_PHY_901_DATA + DDRSS_PHY_902_DATA + DDRSS_PHY_903_DATA + DDRSS_PHY_904_DATA + DDRSS_PHY_905_DATA + DDRSS_PHY_906_DATA + DDRSS_PHY_907_DATA + DDRSS_PHY_908_DATA + DDRSS_PHY_909_DATA + DDRSS_PHY_910_DATA + DDRSS_PHY_911_DATA + DDRSS_PHY_912_DATA + DDRSS_PHY_913_DATA + DDRSS_PHY_914_DATA + DDRSS_PHY_915_DATA + DDRSS_PHY_916_DATA + DDRSS_PHY_917_DATA + DDRSS_PHY_918_DATA + DDRSS_PHY_919_DATA + DDRSS_PHY_920_DATA + DDRSS_PHY_921_DATA + DDRSS_PHY_922_DATA + DDRSS_PHY_923_DATA + DDRSS_PHY_924_DATA + DDRSS_PHY_925_DATA + DDRSS_PHY_926_DATA + DDRSS_PHY_927_DATA + DDRSS_PHY_928_DATA + DDRSS_PHY_929_DATA + DDRSS_PHY_930_DATA + DDRSS_PHY_931_DATA + DDRSS_PHY_932_DATA + DDRSS_PHY_933_DATA + DDRSS_PHY_934_DATA + DDRSS_PHY_935_DATA + DDRSS_PHY_936_DATA + DDRSS_PHY_937_DATA + DDRSS_PHY_938_DATA + DDRSS_PHY_939_DATA + DDRSS_PHY_940_DATA + DDRSS_PHY_941_DATA + DDRSS_PHY_942_DATA + DDRSS_PHY_943_DATA + DDRSS_PHY_944_DATA + DDRSS_PHY_945_DATA + DDRSS_PHY_946_DATA + DDRSS_PHY_947_DATA + DDRSS_PHY_948_DATA + DDRSS_PHY_949_DATA + DDRSS_PHY_950_DATA + DDRSS_PHY_951_DATA + DDRSS_PHY_952_DATA + DDRSS_PHY_953_DATA + DDRSS_PHY_954_DATA + DDRSS_PHY_955_DATA + DDRSS_PHY_956_DATA + DDRSS_PHY_957_DATA + DDRSS_PHY_958_DATA + DDRSS_PHY_959_DATA + DDRSS_PHY_960_DATA + DDRSS_PHY_961_DATA + DDRSS_PHY_962_DATA + DDRSS_PHY_963_DATA + DDRSS_PHY_964_DATA + DDRSS_PHY_965_DATA + DDRSS_PHY_966_DATA + DDRSS_PHY_967_DATA + DDRSS_PHY_968_DATA + DDRSS_PHY_969_DATA + DDRSS_PHY_970_DATA + DDRSS_PHY_971_DATA + DDRSS_PHY_972_DATA + DDRSS_PHY_973_DATA + DDRSS_PHY_974_DATA + DDRSS_PHY_975_DATA + DDRSS_PHY_976_DATA + DDRSS_PHY_977_DATA + DDRSS_PHY_978_DATA + DDRSS_PHY_979_DATA + DDRSS_PHY_980_DATA + DDRSS_PHY_981_DATA + DDRSS_PHY_982_DATA + DDRSS_PHY_983_DATA + DDRSS_PHY_984_DATA + DDRSS_PHY_985_DATA + DDRSS_PHY_986_DATA + DDRSS_PHY_987_DATA + DDRSS_PHY_988_DATA + DDRSS_PHY_989_DATA + DDRSS_PHY_990_DATA + DDRSS_PHY_991_DATA + DDRSS_PHY_992_DATA + DDRSS_PHY_993_DATA + DDRSS_PHY_994_DATA + DDRSS_PHY_995_DATA + DDRSS_PHY_996_DATA + DDRSS_PHY_997_DATA + DDRSS_PHY_998_DATA + DDRSS_PHY_999_DATA + DDRSS_PHY_1000_DATA + DDRSS_PHY_1001_DATA + DDRSS_PHY_1002_DATA + DDRSS_PHY_1003_DATA + DDRSS_PHY_1004_DATA + DDRSS_PHY_1005_DATA + DDRSS_PHY_1006_DATA + DDRSS_PHY_1007_DATA + DDRSS_PHY_1008_DATA + DDRSS_PHY_1009_DATA + DDRSS_PHY_1010_DATA + DDRSS_PHY_1011_DATA + DDRSS_PHY_1012_DATA + DDRSS_PHY_1013_DATA + DDRSS_PHY_1014_DATA + DDRSS_PHY_1015_DATA + DDRSS_PHY_1016_DATA + DDRSS_PHY_1017_DATA + DDRSS_PHY_1018_DATA + DDRSS_PHY_1019_DATA + DDRSS_PHY_1020_DATA + DDRSS_PHY_1021_DATA + DDRSS_PHY_1022_DATA + DDRSS_PHY_1023_DATA + DDRSS_PHY_1024_DATA + DDRSS_PHY_1025_DATA + DDRSS_PHY_1026_DATA + DDRSS_PHY_1027_DATA + DDRSS_PHY_1028_DATA + DDRSS_PHY_1029_DATA + DDRSS_PHY_1030_DATA + DDRSS_PHY_1031_DATA + DDRSS_PHY_1032_DATA + DDRSS_PHY_1033_DATA + DDRSS_PHY_1034_DATA + DDRSS_PHY_1035_DATA + DDRSS_PHY_1036_DATA + DDRSS_PHY_1037_DATA + DDRSS_PHY_1038_DATA + DDRSS_PHY_1039_DATA + DDRSS_PHY_1040_DATA + DDRSS_PHY_1041_DATA + DDRSS_PHY_1042_DATA + DDRSS_PHY_1043_DATA + DDRSS_PHY_1044_DATA + DDRSS_PHY_1045_DATA + DDRSS_PHY_1046_DATA + DDRSS_PHY_1047_DATA + DDRSS_PHY_1048_DATA + DDRSS_PHY_1049_DATA + DDRSS_PHY_1050_DATA + DDRSS_PHY_1051_DATA + DDRSS_PHY_1052_DATA + DDRSS_PHY_1053_DATA + DDRSS_PHY_1054_DATA + DDRSS_PHY_1055_DATA + DDRSS_PHY_1056_DATA + DDRSS_PHY_1057_DATA + DDRSS_PHY_1058_DATA + DDRSS_PHY_1059_DATA + DDRSS_PHY_1060_DATA + DDRSS_PHY_1061_DATA + DDRSS_PHY_1062_DATA + DDRSS_PHY_1063_DATA + DDRSS_PHY_1064_DATA + DDRSS_PHY_1065_DATA + DDRSS_PHY_1066_DATA + DDRSS_PHY_1067_DATA + DDRSS_PHY_1068_DATA + DDRSS_PHY_1069_DATA + DDRSS_PHY_1070_DATA + DDRSS_PHY_1071_DATA + DDRSS_PHY_1072_DATA + DDRSS_PHY_1073_DATA + DDRSS_PHY_1074_DATA + DDRSS_PHY_1075_DATA + DDRSS_PHY_1076_DATA + DDRSS_PHY_1077_DATA + DDRSS_PHY_1078_DATA + DDRSS_PHY_1079_DATA + DDRSS_PHY_1080_DATA + DDRSS_PHY_1081_DATA + DDRSS_PHY_1082_DATA + DDRSS_PHY_1083_DATA + DDRSS_PHY_1084_DATA + DDRSS_PHY_1085_DATA + DDRSS_PHY_1086_DATA + DDRSS_PHY_1087_DATA + DDRSS_PHY_1088_DATA + DDRSS_PHY_1089_DATA + DDRSS_PHY_1090_DATA + DDRSS_PHY_1091_DATA + DDRSS_PHY_1092_DATA + DDRSS_PHY_1093_DATA + DDRSS_PHY_1094_DATA + DDRSS_PHY_1095_DATA + DDRSS_PHY_1096_DATA + DDRSS_PHY_1097_DATA + DDRSS_PHY_1098_DATA + DDRSS_PHY_1099_DATA + DDRSS_PHY_1100_DATA + DDRSS_PHY_1101_DATA + DDRSS_PHY_1102_DATA + DDRSS_PHY_1103_DATA + DDRSS_PHY_1104_DATA + DDRSS_PHY_1105_DATA + DDRSS_PHY_1106_DATA + DDRSS_PHY_1107_DATA + DDRSS_PHY_1108_DATA + DDRSS_PHY_1109_DATA + DDRSS_PHY_1110_DATA + DDRSS_PHY_1111_DATA + DDRSS_PHY_1112_DATA + DDRSS_PHY_1113_DATA + DDRSS_PHY_1114_DATA + DDRSS_PHY_1115_DATA + DDRSS_PHY_1116_DATA + DDRSS_PHY_1117_DATA + DDRSS_PHY_1118_DATA + DDRSS_PHY_1119_DATA + DDRSS_PHY_1120_DATA + DDRSS_PHY_1121_DATA + DDRSS_PHY_1122_DATA + DDRSS_PHY_1123_DATA + DDRSS_PHY_1124_DATA + DDRSS_PHY_1125_DATA + DDRSS_PHY_1126_DATA + DDRSS_PHY_1127_DATA + DDRSS_PHY_1128_DATA + DDRSS_PHY_1129_DATA + DDRSS_PHY_1130_DATA + DDRSS_PHY_1131_DATA + DDRSS_PHY_1132_DATA + DDRSS_PHY_1133_DATA + DDRSS_PHY_1134_DATA + DDRSS_PHY_1135_DATA + DDRSS_PHY_1136_DATA + DDRSS_PHY_1137_DATA + DDRSS_PHY_1138_DATA + DDRSS_PHY_1139_DATA + DDRSS_PHY_1140_DATA + DDRSS_PHY_1141_DATA + DDRSS_PHY_1142_DATA + DDRSS_PHY_1143_DATA + DDRSS_PHY_1144_DATA + DDRSS_PHY_1145_DATA + DDRSS_PHY_1146_DATA + DDRSS_PHY_1147_DATA + DDRSS_PHY_1148_DATA + DDRSS_PHY_1149_DATA + DDRSS_PHY_1150_DATA + DDRSS_PHY_1151_DATA + DDRSS_PHY_1152_DATA + DDRSS_PHY_1153_DATA + DDRSS_PHY_1154_DATA + DDRSS_PHY_1155_DATA + DDRSS_PHY_1156_DATA + DDRSS_PHY_1157_DATA + DDRSS_PHY_1158_DATA + DDRSS_PHY_1159_DATA + DDRSS_PHY_1160_DATA + DDRSS_PHY_1161_DATA + DDRSS_PHY_1162_DATA + DDRSS_PHY_1163_DATA + DDRSS_PHY_1164_DATA + DDRSS_PHY_1165_DATA + DDRSS_PHY_1166_DATA + DDRSS_PHY_1167_DATA + DDRSS_PHY_1168_DATA + DDRSS_PHY_1169_DATA + DDRSS_PHY_1170_DATA + DDRSS_PHY_1171_DATA + DDRSS_PHY_1172_DATA + DDRSS_PHY_1173_DATA + DDRSS_PHY_1174_DATA + DDRSS_PHY_1175_DATA + DDRSS_PHY_1176_DATA + DDRSS_PHY_1177_DATA + DDRSS_PHY_1178_DATA + DDRSS_PHY_1179_DATA + DDRSS_PHY_1180_DATA + DDRSS_PHY_1181_DATA + DDRSS_PHY_1182_DATA + DDRSS_PHY_1183_DATA + DDRSS_PHY_1184_DATA + DDRSS_PHY_1185_DATA + DDRSS_PHY_1186_DATA + DDRSS_PHY_1187_DATA + DDRSS_PHY_1188_DATA + DDRSS_PHY_1189_DATA + DDRSS_PHY_1190_DATA + DDRSS_PHY_1191_DATA + DDRSS_PHY_1192_DATA + DDRSS_PHY_1193_DATA + DDRSS_PHY_1194_DATA + DDRSS_PHY_1195_DATA + DDRSS_PHY_1196_DATA + DDRSS_PHY_1197_DATA + DDRSS_PHY_1198_DATA + DDRSS_PHY_1199_DATA + DDRSS_PHY_1200_DATA + DDRSS_PHY_1201_DATA + DDRSS_PHY_1202_DATA + DDRSS_PHY_1203_DATA + DDRSS_PHY_1204_DATA + DDRSS_PHY_1205_DATA + DDRSS_PHY_1206_DATA + DDRSS_PHY_1207_DATA + DDRSS_PHY_1208_DATA + DDRSS_PHY_1209_DATA + DDRSS_PHY_1210_DATA + DDRSS_PHY_1211_DATA + DDRSS_PHY_1212_DATA + DDRSS_PHY_1213_DATA + DDRSS_PHY_1214_DATA + DDRSS_PHY_1215_DATA + DDRSS_PHY_1216_DATA + DDRSS_PHY_1217_DATA + DDRSS_PHY_1218_DATA + DDRSS_PHY_1219_DATA + DDRSS_PHY_1220_DATA + DDRSS_PHY_1221_DATA + DDRSS_PHY_1222_DATA + DDRSS_PHY_1223_DATA + DDRSS_PHY_1224_DATA + DDRSS_PHY_1225_DATA + DDRSS_PHY_1226_DATA + DDRSS_PHY_1227_DATA + DDRSS_PHY_1228_DATA + DDRSS_PHY_1229_DATA + DDRSS_PHY_1230_DATA + DDRSS_PHY_1231_DATA + DDRSS_PHY_1232_DATA + DDRSS_PHY_1233_DATA + DDRSS_PHY_1234_DATA + DDRSS_PHY_1235_DATA + DDRSS_PHY_1236_DATA + DDRSS_PHY_1237_DATA + DDRSS_PHY_1238_DATA + DDRSS_PHY_1239_DATA + DDRSS_PHY_1240_DATA + DDRSS_PHY_1241_DATA + DDRSS_PHY_1242_DATA + DDRSS_PHY_1243_DATA + DDRSS_PHY_1244_DATA + DDRSS_PHY_1245_DATA + DDRSS_PHY_1246_DATA + DDRSS_PHY_1247_DATA + DDRSS_PHY_1248_DATA + DDRSS_PHY_1249_DATA + DDRSS_PHY_1250_DATA + DDRSS_PHY_1251_DATA + DDRSS_PHY_1252_DATA + DDRSS_PHY_1253_DATA + DDRSS_PHY_1254_DATA + DDRSS_PHY_1255_DATA + DDRSS_PHY_1256_DATA + DDRSS_PHY_1257_DATA + DDRSS_PHY_1258_DATA + DDRSS_PHY_1259_DATA + DDRSS_PHY_1260_DATA + DDRSS_PHY_1261_DATA + DDRSS_PHY_1262_DATA + DDRSS_PHY_1263_DATA + DDRSS_PHY_1264_DATA + DDRSS_PHY_1265_DATA + DDRSS_PHY_1266_DATA + DDRSS_PHY_1267_DATA + DDRSS_PHY_1268_DATA + DDRSS_PHY_1269_DATA + DDRSS_PHY_1270_DATA + DDRSS_PHY_1271_DATA + DDRSS_PHY_1272_DATA + DDRSS_PHY_1273_DATA + DDRSS_PHY_1274_DATA + DDRSS_PHY_1275_DATA + DDRSS_PHY_1276_DATA + DDRSS_PHY_1277_DATA + DDRSS_PHY_1278_DATA + DDRSS_PHY_1279_DATA + DDRSS_PHY_1280_DATA + DDRSS_PHY_1281_DATA + DDRSS_PHY_1282_DATA + DDRSS_PHY_1283_DATA + DDRSS_PHY_1284_DATA + DDRSS_PHY_1285_DATA + DDRSS_PHY_1286_DATA + DDRSS_PHY_1287_DATA + DDRSS_PHY_1288_DATA + DDRSS_PHY_1289_DATA + DDRSS_PHY_1290_DATA + DDRSS_PHY_1291_DATA + DDRSS_PHY_1292_DATA + DDRSS_PHY_1293_DATA + DDRSS_PHY_1294_DATA + DDRSS_PHY_1295_DATA + DDRSS_PHY_1296_DATA + DDRSS_PHY_1297_DATA + DDRSS_PHY_1298_DATA + DDRSS_PHY_1299_DATA + DDRSS_PHY_1300_DATA + DDRSS_PHY_1301_DATA + DDRSS_PHY_1302_DATA + DDRSS_PHY_1303_DATA + DDRSS_PHY_1304_DATA + DDRSS_PHY_1305_DATA + DDRSS_PHY_1306_DATA + DDRSS_PHY_1307_DATA + DDRSS_PHY_1308_DATA + DDRSS_PHY_1309_DATA + DDRSS_PHY_1310_DATA + DDRSS_PHY_1311_DATA + DDRSS_PHY_1312_DATA + DDRSS_PHY_1313_DATA + DDRSS_PHY_1314_DATA + DDRSS_PHY_1315_DATA + DDRSS_PHY_1316_DATA + DDRSS_PHY_1317_DATA + DDRSS_PHY_1318_DATA + DDRSS_PHY_1319_DATA + DDRSS_PHY_1320_DATA + DDRSS_PHY_1321_DATA + DDRSS_PHY_1322_DATA + DDRSS_PHY_1323_DATA + DDRSS_PHY_1324_DATA + DDRSS_PHY_1325_DATA + DDRSS_PHY_1326_DATA + DDRSS_PHY_1327_DATA + DDRSS_PHY_1328_DATA + DDRSS_PHY_1329_DATA + DDRSS_PHY_1330_DATA + DDRSS_PHY_1331_DATA + DDRSS_PHY_1332_DATA + DDRSS_PHY_1333_DATA + DDRSS_PHY_1334_DATA + DDRSS_PHY_1335_DATA + DDRSS_PHY_1336_DATA + DDRSS_PHY_1337_DATA + DDRSS_PHY_1338_DATA + DDRSS_PHY_1339_DATA + DDRSS_PHY_1340_DATA + DDRSS_PHY_1341_DATA + DDRSS_PHY_1342_DATA + DDRSS_PHY_1343_DATA + DDRSS_PHY_1344_DATA + DDRSS_PHY_1345_DATA + DDRSS_PHY_1346_DATA + DDRSS_PHY_1347_DATA + DDRSS_PHY_1348_DATA + DDRSS_PHY_1349_DATA + DDRSS_PHY_1350_DATA + DDRSS_PHY_1351_DATA + DDRSS_PHY_1352_DATA + DDRSS_PHY_1353_DATA + DDRSS_PHY_1354_DATA + DDRSS_PHY_1355_DATA + DDRSS_PHY_1356_DATA + DDRSS_PHY_1357_DATA + DDRSS_PHY_1358_DATA + DDRSS_PHY_1359_DATA + DDRSS_PHY_1360_DATA + DDRSS_PHY_1361_DATA + DDRSS_PHY_1362_DATA + DDRSS_PHY_1363_DATA + DDRSS_PHY_1364_DATA + DDRSS_PHY_1365_DATA + DDRSS_PHY_1366_DATA + DDRSS_PHY_1367_DATA + DDRSS_PHY_1368_DATA + DDRSS_PHY_1369_DATA + DDRSS_PHY_1370_DATA + DDRSS_PHY_1371_DATA + DDRSS_PHY_1372_DATA + DDRSS_PHY_1373_DATA + DDRSS_PHY_1374_DATA + DDRSS_PHY_1375_DATA + DDRSS_PHY_1376_DATA + DDRSS_PHY_1377_DATA + DDRSS_PHY_1378_DATA + DDRSS_PHY_1379_DATA + DDRSS_PHY_1380_DATA + DDRSS_PHY_1381_DATA + DDRSS_PHY_1382_DATA + DDRSS_PHY_1383_DATA + DDRSS_PHY_1384_DATA + DDRSS_PHY_1385_DATA + DDRSS_PHY_1386_DATA + DDRSS_PHY_1387_DATA + DDRSS_PHY_1388_DATA + DDRSS_PHY_1389_DATA + DDRSS_PHY_1390_DATA + DDRSS_PHY_1391_DATA + DDRSS_PHY_1392_DATA + DDRSS_PHY_1393_DATA + DDRSS_PHY_1394_DATA + DDRSS_PHY_1395_DATA + DDRSS_PHY_1396_DATA + DDRSS_PHY_1397_DATA + DDRSS_PHY_1398_DATA + DDRSS_PHY_1399_DATA + DDRSS_PHY_1400_DATA + DDRSS_PHY_1401_DATA + DDRSS_PHY_1402_DATA + DDRSS_PHY_1403_DATA + DDRSS_PHY_1404_DATA + DDRSS_PHY_1405_DATA + DDRSS_PHY_1406_DATA + DDRSS_PHY_1407_DATA + DDRSS_PHY_1408_DATA + DDRSS_PHY_1409_DATA + DDRSS_PHY_1410_DATA + DDRSS_PHY_1411_DATA + DDRSS_PHY_1412_DATA + DDRSS_PHY_1413_DATA + DDRSS_PHY_1414_DATA + DDRSS_PHY_1415_DATA + DDRSS_PHY_1416_DATA + DDRSS_PHY_1417_DATA + DDRSS_PHY_1418_DATA + DDRSS_PHY_1419_DATA + DDRSS_PHY_1420_DATA + DDRSS_PHY_1421_DATA + DDRSS_PHY_1422_DATA + >; +}; diff --git a/roms/u-boot/doc/device-tree-bindings/memory-controllers/k3-am654-ddrss.txt b/roms/u-boot/doc/device-tree-bindings/memory-controllers/k3-am654-ddrss.txt new file mode 100644 index 000000000..4ed731c52 --- /dev/null +++ b/roms/u-boot/doc/device-tree-bindings/memory-controllers/k3-am654-ddrss.txt @@ -0,0 +1,46 @@ +Texas Instruments' K3 AM654 DDRSS +================================= + +K3 based AM654 devices has DDR memory subsystem that comprises +Synopys DDR controller, Synopsis DDR phy and wrapper logic to +integrate these blocks into the device. This DDR subsystem +provides an interface to external SDRAM devices. This DDRSS driver +adds support for the initialization of the external SDRAM devices by +configuring the DDRSS registers and using the buitin PHY +initialization routines. + +DDRSS device node: +================== +Required properties: +-------------------- +- compatible: Shall be: "ti,am654-ddrss" +- reg-names ss - Map the sub system wrapper logic region + ctl - Map the controller region + phy - Map the PHY region +- reg: Contains the register map per reg-names. +- power-domains: Should contain a phandle to a PM domain provider node + and an args specifier containing the DDRSS device id + value. This property is as per the binding, + doc/device-tree-bindings/power/ti,sci-pm-domain.txt +- clocks: Must contain an entry for enabling DDR clock. Should + be defined as per the appropriate clock bindings consumer + usage in doc/device-tree-bindings/clock/ti,sci-clk.txt + + +Optional Properties: +-------------------- +- clock-frequency: Frequency at which DDR pll should be locked. + If not provided, default frequency will be used. + +Example (AM65x): +================ + memory-controller: memory-controller@298e000 { + compatible = "ti,am654-ddrss"; + reg = <0x0298e000 0x200>, + <0x02980000 0x4000>, + <0x02988000 0x2000>; + reg-names = "ss", "ctl", "phy"; + clocks = <&k3_clks 20 0>; + power-domains = <&k3_pds 20>; + u-boot,dm-spl; + }; diff --git a/roms/u-boot/doc/device-tree-bindings/memory-controllers/st,stm32-fmc.txt b/roms/u-boot/doc/device-tree-bindings/memory-controllers/st,stm32-fmc.txt new file mode 100644 index 000000000..99f76d515 --- /dev/null +++ b/roms/u-boot/doc/device-tree-bindings/memory-controllers/st,stm32-fmc.txt @@ -0,0 +1,58 @@ +ST, stm32 flexible memory controller Drive +Required properties: +- compatible : "st,stm32-fmc" +- reg : fmc controller base address +- clocks : fmc controller clock +u-boot,dm-pre-reloc: flag to initialize memory before relocation. + +on-board sdram memory attributes: +- st,sdram-control : parameters for sdram configuration, in this order: + number of columns + number of rows + memory width + number of intenal banks in memory + cas latency + read burst enable or disable + read pipe delay + +- st,sdram-timing: timings for sdram, in this order: + tmrd + txsr + tras + trc + trp + trcd + +There is device tree include file at : +include/dt-bindings/memory/stm32-sdram.h to define sdram control and timing +parameters as MACROS. + +Example: + fmc: fmc@A0000000 { + compatible = "st,stm32-fmc"; + reg = <0xA0000000 0x1000>; + clocks = <&rcc 0 64>; + u-boot,dm-pre-reloc; + }; + + &fmc { + pinctrl-0 = <&fmc_pins>; + pinctrl-names = "default"; + status = "okay"; + + /* sdram memory configuration from sdram datasheet */ + bank1: bank@0 { + st,sdram-control = /bits/ 8 <NO_COL_8 NO_ROW_12 MWIDTH_16 BANKS_2 + CAS_3 RD_BURST_EN RD_PIPE_DL_0>; + st,sdram-timing = /bits/ 8 <TMRD_1 TXSR_60 TRAS_42 TRC_60 TRP_18 + TRCD_18>; + }; + + /* sdram memory configuration from sdram datasheet */ + bank2: bank@1 { + st,sdram-control = /bits/ 8 <NO_COL_8 NO_ROW_12 MWIDTH_16 BANKS_2 + CAS_3 RD_BURST_EN RD_PIPE_DL_0>; + st,sdram-timing = /bits/ 8 <TMRD_1 TXSR_60 TRAS_42 TRC_60 TRP_18 + TRCD_18>; + }; + } diff --git a/roms/u-boot/doc/device-tree-bindings/memory-controllers/st,stm32mp1-ddr.txt b/roms/u-boot/doc/device-tree-bindings/memory-controllers/st,stm32mp1-ddr.txt new file mode 100644 index 000000000..ac6a7df43 --- /dev/null +++ b/roms/u-boot/doc/device-tree-bindings/memory-controllers/st,stm32mp1-ddr.txt @@ -0,0 +1,301 @@ +ST,stm32mp1 DDR3/LPDDR2/LPDDR3 Controller (DDRCTRL and DDRPHYC) + +-------------------- +Required properties: +-------------------- +- compatible : Should be "st,stm32mp1-ddr" +- reg : controleur (DDRCTRL) and phy (DDRPHYC) base address +- clocks : controller clocks handle +- clock-names : associated controller clock names + the "ddrphyc" clock is used to check the DDR frequency + at phy level according the expected value in "mem-speed" field + +the next attributes are DDR parameters, they are generated by DDR tools +included in STM32 Cube tool + +info attributes: +---------------- +- st,mem-name : name for DDR configuration, simple string for information +- st,mem-speed : DDR expected speed for the setting in kHz +- st,mem-size : DDR mem size in byte + + +controlleur attributes: +----------------------- +- st,ctl-reg : controleur values depending of the DDR type + (DDR3/LPDDR2/LPDDR3) + for STM32MP15x: 25 values are requested in this order + MSTR + MRCTRL0 + MRCTRL1 + DERATEEN + DERATEINT + PWRCTL + PWRTMG + HWLPCTL + RFSHCTL0 + RFSHCTL3 + CRCPARCTL0 + ZQCTL0 + DFITMG0 + DFITMG1 + DFILPCFG0 + DFIUPD0 + DFIUPD1 + DFIUPD2 + DFIPHYMSTR + ODTMAP + DBG0 + DBG1 + DBGCMD + POISONCFG + PCCFG + +- st,ctl-timing : controleur values depending of frequency and timing parameter + of DDR + for STM32MP15x: 12 values are requested in this order + RFSHTMG + DRAMTMG0 + DRAMTMG1 + DRAMTMG2 + DRAMTMG3 + DRAMTMG4 + DRAMTMG5 + DRAMTMG6 + DRAMTMG7 + DRAMTMG8 + DRAMTMG14 + ODTCFG + +- st,ctl-map : controleur values depending of address mapping + for STM32MP15x: 9 values are requested in this order + ADDRMAP1 + ADDRMAP2 + ADDRMAP3 + ADDRMAP4 + ADDRMAP5 + ADDRMAP6 + ADDRMAP9 + ADDRMAP10 + ADDRMAP11 + +- st,ctl-perf : controleur values depending of performance and scheduling + for STM32MP15x: 17 values are requested in this order + SCHED + SCHED1 + PERFHPR1 + PERFLPR1 + PERFWR1 + PCFGR_0 + PCFGW_0 + PCFGQOS0_0 + PCFGQOS1_0 + PCFGWQOS0_0 + PCFGWQOS1_0 + PCFGR_1 + PCFGW_1 + PCFGQOS0_1 + PCFGQOS1_1 + PCFGWQOS0_1 + PCFGWQOS1_1 + +phyc attributes: +---------------- +- st,phy-reg : phy values depending of the DDR type (DDR3/LPDDR2/LPDDR3) + for STM32MP15x: 11 values are requested in this order + PGCR + ACIOCR + DXCCR + DSGCR + DCR + ODTCR + ZQ0CR1 + DX0GCR + DX1GCR + DX2GCR + DX3GCR + +- st,phy-timing : phy values depending of frequency and timing parameter of DDR + for STM32MP15x: 10 values are requested in this order + PTR0 + PTR1 + PTR2 + DTPR0 + DTPR1 + DTPR2 + MR0 + MR1 + MR2 + MR3 + +- st,phy-cal : phy cal depending of calibration or tuning of DDR + This parameter is optional; when it is absent the built-in PHY + calibration is done. + for STM32MP15x: 12 values are requested in this order + DX0DLLCR + DX0DQTR + DX0DQSTR + DX1DLLCR + DX1DQTR + DX1DQSTR + DX2DLLCR + DX2DQTR + DX2DQSTR + DX3DLLCR + DX3DQTR + DX3DQSTR + +Example: + +/ { + soc { + u-boot,dm-spl; + + ddr: ddr@0x5A003000{ + u-boot,dm-spl; + u-boot,dm-pre-reloc; + + compatible = "st,stm32mp1-ddr"; + + reg = <0x5A003000 0x550 + 0x5A004000 0x234>; + + clocks = <&rcc_clk AXIDCG>, + <&rcc_clk DDRC1>, + <&rcc_clk DDRC2>, + <&rcc_clk DDRPHYC>, + <&rcc_clk DDRCAPB>, + <&rcc_clk DDRPHYCAPB>; + + clock-names = "axidcg", + "ddrc1", + "ddrc2", + "ddrphyc", + "ddrcapb", + "ddrphycapb"; + + st,mem-name = "DDR3 2x4Gb 533MHz"; + st,mem-speed = <533000>; + st,mem-size = <0x40000000>; + + st,ctl-reg = < + 0x00040401 /*MSTR*/ + 0x00000010 /*MRCTRL0*/ + 0x00000000 /*MRCTRL1*/ + 0x00000000 /*DERATEEN*/ + 0x00800000 /*DERATEINT*/ + 0x00000000 /*PWRCTL*/ + 0x00400010 /*PWRTMG*/ + 0x00000000 /*HWLPCTL*/ + 0x00210000 /*RFSHCTL0*/ + 0x00000000 /*RFSHCTL3*/ + 0x00000000 /*CRCPARCTL0*/ + 0xC2000040 /*ZQCTL0*/ + 0x02050105 /*DFITMG0*/ + 0x00000202 /*DFITMG1*/ + 0x07000000 /*DFILPCFG0*/ + 0xC0400003 /*DFIUPD0*/ + 0x00000000 /*DFIUPD1*/ + 0x00000000 /*DFIUPD2*/ + 0x00000000 /*DFIPHYMSTR*/ + 0x00000001 /*ODTMAP*/ + 0x00000000 /*DBG0*/ + 0x00000000 /*DBG1*/ + 0x00000000 /*DBGCMD*/ + 0x00000000 /*POISONCFG*/ + 0x00000010 /*PCCFG*/ + >; + + st,ctl-timing = < + 0x0080008A /*RFSHTMG*/ + 0x121B2414 /*DRAMTMG0*/ + 0x000D041B /*DRAMTMG1*/ + 0x0607080E /*DRAMTMG2*/ + 0x0050400C /*DRAMTMG3*/ + 0x07040407 /*DRAMTMG4*/ + 0x06060303 /*DRAMTMG5*/ + 0x02020002 /*DRAMTMG6*/ + 0x00000202 /*DRAMTMG7*/ + 0x00001005 /*DRAMTMG8*/ + 0x000D041B /*DRAMTMG1*/4 + 0x06000600 /*ODTCFG*/ + >; + + st,ctl-map = < + 0x00080808 /*ADDRMAP1*/ + 0x00000000 /*ADDRMAP2*/ + 0x00000000 /*ADDRMAP3*/ + 0x00001F1F /*ADDRMAP4*/ + 0x07070707 /*ADDRMAP5*/ + 0x0F070707 /*ADDRMAP6*/ + 0x00000000 /*ADDRMAP9*/ + 0x00000000 /*ADDRMAP10*/ + 0x00000000 /*ADDRMAP11*/ + >; + + st,ctl-perf = < + 0x00001201 /*SCHED*/ + 0x00001201 /*SCHED*/1 + 0x01000001 /*PERFHPR1*/ + 0x08000200 /*PERFLPR1*/ + 0x08000400 /*PERFWR1*/ + 0x00010000 /*PCFGR_0*/ + 0x00000000 /*PCFGW_0*/ + 0x02100B03 /*PCFGQOS0_0*/ + 0x00800100 /*PCFGQOS1_0*/ + 0x01100B03 /*PCFGWQOS0_0*/ + 0x01000200 /*PCFGWQOS1_0*/ + 0x00010000 /*PCFGR_1*/ + 0x00000000 /*PCFGW_1*/ + 0x02100B03 /*PCFGQOS0_1*/ + 0x00800000 /*PCFGQOS1_1*/ + 0x01100B03 /*PCFGWQOS0_1*/ + 0x01000200 /*PCFGWQOS1_1*/ + >; + + st,phy-reg = < + 0x01442E02 /*PGCR*/ + 0x10400812 /*ACIOCR*/ + 0x00000C40 /*DXCCR*/ + 0xF200001F /*DSGCR*/ + 0x0000000B /*DCR*/ + 0x00010000 /*ODTCR*/ + 0x0000007B /*ZQ0CR1*/ + 0x0000CE81 /*DX0GCR*/ + 0x0000CE81 /*DX1GCR*/ + 0x0000CE81 /*DX2GCR*/ + 0x0000CE81 /*DX3GCR*/ + >; + + st,phy-timing = < + 0x0022A41B /*PTR0*/ + 0x047C0740 /*PTR1*/ + 0x042D9C80 /*PTR2*/ + 0x369477D0 /*DTPR0*/ + 0x098A00D8 /*DTPR1*/ + 0x10023600 /*DTPR2*/ + 0x00000830 /*MR0*/ + 0x00000000 /*MR1*/ + 0x00000208 /*MR2*/ + 0x00000000 /*MR3*/ + >; + + st,phy-cal = < + 0x40000000 /*DX0DLLCR*/ + 0xFFFFFFFF /*DX0DQTR*/ + 0x3DB02000 /*DX0DQSTR*/ + 0x40000000 /*DX1DLLCR*/ + 0xFFFFFFFF /*DX1DQTR*/ + 0x3DB02000 /*DX1DQSTR*/ + 0x40000000 /*DX2DLLCR*/ + 0xFFFFFFFF /*DX2DQTR*/ + 0x3DB02000 /*DX2DQSTR*/ + 0x40000000 /*DX3DLLCR*/ + 0xFFFFFFFF /*DX3DQTR*/ + 0x3DB02000 /*DX3DQSTR*/ + >; + + status = "okay"; + }; + }; +}; diff --git a/roms/u-boot/doc/device-tree-bindings/memory/memory.txt b/roms/u-boot/doc/device-tree-bindings/memory/memory.txt new file mode 100644 index 000000000..321894e01 --- /dev/null +++ b/roms/u-boot/doc/device-tree-bindings/memory/memory.txt @@ -0,0 +1,67 @@ +* Memory binding + +The memory binding for U-Boot is as in the ePAPR with the following additions: + +Optional subnodes can be used defining the memory layout for different board +ID masks. To match a set of board ids, a board-id node may define match-mask +and match-value ints to define a mask to apply to the board id, and the value +that the result should have for the match to be considered valid. The mask +defaults to -1, meaning that the value must fully match the board id. + +If subnodes are present, then the /memory node must define these properties: + +- #address-cells: should be 1. +- #size-cells: should be 0. + +Each subnode must define + + reg - board ID or mask for this subnode + memory-banks - list of memory banks in the same format as normal + +Each subnode may optionally define: + + match-mask - A mask to apply to the board id. This must be accompanied by + match-value. + match-value - The required resulting value of the board id mask for the given + node to be considered a match. + auto-size - Indicates that the value given for a bank is the maximum size, + each bank is probed to determine its actual size, which may be + smaller + + +The board id determination is up to the vendor and is not defined by this +binding. + +Example: + +memory { + #address-cells = <1>; + #size-cells = <1>; + reg = <0x20000000 0x20000000 + 0x40000000 0x20000000 + 0x60000000 0x20000000 + 0x80000000 0x20000000>; + auto-size; + board-id@0 { + match-value = <17>; + reg = <0x20000000 0x20000000 + 0x40000000 0x20000000>; + }; + board-id@1 { + match-mask = <2>; + match-value = <2>; + reg = <0x20000000 0x20000000 + 0x40000000 0x20000000 + 0x60000000 0x20000000 + 0x80000000 0x20000000 + 0xa0000000 0x20000000 + 0xc0000000 0x20000000 + 0xe0000000 0x20000000>; + }; +}; + + +This shows a system with the following properties: +* Default of 2GB of memory, auto-sized, so could be smaller +* 3.5GB of memory (with no auto-size) if (board id & 2) is 2 +* 1GB of memory (with no auto-size) if board id is 17. diff --git a/roms/u-boot/doc/device-tree-bindings/mfd/kendryte,k210-sysctl.txt b/roms/u-boot/doc/device-tree-bindings/mfd/kendryte,k210-sysctl.txt new file mode 100644 index 000000000..5b24abcb6 --- /dev/null +++ b/roms/u-boot/doc/device-tree-bindings/mfd/kendryte,k210-sysctl.txt @@ -0,0 +1,33 @@ +Kendryte K210 Sysctl + +This binding describes the K210 sysctl device, which contains many miscellaneous +registers controlling system functionality. This node is a register map and can +be reference by other bindings which need a phandle to the K210 sysctl regmap. + +Required properties: +- compatible: should be + "kendryte,k210-sysctl", "syscon", "simple-mfd" +- reg: address and length of the sysctl registers +- reg-io-width: must be <4> + +Clock sub-node + +This node is a binding for the clock tree driver + +Required properties: +- compatible: should be "kendryte,k210-clk" +- clocks: phandle to the "in0" external oscillator +- #clock-cells: must be <1> + +Example: +sysctl: syscon@50440000 { + compatible = "kendryte,k210-sysctl", "syscon", "simple-mfd"; + reg = <0x50440000 0x100>; + reg-io-width = <4>; + + sysclk: clock-controller { + compatible = "kendryte,k210-clk"; + clocks = <&in0>; + #clock-cells = <1>; + }; +}; diff --git a/roms/u-boot/doc/device-tree-bindings/misc/altera_sysid.txt b/roms/u-boot/doc/device-tree-bindings/misc/altera_sysid.txt new file mode 100644 index 000000000..54462eb5e --- /dev/null +++ b/roms/u-boot/doc/device-tree-bindings/misc/altera_sysid.txt @@ -0,0 +1,4 @@ +Altera sysid + +Required properties: +- compatible : should be "altr,sysid-1.0" diff --git a/roms/u-boot/doc/device-tree-bindings/misc/bootcounter.txt b/roms/u-boot/doc/device-tree-bindings/misc/bootcounter.txt new file mode 100644 index 000000000..d32fbc37b --- /dev/null +++ b/roms/u-boot/doc/device-tree-bindings/misc/bootcounter.txt @@ -0,0 +1,21 @@ +U-Boot bootcounter Devicetree Binding +===================================== + +The device tree node describes the U-Boot bootcounter +memory based device binding. + +Required properties : + +- compatible : "u-boot,bootcount"; +- single-word : set this, if you have only one word space + for storing the bootcounter. + +Example +------- + +MPC83xx based board: + +bootcount@0x13ff8 { + compatible = "u-boot,bootcount"; + reg = <0x13ff8 0x08>; +}; diff --git a/roms/u-boot/doc/device-tree-bindings/misc/cros-ec.txt b/roms/u-boot/doc/device-tree-bindings/misc/cros-ec.txt new file mode 100644 index 000000000..07ea7cdea --- /dev/null +++ b/roms/u-boot/doc/device-tree-bindings/misc/cros-ec.txt @@ -0,0 +1,38 @@ +Chrome OS CROS_EC Binding +====================== + +The device tree node which describes the operation of the CROS_EC interface +is as follows: + +Required properties : +- compatible = "google,cros-ec" + +Optional properties : +- spi-max-frequency : Sets the maximum frequency (in Hz) for SPI bus + operation +- i2c-max-frequency : Sets the maximum frequency (in Hz) for I2C bus + operation +- ec-interrupt : Selects the EC interrupt, defined as a GPIO according + to the platform +- optimise-flash-write : Boolean property - if present then flash blocks + containing all 0xff will not be written, since we assume that the EC + uses that pattern for erased blocks + +The CROS_EC node should appear as a subnode of the interrupt that connects it +to the EC (e.g. i2c, spi, lpc). The reg property (as usual) will indicate +the unit address on that bus. + + +Example +======= + + spi@131b0000 { + cros-ec@0 { + reg = <0>; + compatible = "google,cros-ec"; + spi-max-frequency = <5000000>; + ec-interrupt = <&gpio 174 1>; + optimise-flash-write; + status = "disabled"; + }; + }; diff --git a/roms/u-boot/doc/device-tree-bindings/misc/esm-k3.txt b/roms/u-boot/doc/device-tree-bindings/misc/esm-k3.txt new file mode 100644 index 000000000..01c8b6b29 --- /dev/null +++ b/roms/u-boot/doc/device-tree-bindings/misc/esm-k3.txt @@ -0,0 +1,25 @@ +Texas Instruments K3 ESM Binding +====================== + +ESM (Error Signaling Module) is an IP block on TI K3 devices that allows +handling of safety events somewhat similar to what interrupt controller +would do. The safety signals have their separate paths within the SoC, +and they are handled by the ESM, which routes them to the proper +destination, which can be system reset, interrupt controller, etc. In +the simplest configuration the signals are just routed to reset the +SoC. + +Required properties : +- compatible : "ti,j721e-esm" +- ti,esm-pins : integer array of esm events IDs to route to external event + pin which can be used to reset the SoC. The array can + have arbitrary amount of event IDs listed on it. + +Example +======= + + main_esm: esm@700000 { + compatible = "ti,j721e-esm"; + reg = <0x0 0x700000 0x0 0x1000>; + ti,esm-pins = <344>, <345>; + }; diff --git a/roms/u-boot/doc/device-tree-bindings/misc/esm-pmic.txt b/roms/u-boot/doc/device-tree-bindings/misc/esm-pmic.txt new file mode 100644 index 000000000..a60ad7467 --- /dev/null +++ b/roms/u-boot/doc/device-tree-bindings/misc/esm-pmic.txt @@ -0,0 +1,19 @@ +PMIC ESM Binding +====================== + +Certain Power Management ICs contain safety handling logic within them, +allowing automatic reset of the board in case a safety error is signaled. +For this purpose, ESM (Error Signal Monitor) is implemented within +the PMIC running its own state machine. + +Required properties : +- compatible : "ti,tps659413-esm" + +Example +======= + +&tps659413a { + esm: esm { + compatible = "ti,tps659413-esm"; + }; +}; diff --git a/roms/u-boot/doc/device-tree-bindings/misc/fs_loader.txt b/roms/u-boot/doc/device-tree-bindings/misc/fs_loader.txt new file mode 100644 index 000000000..884fbf47c --- /dev/null +++ b/roms/u-boot/doc/device-tree-bindings/misc/fs_loader.txt @@ -0,0 +1,48 @@ +* File system firmware loader + +Required properties: +-------------------- + +- compatible: should contain "u-boot,fs-loader" +- phandlepart: which block storage device and partition the image loading from, + this property is required for mmc, usb and sata. This is unsigned + 32-bit array. For example phandlepart=<&mmc_0 1>, meaning use + that MMC0 node pointer, partition 1. +- mdtpart: which partition of ubi the image loading from, this property is + required for ubi and mounting. +- ubivol: which volume of ubi the image loading from, this property is required + for ubi and mounting. + +Example of storage device and partition search set for mmc, usb, sata and +ubi in device tree source as shown in below: + + Example of storage type and device partition search set for mmc, usb, + sata and ubi as shown in below: + Example for mmc: + fs_loader0: fs-loader@0 { + u-boot,dm-pre-reloc; + compatible = "u-boot,fs-loader"; + phandlepart = <&mmc_0 1>; + }; + + Example for usb: + fs_loader1: fs-loader@1 { + u-boot,dm-pre-reloc; + compatible = "u-boot,fs-loader"; + phandlepart = <&usb0 1>; + }; + + Example for sata: + fs_loader2: fs-loader@2 { + u-boot,dm-pre-reloc; + compatible = "u-boot,fs-loader"; + phandlepart = <&sata0 1>; + }; + + Example for ubi: + fs_loader3: fs-loader@3 { + u-boot,dm-pre-reloc; + compatible = "u-boot,fs-loader"; + mtdpart = "UBI", + ubivol = "ubi0"; + }; diff --git a/roms/u-boot/doc/device-tree-bindings/misc/intel,baytrail-fsp.txt b/roms/u-boot/doc/device-tree-bindings/misc/intel,baytrail-fsp.txt new file mode 100644 index 000000000..929ae88c5 --- /dev/null +++ b/roms/u-boot/doc/device-tree-bindings/misc/intel,baytrail-fsp.txt @@ -0,0 +1,155 @@ +Intel Bay Trail FSP UPD Binding +=============================== + +The device tree node which describes the overriding of the Intel Bay Trail FSP +UPD data for configuring the SoC. + +All properties can be found within the `upd-region` struct in +arch/x86/include/asm/arch-baytrail/fsp/fsp_vpd.h, under the same names, and in +Intel's FSP Binary Configuration Tool for Bay Trail. This list of properties +is matched up to Intel's E3800 FSPv4 release. + +# Boolean properties: + +- fsp,enable-sdio +- fsp,enable-sdcard +- fsp,enable-hsuart0 +- fsp,enable-hsuart1 +- fsp,enable-spi +- fsp,enable-sata +- fsp,enable-azalia +- fsp,enable-xhci +- fsp,enable-dma0 +- fsp,enable-dma1 +- fsp,enable-i2-c0 +- fsp,enable-i2-c1 +- fsp,enable-i2-c2 +- fsp,enable-i2-c3 +- fsp,enable-i2-c4 +- fsp,enable-i2-c5 +- fsp,enable-i2-c6 +- fsp,enable-pwm0 +- fsp,enable-pwm1 +- fsp,enable-hsi +- fsp,mrc-debug-msg +- fsp,isp-enable +- fsp,igd-render-standby +- fsp,txe-uma-enable +- fsp,emmc45-ddr50-enabled +- fsp,emmc45-hs200-enabled +- fsp,enable-igd +- fsp,enable-memory-down + +If you set "fsp,enable-memory-down" you are strongly encouraged to provide an +"fsp,memory-down-params{};" to specify how your memory is configured. If you +do not set "fsp,enable-memory-down", then the DIMM SPD information will be +discovered by the FSP and used to setup main memory. + + +# Integer properties: + +- fsp,mrc-init-tseg-size +- fsp,mrc-init-mmio-size +- fsp,mrc-init-spd-addr1 +- fsp,mrc-init-spd-addr2 +- fsp,emmc-boot-mode +- fsp,sata-mode +- fsp,lpe-mode +- fsp,lpss-sio-mode +- fsp,igd-dvmt50-pre-alloc +- fsp,aperture-size +- fsp,gtt-size +- fsp,scc-mode +- fsp,os-selection +- fsp,emmc45-retune-timer-value + +- fsp,memory-down-params { + + # Boolean properties: + + - fsp,dimm-0-enable + - fsp,dimm-1-enable + + # Integer properties: + + - fsp,dram-speed + - fsp,dram-type + - fsp,dimm-width + - fsp,dimm-density + - fsp,dimm-bus-width + - fsp,dimm-sides + - fsp,dimm-tcl + - fsp,dimm-trpt-rcd + - fsp,dimm-twr + - fsp,dimm-twtr + - fsp,dimm-trrd + - fsp,dimm-trtp + - fsp,dimm-tfaw +}; + +For all integer properties, available options are listed in fsp_configs.h in +arch/x86/include/asm/arch-baytrail/fsp directory (eg: MRC_INIT_TSEG_SIZE_1MB). + + +Example (from MinnowMax Dual Core): +----------------------------------- + +/ { + ... + + fsp { + compatible = "intel,baytrail-fsp"; + fsp,mrc-init-tseg-size = <MRC_INIT_TSEG_SIZE_1MB>; + fsp,mrc-init-mmio-size = <MRC_INIT_MMIO_SIZE_2048MB>; + fsp,mrc-init-spd-addr1 = <0xa0>; + fsp,mrc-init-spd-addr2 = <0xa2>; + fsp,emmc-boot-mode = <EMMC_BOOT_MODE_AUTO>; + fsp,enable-sdio; + fsp,enable-sdcard; + fsp,enable-hsuart1; + fsp,enable-spi; + fsp,enable-sata; + fsp,sata-mode = <SATA_MODE_AHCI>; + fsp,lpe-mode = <LPE_MODE_PCI>; + fsp,lpss-sio-mode = <LPSS_SIO_MODE_PCI>; + fsp,enable-dma0; + fsp,enable-dma1; + fsp,enable-i2c0; + fsp,enable-i2c1; + fsp,enable-i2c2; + fsp,enable-i2c3; + fsp,enable-i2c4; + fsp,enable-i2c5; + fsp,enable-i2c6; + fsp,enable-pwm0; + fsp,enable-pwm1; + fsp,igd-dvmt50-pre-alloc = <IGD_DVMT50_PRE_ALLOC_64MB>; + fsp,aperture-size = <APERTURE_SIZE_256MB>; + fsp,gtt-size = <GTT_SIZE_2MB>; + fsp,scc-mode = <SCC_MODE_PCI>; + fsp,os-selection = <OS_SELECTION_LINUX>; + fsp,emmc45-ddr50-enabled; + fsp,emmc45-retune-timer-value = <8>; + fsp,enable-igd; + fsp,enable-memory-down; + fsp,memory-down-params { + compatible = "intel,baytrail-fsp-mdp"; + fsp,dram-speed = <DRAM_SPEED_1066MTS>; + fsp,dram-type = <DRAM_TYPE_DDR3L>; + fsp,dimm-0-enable; + fsp,dimm-width = <DIMM_WIDTH_X16>; + fsp,dimm-density = <DIMM_DENSITY_4GBIT>; + fsp,dimm-bus-width = <DIMM_BUS_WIDTH_64BITS>; + fsp,dimm-sides = <DIMM_SIDES_1RANKS>; + fsp,dimm-tcl = <0xb>; + fsp,dimm-trpt-rcd = <0xb>; + fsp,dimm-twr = <0xc>; + fsp,dimm-twtr = <6>; + fsp,dimm-trrd = <6>; + fsp,dimm-trtp = <6>; + fsp,dimm-tfaw = <0x14>; + }; + }; + + ... +}; diff --git a/roms/u-boot/doc/device-tree-bindings/misc/intel,irq-router.txt b/roms/u-boot/doc/device-tree-bindings/misc/intel,irq-router.txt new file mode 100644 index 000000000..09e97b430 --- /dev/null +++ b/roms/u-boot/doc/device-tree-bindings/misc/intel,irq-router.txt @@ -0,0 +1,61 @@ +Intel Interrupt Router Device Binding +===================================== + +The device tree node which describes the operation of the Intel Interrupt Router +device is as follows: + +Required properties : +- reg : Specifies the interrupt router's PCI configuration space address as + defined by the Open Firmware spec. +- compatible = "intel,irq-router" +- intel,pirq-config : Specifies the IRQ routing register programming mechanism. + Valid values are: + "pci": IRQ routing is controlled by PCI configuration registers + "ibase": IRQ routing is in the memory-mapped IBASE register block +- intel,ibase-offset : IBASE register offset in the interrupt router's PCI + configuration space, required only if intel,pirq-config = "ibase". +- intel,actl-8bit : If ACTL (ACPI control) register width is 8-bit, this must + be specified. The 8-bit ACTL register is seen on ICH series chipset, like + ICH9/Panther Point/etc. On Atom chipset it is a 32-bit register. +- intel,actl-addr : ACTL (ACPI control) register offset. ACTL can be either + in the interrupt router's PCI configuration space, or IBASE. +- intel,pirq-link : Specifies the PIRQ link information with two cells. The + first cell is the register offset that controls the first PIRQ link routing. + The second cell is the total number of PIRQ links the router supports. +- intel,pirq-regmap : Specifies PIRQ routing register offset of all PIRQ links, + encoded as 2 cells a group for each link. The first cell is the PIRQ link + number (0 for PIRQA, 1 for PIRQB, etc). The second cell is the PIRQ routing + register offset from the interrupt router's base address. If this property + is omitted, it indicates a consecutive register offset from the first PIRQ + link, as specified by the first cell of intel,pirq-link. +- intel,pirq-mask : Specifies the IRQ mask representing the 16 IRQs in the + 8259 PIC. Bit N is 1 means IRQ N is available to be routed. +- intel,pirq-routing : Specifies all PCI devices' IRQ routing information, + encoded as 3 cells a group for a device. The first cell is the device's PCI + bus number, device number and function number encoding with PCI_BDF() macro. + The second cell is the PCI interrupt pin used by this device. The last cell + is which PIRQ line the PCI interrupt pin is routed to. + + +Example +------- + +#include <dt-bindings/interrupt-router/intel-irq.h> + + irq-router@1f,0 { + reg = <0x0000f800 0 0 0 0>; + compatible = "intel,irq-router"; + intel,pirq-config = "pci"; + intel,pirq-link = <0x60 8>; + intel,pirq-mask = <0xdef8>; + intel,pirq-routing = < + PCI_BDF(0, 2, 0) INTA PIRQA + PCI_BDF(0, 3, 0) INTA PIRQB + PCI_BDF(0, 8, 0) INTA PIRQC + PCI_BDF(0, 8, 1) INTB PIRQD + PCI_BDF(1, 6, 0) INTA PIRQE + PCI_BDF(1, 6, 1) INTB PIRQF + PCI_BDF(1, 6, 2) INTC PIRQG + PCI_BDF(1, 6, 3) INTD PIRQH + >; + }; diff --git a/roms/u-boot/doc/device-tree-bindings/misc/intel-lpc.txt b/roms/u-boot/doc/device-tree-bindings/misc/intel-lpc.txt new file mode 100644 index 000000000..ba6ca9dbc --- /dev/null +++ b/roms/u-boot/doc/device-tree-bindings/misc/intel-lpc.txt @@ -0,0 +1,64 @@ +Intel LPC Device Binding +======================== + +The device tree node which describes the operation of the Intel Low Pin +Count device is as follows: + +Required properties : +- compatible = "intel,lpc" +- intel,alt-gp-smi-enable : Enable SMI sources. This cell is written to the + ALT_GP_SMI_EN register +- intel,gen-dec : Specifies the values for the gen-dec registers. Up to four + cell pairs can be provided - the first of each pair is the base address and + the second is the size. These are written into the GENx_DEC registers of + the LPC device +- intel,gpi-routing : Specifies the GPI routing. There are 16 cells, valid + values are: + 0 No effect (default) + 1 SMI# (if corresponding ALT_GPI_SMI_EN bit is also set) + 2 SCI (if corresponding GPIO_EN bit is also set) +- intel,pirq-routing : Speciffies the routing IRQ number for each of PIRQA-H, + one cell for each. + 0x00 - 0000 = Reserved + 0x01 - 0001 = Reserved + 0x02 - 0010 = Reserved + 0x03 - 0011 = IRQ3 + 0x04 - 0100 = IRQ4 + 0x05 - 0101 = IRQ5 + 0x06 - 0110 = IRQ6 + 0x07 - 0111 = IRQ7 + 0x08 - 1000 = Reserved + 0x09 - 1001 = IRQ9 + 0x0A - 1010 = IRQ10 + 0x0B - 1011 = IRQ11 + 0x0C - 1100 = IRQ12 + 0x0D - 1101 = Reserved + 0x0E - 1110 = IRQ14 + 0x0F - 1111 = IRQ15 + PIRQ[n]_ROUT[7] - PIRQ Routing Control + 0x80 - The PIRQ is not routed. + + +Example +------- + +lpc { + compatible = "intel,lpc"; + #address-cells = <1>; + #size-cells = <1>; + intel,gen-dec = <0x800 0xfc 0x900 0xfc>; + + intel,pirq-routing = <0x8b 0x8a 0x8b 0x8b + 0x80 0x80 0x80 0x80>; + /* + * GPI routing + * 0 No effect (default) + * 1 SMI# (if corresponding ALT_GPI_SMI_EN bit is + * also set) + * 2 SCI (if corresponding GPIO_EN bit is also set) + */ + intel,gpi-routing = <0 0 0 0 0 0 0 2 + 1 0 0 0 0 0 0 0>; + /* Enable EC SMI source */ + intel,alt-gp-smi-enable = <0x0100>; +}; diff --git a/roms/u-boot/doc/device-tree-bindings/misc/misc/fsl,mpc83xx-serdes.txt b/roms/u-boot/doc/device-tree-bindings/misc/misc/fsl,mpc83xx-serdes.txt new file mode 100644 index 000000000..64a9b5b15 --- /dev/null +++ b/roms/u-boot/doc/device-tree-bindings/misc/misc/fsl,mpc83xx-serdes.txt @@ -0,0 +1,24 @@ +MPC83xx SerDes controller devices + +MPC83xx SoCs contain a built-in SerDes controller that determines which +protocols (SATA, PCI Express, SGMII, ...) are used on the system's serdes lines +and how the lines are configured. + +Required properties: +- compatible: must be "fsl,mpc83xx-serdes" +- reg: must point to the serdes controller's register map +- proto: selects for which protocol the serdes lines are configured. One of + "sata", "pex", "pex-x2", "sgmii" +- serdes-clk: determines the frequency the serdes lines are configured for. One + of 100, 125, 150. +- vdd: determines whether 1.0V core VDD is used or not + +Example: + +SERDES: serdes@e3000 { + reg = <0xe3000 0x200>; + compatible = "fsl,mpc83xx-serdes"; + proto = "pex"; + serdes-clk = <100>; + vdd; +}; diff --git a/roms/u-boot/doc/device-tree-bindings/misc/misc/gdsys,io-endpoint.txt b/roms/u-boot/doc/device-tree-bindings/misc/misc/gdsys,io-endpoint.txt new file mode 100644 index 000000000..db2ff8ca1 --- /dev/null +++ b/roms/u-boot/doc/device-tree-bindings/misc/misc/gdsys,io-endpoint.txt @@ -0,0 +1,20 @@ +gdsys IO endpoint of IHS FPGA devices + +The IO endpoint of IHS FPGA devices is a packet-based transmission interface +that allows interconnected gdsys devices to send and receive data over the +FPGA's main ethernet connection. + +Required properties: +- compatible: must be "gdsys,io-endpoint" +- reg: describes the address and length of the endpoint's register map (within + the FPGA's register space) + +Example: + +fpga0_ep0 { + compatible = "gdsys,io-endpoint"; + reg = <0x020 0x10 + 0x320 0x10 + 0x340 0x10 + 0x360 0x10>; +}; diff --git a/roms/u-boot/doc/device-tree-bindings/misc/misc/gdsys,iocon_fpga.txt b/roms/u-boot/doc/device-tree-bindings/misc/misc/gdsys,iocon_fpga.txt new file mode 100644 index 000000000..acd466fdc --- /dev/null +++ b/roms/u-boot/doc/device-tree-bindings/misc/misc/gdsys,iocon_fpga.txt @@ -0,0 +1,19 @@ +gdsys IHS FPGA for CON devices + +The gdsys IHS FPGA is the main FPGA on gdsys CON devices. This driver provides +support for enabling and starting the FPGA, as well as verifying working bus +communication. + +Required properties: +- compatible: must be "gdsys,iocon_fpga" +- reset-gpios: List of GPIOs controlling the FPGA's reset +- done-gpios: List of GPIOs notifying whether the FPGA's reconfiguration is + done + +Example: + +FPGA0 { + compatible = "gdsys,iocon_fpga"; + reset-gpios = <&PPCPCA 26 0>; + done-gpios = <&GPIO_VB0 19 0>; +}; diff --git a/roms/u-boot/doc/device-tree-bindings/misc/misc/gdsys,iocpu_fpga.txt b/roms/u-boot/doc/device-tree-bindings/misc/misc/gdsys,iocpu_fpga.txt new file mode 100644 index 000000000..819db22bf --- /dev/null +++ b/roms/u-boot/doc/device-tree-bindings/misc/misc/gdsys,iocpu_fpga.txt @@ -0,0 +1,19 @@ +gdsys IHS FPGA for CPU devices + +The gdsys IHS FPGA is the main FPGA on gdsys CPU devices. This driver provides +support for enabling and starting the FPGA, as well as verifying working bus +communication. + +Required properties: +- compatible: must be "gdsys,iocpu_fpga" +- reset-gpios: List of GPIOs controlling the FPGA's reset +- done-gpios: List of GPIOs notifying whether the FPGA's reconfiguration is + done + +Example: + +FPGA0 { + compatible = "gdsys,iocpu_fpga"; + reset-gpios = <&PPCPCA 26 0>; + done-gpios = <&GPIO_VB0 19 0>; +}; diff --git a/roms/u-boot/doc/device-tree-bindings/misc/misc/gdsys,soc.txt b/roms/u-boot/doc/device-tree-bindings/misc/misc/gdsys,soc.txt new file mode 100644 index 000000000..278e935b1 --- /dev/null +++ b/roms/u-boot/doc/device-tree-bindings/misc/misc/gdsys,soc.txt @@ -0,0 +1,16 @@ +gdsys soc bus driver + +This driver provides a simple interface for the busses associated with gdsys +IHS FPGAs. The bus itself contains devices whose register maps are contained +within the FPGA's register space. + +Required properties: +- fpga: A phandle to the controlling IHS FPGA + +Example: + +FPGA0BUS: fpga0bus { + compatible = "gdsys,soc"; + ranges = <0x0 0xe0600000 0x00004000>; + fpga = <&FPGA0>; +}; diff --git a/roms/u-boot/doc/device-tree-bindings/mmc/msm_sdhci.txt b/roms/u-boot/doc/device-tree-bindings/mmc/msm_sdhci.txt new file mode 100644 index 000000000..08a290c66 --- /dev/null +++ b/roms/u-boot/doc/device-tree-bindings/mmc/msm_sdhci.txt @@ -0,0 +1,25 @@ +Qualcomm Snapdragon SDHCI controller + +Required properties: +- compatible : "qcom,sdhci-msm-v4" +- reg: Base address and length of registers: + - Host controller registers (SDHCI) + - SD Core registers +- clock: interface clock (must accept SD bus clock as a frequency) + +Optional properties: +- index: If there is more than one controller - controller index (required + by generic SDHCI code). +- bus_width: Width of SD/eMMC bus (default 4) +- clock-frequency: Frequency of SD/eMMC bus (default 400 kHz) + +Example: + +sdhci@07864000 { + compatible = "qcom,sdhci-msm-v4"; + reg = <0x7864900 0x11c 0x7864000 0x800>; + index = <0x1>; + bus-width = <0x4>; + clock = <&clkc 1>; + clock-frequency = <200000000>; +}; diff --git a/roms/u-boot/doc/device-tree-bindings/mmc/snps,dw-mmc.txt b/roms/u-boot/doc/device-tree-bindings/mmc/snps,dw-mmc.txt new file mode 100644 index 000000000..69faefa95 --- /dev/null +++ b/roms/u-boot/doc/device-tree-bindings/mmc/snps,dw-mmc.txt @@ -0,0 +1,33 @@ +Synopsys Designware Mobile Storage Host Controller extensions +used in Synopsys ARC devboards + +Required Properties: + +* compatible: should be - "snps,dw-mshc". +* bus-width: number of data lines connected to the controller. +* clocks: from common clock binding: handle to biu and ciu clocks for the + bus interface unit clock and the card interface unit clock. +* clock-names: from common clock binding: Shall be "biu" and "ciu". + +Optional properties: + +* fifo-depth: The maximum size of the tx/rx fifo's. If this property is not + specified, the default value of the fifo size is determined from the + controller registers. +* fifo-mode: Don't use DMA. +* max-frequency: Maximum operating clock frequency, driver uses 'ciu' clock + frequency if it is not set. + +Example: + +mmc0@f000a000 { + compatible = "snps,dw-mshc"; + reg = <0xf000a000 0x400>; + + bus-width = <4>; + fifo-depth = <256>; + clocks = <&mmcclk_biu>, <&mmcclk_ciu>; + clock-names = "biu", "ciu"; + max-frequency = <25000000>; +}; + diff --git a/roms/u-boot/doc/device-tree-bindings/mtd/altera_qspi.txt b/roms/u-boot/doc/device-tree-bindings/mtd/altera_qspi.txt new file mode 100644 index 000000000..3361ac92a --- /dev/null +++ b/roms/u-boot/doc/device-tree-bindings/mtd/altera_qspi.txt @@ -0,0 +1,35 @@ +Altera QUADSPI driver + +Required properties: +- compatible: Should be "altr,quadspi-1.0" +- reg: Address and length of the register set for the device. It contains + the information of registers in the same order as described by reg-names +- reg-names: Should contain the reg names + "avl_csr": Should contain the register configuration base address + "avl_mem": Should contain the data base address +- #address-cells: Must be <1>. +- #size-cells: Must be <0>. +- flash device tree subnode, there must be a node with the following fields: + - compatible: Should contain the flash name: + 1. EPCS: epcs16, epcs64, epcs128 + 2. EPCQ: epcq16, epcq32, epcq64, epcq128, epcq256, epcq512, epcq1024 + 3. EPCQ-L: epcql256, epcql512, epcql1024 + - #address-cells: please refer to /mtd/partition.txt + - #size-cells: please refer to /mtd/partition.txt + For partitions inside each flash, please refer to /mtd/partition.txt + +Example: + + quadspi_controller_0: quadspi@0x180014a0 { + compatible = "altr,quadspi-1.0"; + reg = <0x180014a0 0x00000020>, + <0x14000000 0x04000000>; + reg-names = "avl_csr", "avl_mem"; + #address-cells = <1>; + #size-cells = <0>; + flash0: epcq512@0 { + compatible = "altr,epcq512"; + #address-cells = <1>; + #size-cells = <1>; + }; + }; diff --git a/roms/u-boot/doc/device-tree-bindings/mtd/mtd-physmap.txt b/roms/u-boot/doc/device-tree-bindings/mtd/mtd-physmap.txt new file mode 100644 index 000000000..4b8c48943 --- /dev/null +++ b/roms/u-boot/doc/device-tree-bindings/mtd/mtd-physmap.txt @@ -0,0 +1,88 @@ +CFI or JEDEC memory-mapped NOR flash, MTD-RAM (NVRAM...) + +Flash chips (Memory Technology Devices) are often used for solid state +file systems on embedded devices. + + - compatible : should contain the specific model of mtd chip(s) + used, if known, followed by either "cfi-flash", "jedec-flash", + "mtd-ram" or "mtd-rom". + - reg : Address range(s) of the mtd chip(s) + It's possible to (optionally) define multiple "reg" tuples so that + non-identical chips can be described in one node. + - bank-width : Width (in bytes) of the bank. Equal to the + device width times the number of interleaved chips. + - device-width : (optional) Width of a single mtd chip. If + omitted, assumed to be equal to 'bank-width'. + - #address-cells, #size-cells : Must be present if the device has + sub-nodes representing partitions (see below). In this case + both #address-cells and #size-cells must be equal to 1. + - no-unaligned-direct-access: boolean to disable the default direct + mapping of the flash. + On some platforms (e.g. MPC5200) a direct 1:1 mapping may cause + problems with JFFS2 usage, as the local bus (LPB) doesn't support + unaligned accesses as implemented in the JFFS2 code via memcpy(). + By defining "no-unaligned-direct-access", the flash will not be + exposed directly to the MTD users (e.g. JFFS2) any more. + - linux,mtd-name: allow to specify the mtd name for retro capability with + physmap-flash drivers as boot loader pass the mtd partition via the old + device name physmap-flash. + - use-advanced-sector-protection: boolean to enable support for the + advanced sector protection (Spansion: PPB - Persistent Protection + Bits) locking. + +For JEDEC compatible devices, the following additional properties +are defined: + + - vendor-id : Contains the flash chip's vendor id (1 byte). + - device-id : Contains the flash chip's device id (1 byte). + +For ROM compatible devices (and ROM fallback from cfi-flash), the following +additional (optional) property is defined: + + - erase-size : The chip's physical erase block size in bytes. + +The device tree may optionally contain sub-nodes describing partitions of the +address space. See partition.txt for more detail. + +Example: + + flash@ff000000 { + compatible = "amd,am29lv128ml", "cfi-flash"; + reg = <ff000000 01000000>; + bank-width = <4>; + device-width = <1>; + #address-cells = <1>; + #size-cells = <1>; + fs@0 { + label = "fs"; + reg = <0 f80000>; + }; + firmware@f80000 { + label ="firmware"; + reg = <f80000 80000>; + read-only; + }; + }; + +Here an example with multiple "reg" tuples: + + flash@f0000000,0 { + #address-cells = <1>; + #size-cells = <1>; + compatible = "intel,pc48f4400p0vb", "cfi-flash"; + reg = <0 0x00000000 0x02000000 + 0 0x02000000 0x02000000>; + bank-width = <2>; + partition@0 { + label = "test-part1"; + reg = <0 0x04000000>; + }; + }; + +An example using SRAM: + + sram@2,0 { + compatible = "samsung,k6f1616u6a", "mtd-ram"; + reg = <2 0 0x00200000>; + bank-width = <2>; + }; diff --git a/roms/u-boot/doc/device-tree-bindings/mtd/spi-nand.txt b/roms/u-boot/doc/device-tree-bindings/mtd/spi-nand.txt new file mode 100644 index 000000000..8b51f3b6d --- /dev/null +++ b/roms/u-boot/doc/device-tree-bindings/mtd/spi-nand.txt @@ -0,0 +1,5 @@ +SPI NAND flash + +Required properties: +- compatible: should be "spi-nand" +- reg: should encode the chip-select line used to access the NAND chip diff --git a/roms/u-boot/doc/device-tree-bindings/mtd/spi/spi-flash.txt b/roms/u-boot/doc/device-tree-bindings/mtd/spi/spi-flash.txt new file mode 100644 index 000000000..332789026 --- /dev/null +++ b/roms/u-boot/doc/device-tree-bindings/mtd/spi/spi-flash.txt @@ -0,0 +1,25 @@ +* MTD SPI driver for serial flash chips + +Required properties: +- #address-cells, #size-cells : Must be present if the device has sub-nodes + representing partitions. +- compatible : Should be the manufacturer and the name of the chip. Bear in + mind that the DT binding is not U-Boot-only, but in case of + U-Boot, see spi_flash_params_table table in + drivers/mtd/spi/spi_flash_ids.c for the list of supported chips. +- reg : Chip-Select number +- spi-max-frequency : Maximum frequency of the SPI bus the chip can operate at + +Optional properties: + - memory-map : Address and size of the flash, if memory mapped. This may + apply to Intel chipsets, which tend to memory-map flash. + +Example: + + flash: m25p80@0 { + #address-cells = <1>; + #size-cells = <1>; + compatible = "spansion,m25p80"; + reg = <0>; + spi-max-frequency = <40000000>; + }; diff --git a/roms/u-boot/doc/device-tree-bindings/mtd/stm32-fmc2-nand.txt b/roms/u-boot/doc/device-tree-bindings/mtd/stm32-fmc2-nand.txt new file mode 100644 index 000000000..ad2bef826 --- /dev/null +++ b/roms/u-boot/doc/device-tree-bindings/mtd/stm32-fmc2-nand.txt @@ -0,0 +1,61 @@ +STMicroelectronics Flexible Memory Controller 2 (FMC2) +NAND Interface + +Required properties: +- compatible: Should be one of: + * st,stm32mp15-fmc2 +- reg: NAND flash controller memory areas. + First region contains the register location. + Regions 2 to 4 respectively contain the data, command, + and address space for CS0. + Regions 5 to 7 contain the same areas for CS1. +- interrupts: The interrupt number +- pinctrl-0: Standard Pinctrl phandle (see: pinctrl/pinctrl-bindings.txt) +- clocks: The clock needed by the NAND flash controller + +Optional properties: +- resets: Reference to a reset controller asserting the FMC controller +- dmas: DMA specifiers (see: dma/stm32-mdma.txt) +- dma-names: Must be "tx", "rx" and "ecc" + +* NAND device bindings: + +Required properties: +- reg: describes the CS lines assigned to the NAND device. + +Optional properties: +- nand-on-flash-bbt: see nand.txt +- nand-ecc-strength: see nand.txt +- nand-ecc-step-size: see nand.txt + +The following ECC strength and step size are currently supported: + - nand-ecc-strength = <1>, nand-ecc-step-size = <512> (Hamming) + - nand-ecc-strength = <4>, nand-ecc-step-size = <512> (BCH4) + - nand-ecc-strength = <8>, nand-ecc-step-size = <512> (BCH8) (default) + +Example: + + fmc: nand-controller@58002000 { + compatible = "st,stm32mp15-fmc2"; + reg = <0x58002000 0x1000>, + <0x80000000 0x1000>, + <0x88010000 0x1000>, + <0x88020000 0x1000>, + <0x81000000 0x1000>, + <0x89010000 0x1000>, + <0x89020000 0x1000>; + interrupts = <GIC_SPI 48 IRQ_TYPE_LEVEL_HIGH>; + clocks = <&rcc FMC_K>; + resets = <&rcc FMC_R>; + pinctrl-names = "default"; + pinctrl-0 = <&fmc_pins_a>; + #address-cells = <1>; + #size-cells = <0>; + + nand@0 { + reg = <0>; + nand-on-flash-bbt; + #address-cells = <1>; + #size-cells = <1>; + }; + }; diff --git a/roms/u-boot/doc/device-tree-bindings/nand/nvidia,tegra20-nand.txt b/roms/u-boot/doc/device-tree-bindings/nand/nvidia,tegra20-nand.txt new file mode 100644 index 000000000..86ae4082d --- /dev/null +++ b/roms/u-boot/doc/device-tree-bindings/nand/nvidia,tegra20-nand.txt @@ -0,0 +1,53 @@ +NAND Flash +---------- + +(there isn't yet a generic binding in Linux, so this describes what is in +U-Boot. There should not be Linux-specific or U-Boot specific binding, just +a binding that describes this hardware. But agreeing a binding in Linux in +the absence of a driver may be beyond my powers.) + +The device node for a NAND flash device is as follows: + +Required properties : + - compatible : Should be "manufacturer,device", "nand-flash" + +This node should sit inside its controller. + + +Nvidia NAND Controller +---------------------- + +The device node for a NAND flash controller is as follows: + +Optional properties: + +nvidia,wp-gpios : GPIO of write-protect line, three cells in the format: + phandle, parameter, flags +nvidia,nand-width : bus width of the NAND device in bits + + - nvidia,nand-timing : Timing parameters for the NAND. Each is in ns. + Order is: MAX_TRP_TREA, TWB, Max(tCS, tCH, tALS, tALH), + TWHR, Max(tCS, tCH, tALS, tALH), TWH, TWP, TRH, TADL + + MAX_TRP_TREA is: + non-EDO mode: Max(tRP, tREA) + 6ns + EDO mode: tRP timing + +The 'reg' property should provide the chip select used by the flash chip. + + +Example +------- + +nand-controller@0x70008000 { + compatible = "nvidia,tegra20-nand"; + #address-cells = <1>; + #size-cells = <0>; + nvidia,wp-gpios = <&gpio 59 0>; /* PH3 */ + nvidia,nand-width = <8>; + nvidia,timing = <26 100 20 80 20 10 12 10 70>; + nand@0 { + reg = <0>; + compatible = "hynix,hy27uf4g2b", "nand-flash"; + }; +}; diff --git a/roms/u-boot/doc/device-tree-bindings/net/allwinner,sun4i-emac.txt b/roms/u-boot/doc/device-tree-bindings/net/allwinner,sun4i-emac.txt new file mode 100644 index 000000000..10640b17c --- /dev/null +++ b/roms/u-boot/doc/device-tree-bindings/net/allwinner,sun4i-emac.txt @@ -0,0 +1,19 @@ +* Allwinner EMAC ethernet controller + +Required properties: +- compatible: should be "allwinner,sun4i-a10-emac" (Deprecated: + "allwinner,sun4i-emac") +- reg: address and length of the register set for the device. +- interrupts: interrupt for the device +- phy: see ethernet.txt file in the same directory. +- clocks: A phandle to the reference clock for this device + +Example: + +emac: ethernet@01c0b000 { + compatible = "allwinner,sun4i-a10-emac"; + reg = <0x01c0b000 0x1000>; + interrupts = <55>; + clocks = <&ahb_gates 17>; + phy = <&phy0>; +}; diff --git a/roms/u-boot/doc/device-tree-bindings/net/allwinner,sun4i-mdio.txt b/roms/u-boot/doc/device-tree-bindings/net/allwinner,sun4i-mdio.txt new file mode 100644 index 000000000..4ec564137 --- /dev/null +++ b/roms/u-boot/doc/device-tree-bindings/net/allwinner,sun4i-mdio.txt @@ -0,0 +1,27 @@ +* Allwinner A10 MDIO Ethernet Controller interface + +Required properties: +- compatible: should be "allwinner,sun4i-a10-mdio" + (Deprecated: "allwinner,sun4i-mdio"). +- reg: address and length of the register set for the device. + +Optional properties: +- phy-supply: phandle to a regulator if the PHY needs one + +Example at the SoC level: +mdio@01c0b080 { + compatible = "allwinner,sun4i-a10-mdio"; + reg = <0x01c0b080 0x14>; + #address-cells = <1>; + #size-cells = <0>; +}; + +And at the board level: + +mdio@01c0b080 { + phy-supply = <®_emac_3v3>; + + phy0: ethernet-phy@0 { + reg = <0>; + }; +}; diff --git a/roms/u-boot/doc/device-tree-bindings/net/allwinner,sun7i-a20-gmac.txt b/roms/u-boot/doc/device-tree-bindings/net/allwinner,sun7i-a20-gmac.txt new file mode 100644 index 000000000..ea4d75238 --- /dev/null +++ b/roms/u-boot/doc/device-tree-bindings/net/allwinner,sun7i-a20-gmac.txt @@ -0,0 +1,27 @@ +* Allwinner GMAC ethernet controller + +This device is a platform glue layer for stmmac. +Please see stmmac.txt for the other unchanged properties. + +Required properties: + - compatible: Should be "allwinner,sun7i-a20-gmac" + - clocks: Should contain the GMAC main clock, and tx clock + The tx clock type should be "allwinner,sun7i-a20-gmac-clk" + - clock-names: Should contain the clock names "stmmaceth", + and "allwinner_gmac_tx" + +Optional properties: +- phy-supply: phandle to a regulator if the PHY needs one + +Examples: + + gmac: ethernet@01c50000 { + compatible = "allwinner,sun7i-a20-gmac"; + reg = <0x01c50000 0x10000>, + <0x01c20164 0x4>; + interrupts = <0 85 1>; + interrupt-names = "macirq"; + clocks = <&ahb_gates 49>, <&gmac_tx>; + clock-names = "stmmaceth", "allwinner_gmac_tx"; + phy-mode = "mii"; + }; diff --git a/roms/u-boot/doc/device-tree-bindings/net/altera_tse.txt b/roms/u-boot/doc/device-tree-bindings/net/altera_tse.txt new file mode 100644 index 000000000..cb190df65 --- /dev/null +++ b/roms/u-boot/doc/device-tree-bindings/net/altera_tse.txt @@ -0,0 +1,112 @@ +* Altera Triple-Speed Ethernet MAC driver (TSE) + +Required properties: +- compatible: Should be "altr,tse-1.0" for legacy SGDMA based TSE, and should + be "altr,tse-msgdma-1.0" for the preferred MSGDMA based TSE. +- reg: Address and length of the register set for the device. It contains + the information of registers in the same order as described by reg-names +- reg-names: Should contain the reg names + "control_port": MAC configuration space region + "tx_csr": xDMA Tx dispatcher control and status space region + "tx_desc": MSGDMA Tx dispatcher descriptor space region + "rx_csr" : xDMA Rx dispatcher control and status space region + "rx_desc": MSGDMA Rx dispatcher descriptor space region + "rx_resp": MSGDMA Rx dispatcher response space region + "s1": SGDMA descriptor memory +- interrupts: Should contain the TSE interrupts and it's mode. +- interrupt-names: Should contain the interrupt names + "rx_irq": xDMA Rx dispatcher interrupt + "tx_irq": xDMA Tx dispatcher interrupt +- rx-fifo-depth: MAC receive FIFO buffer depth in bytes +- tx-fifo-depth: MAC transmit FIFO buffer depth in bytes +- phy-mode: See ethernet.txt in the same directory. +- phy-handle: See ethernet.txt in the same directory. +- phy-addr: See ethernet.txt in the same directory. A configuration should + include phy-handle or phy-addr. +- altr,has-supplementary-unicast: + If present, TSE supports additional unicast addresses. + Otherwise additional unicast addresses are not supported. +- altr,has-hash-multicast-filter: + If present, TSE supports a hash based multicast filter. + Otherwise, hash-based multicast filtering is not supported. + +- mdio device tree subnode: When the TSE has a phy connected to its local + mdio, there must be device tree subnode with the following + required properties: + + - compatible: Must be "altr,tse-mdio". + - #address-cells: Must be <1>. + - #size-cells: Must be <0>. + + For each phy on the mdio bus, there must be a node with the following + fields: + + - reg: phy id used to communicate to phy. + - device_type: Must be "ethernet-phy". + +Optional properties: +- local-mac-address: See ethernet.txt in the same directory. +- max-frame-size: See ethernet.txt in the same directory. + +Example: + + tse_sub_0_eth_tse_0: ethernet@0x1,00000000 { + compatible = "altr,tse-msgdma-1.0"; + reg = <0x00000001 0x00000000 0x00000400>, + <0x00000001 0x00000460 0x00000020>, + <0x00000001 0x00000480 0x00000020>, + <0x00000001 0x000004A0 0x00000008>, + <0x00000001 0x00000400 0x00000020>, + <0x00000001 0x00000420 0x00000020>; + reg-names = "control_port", "rx_csr", "rx_desc", "rx_resp", "tx_csr", "tx_desc"; + interrupt-parent = <&hps_0_arm_gic_0>; + interrupts = <0 41 4>, <0 40 4>; + interrupt-names = "rx_irq", "tx_irq"; + rx-fifo-depth = <2048>; + tx-fifo-depth = <2048>; + address-bits = <48>; + max-frame-size = <1500>; + local-mac-address = [ 00 00 00 00 00 00 ]; + phy-mode = "gmii"; + altr,has-supplementary-unicast; + altr,has-hash-multicast-filter; + phy-handle = <&phy0>; + mdio { + compatible = "altr,tse-mdio"; + #address-cells = <1>; + #size-cells = <0>; + phy0: ethernet-phy@0 { + reg = <0x0>; + device_type = "ethernet-phy"; + }; + + phy1: ethernet-phy@1 { + reg = <0x1>; + device_type = "ethernet-phy"; + }; + + }; + }; + + tse_sub_1_eth_tse_0: ethernet@0x1,00001000 { + compatible = "altr,tse-msgdma-1.0"; + reg = <0x00000001 0x00001000 0x00000400>, + <0x00000001 0x00001460 0x00000020>, + <0x00000001 0x00001480 0x00000020>, + <0x00000001 0x000014A0 0x00000008>, + <0x00000001 0x00001400 0x00000020>, + <0x00000001 0x00001420 0x00000020>; + reg-names = "control_port", "rx_csr", "rx_desc", "rx_resp", "tx_csr", "tx_desc"; + interrupt-parent = <&hps_0_arm_gic_0>; + interrupts = <0 43 4>, <0 42 4>; + interrupt-names = "rx_irq", "tx_irq"; + rx-fifo-depth = <2048>; + tx-fifo-depth = <2048>; + address-bits = <48>; + max-frame-size = <1500>; + local-mac-address = [ 00 00 00 00 00 00 ]; + phy-mode = "gmii"; + altr,has-supplementary-unicast; + altr,has-hash-multicast-filter; + phy-handle = <&phy1>; + }; diff --git a/roms/u-boot/doc/device-tree-bindings/net/aquantia-phy.txt b/roms/u-boot/doc/device-tree-bindings/net/aquantia-phy.txt new file mode 100644 index 000000000..89ce61e05 --- /dev/null +++ b/roms/u-boot/doc/device-tree-bindings/net/aquantia-phy.txt @@ -0,0 +1,25 @@ +PHY nodes for Aquantia devices. + +This text describes properties that are applicable to Aquantia PHY nodes in +addition to the bindings in phy.txt. + +Aquantia PHYs allow some flexibility in the way they are wired in a system, +they allow MDI pins to be reversed, LEDs linked up in different weays, have an +I2C slave interface that can be used for debug. Normally the configuration +corresponding to these is driven by the PHY firmware with the downside that +a custom firmware is needed for each integration of a PHY. +Several optional bindings are defined that allow these configuration points to +be driven by the PHY driver and reduce dependency on specific FW versions. + +Optional properties: +mdi-reversal: 0 or 1 indicating that reversal must be disabled/enabled. + Firmware default is used if the property is missing. +smb-addr: I2C/SMBus address to use, firmware default is used if the property + is missing. + +Example node: +phy@00 { + reg = <0x00>; + mdi-reversal = <1>; + smb-addr = <0x25>; +}; diff --git a/roms/u-boot/doc/device-tree-bindings/net/ethernet.txt b/roms/u-boot/doc/device-tree-bindings/net/ethernet.txt new file mode 100644 index 000000000..cfc376bc9 --- /dev/null +++ b/roms/u-boot/doc/device-tree-bindings/net/ethernet.txt @@ -0,0 +1,66 @@ +The following properties are common to the Ethernet controllers: + +NOTE: All 'phy*' properties documented below are Ethernet specific. For the +generic PHY 'phys' property, see +Documentation/devicetree/bindings/phy/phy-bindings.txt. + +- local-mac-address: array of 6 bytes, specifies the MAC address that was + assigned to the network device; +- mac-address: array of 6 bytes, specifies the MAC address that was last used by + the boot program; should be used in cases where the MAC address assigned to + the device by the boot program is different from the "local-mac-address" + property; +- nvmem-cells: phandle, reference to an nvmem node for the MAC address; +- nvmem-cell-names: string, should be "mac-address" if nvmem is to be used; +- max-speed: number, specifies maximum speed in Mbit/s supported by the device; +- max-frame-size: number, maximum transfer unit (IEEE defined MTU), rather than + the maximum frame size (there's contradiction in the Devicetree + Specification). +- phy-mode: string, operation mode of the PHY interface. This is now a de-facto + standard property; supported values are: + * "internal" + * "mii" + * "gmii" + * "sgmii" + * "qsgmii" + * "tbi" + * "rev-mii" + * "rmii" + * "rgmii" (RX and TX delays are added by the MAC when required) + * "rgmii-id" (RGMII with internal RX and TX delays provided by the PHY, the + MAC should not add the RX or TX delays in this case) + * "rgmii-rxid" (RGMII with internal RX delay provided by the PHY, the MAC + should not add an RX delay in this case) + * "rgmii-txid" (RGMII with internal TX delay provided by the PHY, the MAC + should not add an TX delay in this case) + * "rtbi" + * "smii" + * "xgmii" + * "trgmii" + * "2000base-x", + * "2500base-x", + * "rxaui" + * "xaui" + * "10gbase-kr" (10GBASE-KR, XFI, SFI) +- phy-connection-type: the same as "phy-mode" property but described in the + Devicetree Specification; +- phy-handle: phandle, specifies a reference to a node representing a PHY + device; this property is described in the Devicetree Specification and so + preferred; +- phy: the same as "phy-handle" property, not recommended for new bindings. +- phy-device: the same as "phy-handle" property, not recommended for new + bindings. +- rx-fifo-depth: the size of the controller's receive fifo in bytes. This + is used for components that can have configurable receive fifo sizes, + and is useful for determining certain configuration settings such as + flow control thresholds. +- tx-fifo-depth: the size of the controller's transmit fifo in bytes. This + is used for components that can have configurable fifo sizes. +- managed: string, specifies the PHY management type. Supported values are: + "auto", "in-band-status". "auto" is the default, it usess MDIO for + management if fixed-link is not specified. + +Child nodes of the Ethernet controller are typically the individual PHY devices +connected via the MDIO bus (sometimes the MDIO bus controller is separate). +They are described in the phy.txt file in this same directory. +For non-MDIO PHY management see fixed-link.txt. diff --git a/roms/u-boot/doc/device-tree-bindings/net/fixed-link.txt b/roms/u-boot/doc/device-tree-bindings/net/fixed-link.txt new file mode 100644 index 000000000..5efeeb6fc --- /dev/null +++ b/roms/u-boot/doc/device-tree-bindings/net/fixed-link.txt @@ -0,0 +1,54 @@ +Fixed link Device Tree binding +------------------------------ + +Some Ethernet MACs have a "fixed link", and are not connected to a +normal MDIO-managed PHY device. For those situations, a Device Tree +binding allows to describe a "fixed link". + +Note there are two ways to describe a fixed PHY attached to an +Ethernet device: + +- The new DT binding, where 'fixed-link' is a sub-node of the Ethernet + MAC device node, with the following properties: + + * 'speed' (integer, mandatory), to indicate the link speed. Accepted + values are 10, 100 and 1000 + * 'full-duplex' (boolean, optional), to indicate that full duplex is + used. When absent, half duplex is assumed. + * 'pause' (boolean, optional), to indicate that pause should be + enabled. + * 'asym-pause' (boolean, optional), to indicate that asym_pause should + be enabled. + +- The old DT binding, where 'fixed-link' is a property with 5 cells + encoding various information about the fixed PHY, in the form of + <phy_id, full-duplex, speed, pause, asym-pause>. + + * 'phy_id', emulated PHY ID, choose any but unique to the all specified + fixed-links. Note U-Boot deliberately ignores the 'phy_id' and + unconditionally uses PHY_FIXED_ID. + * 'full-duplex', 0 for half duplex or 1 for full duplex + * 'speed', link speed in Mbits/sec, accepts only 10, 100 and 1000 + * 'pause', 0 for no pause, 1 for pause + * 'asym-pause', 0 for no asymmetric pause, 1 for asymmetric pause + +Examples: + +The new binding: + +ethernet@0 { + ... + fixed-link { + speed = <1000>; + full-duplex; + }; + ... +}; + +The old binding: + +ethernet@0 { + ... + fixed-link = <0 1 1000 0 0>; + ... +}; diff --git a/roms/u-boot/doc/device-tree-bindings/net/fsl,mcf-dma-fec.txt b/roms/u-boot/doc/device-tree-bindings/net/fsl,mcf-dma-fec.txt new file mode 100644 index 000000000..e237825ba --- /dev/null +++ b/roms/u-boot/doc/device-tree-bindings/net/fsl,mcf-dma-fec.txt @@ -0,0 +1,35 @@ +* Freescale ColdFire DMA-FEC ethernet controller + +Required properties: +- compatible: should be "fsl,mcf-dma-fec" +- reg: address and length of the register set for the device. +- rx-task: dma channel +- tx-task: dma channel +- rx-priority: dma channel +- tx-priority: dma channel +- rx-init: dma channel +- tx-init: dma channel + +Optional properties: +- mii-base: index of FEC reg area, 0 for FEC0, 1 for FEC1 +- max-speed: max speedm Mbits/sec +- phy-addr: phy address +- timeout-loop: integer value for driver loops time out + + +Example: + +fec0: ethernet@9000 { + compatible = "fsl,mcf-dma-fec"; + reg = <0x9000 0x800>; + mii-base = <0>; + phy-addr = <0>; + timeout-loop = <5000>; + rx-task = <0>; + tx-task = <1>; + rx-piority = <6>; + tx-piority = <7>; + rx-init = <16>; + tx-init = <17>; + status = "disabled"; +}; diff --git a/roms/u-boot/doc/device-tree-bindings/net/fsl,mcf-fec.txt b/roms/u-boot/doc/device-tree-bindings/net/fsl,mcf-fec.txt new file mode 100644 index 000000000..39bbaa52f --- /dev/null +++ b/roms/u-boot/doc/device-tree-bindings/net/fsl,mcf-fec.txt @@ -0,0 +1,22 @@ +* Freescale ColdFire FEC ethernet controller + +Required properties: +- compatible: should be "fsl,mcf-fec" +- reg: address and length of the register set for the device. + +Optional properties: +- mii-base: index of FEC reg area, 0 for FEC0, 1 for FEC1 +- max-speed: max speedm Mbits/sec +- phy-addr: phy address +- timeout-loop: integer value for driver loops time out + + +Example: + +fec0: ethernet@fc030000 { + compatible = "fsl,mcf-fec"; + reg = <0xfc030000 0x400>; + mii-base = <0>; + phy-addr = <0>; + timeout-loop = <5000>; +}; diff --git a/roms/u-boot/doc/device-tree-bindings/net/fsl-tsec-phy.txt b/roms/u-boot/doc/device-tree-bindings/net/fsl-tsec-phy.txt new file mode 100644 index 000000000..f68980352 --- /dev/null +++ b/roms/u-boot/doc/device-tree-bindings/net/fsl-tsec-phy.txt @@ -0,0 +1,81 @@ +* TSEC-compatible ethernet nodes + +Properties: + + - compatible : Should be "fsl,etsec2" or "gianfar" + - reg : Offset and length of the register set for the device. If this is + missing, a subnode with a name prefix "queue-group" must be provided to + provide the <reg> property. + - phy-handle : See ethernet.txt file in the same directory. + - phy-connection-type : See ethernet.txt file in the same directory. This + property is only really needed if the connection is of type "rgmii-id", + "rgmii-rxid" and "rgmii-txid" as all other connection types are detected + by hardware. + - ranges : an <empty> value if subnode "queue-group" is present, specifying + that no address translation is required between them TSEC parent node and + the child "queue-group" node. + +Example: + ethernet@24000 { + compatible = "fsl,etsec2"; + reg = <0x24000 0x1000>; + phy-handle = <&phy0>; + phy-connection-type = "sgmii"; + }; + +An alternate description with "queue-group" subnode example: + ethernet@24000 { + compatible = "fsl,etsec2"; + phy-handle = <&phy0>; + phy-connection-type = "sgmii"; + ranges; + + queue-group { + reg = <0x24000 0x1000>; + }; + }; + +Child nodes of the TSEC controller are typically the individual PHY devices +connected via the MDIO bus (sometimes the MDIO bus controller is separate). + +* MDIO IO device + +The MDIO is a bus to which the PHY devices are connected. For each +device that exists on this bus, a PHY node should be created. + +Required properties: + - compatible : Should define the compatible device type for the + mdio. Currently supported string/device is "fsl,etsec2-mdio". + - reg : Offset and length of the register set for the device + +Example: + + mdio@24520 { + compatible = "fsl,etsec2-mdio"; + reg = <0x24520 0x20>; + + ethernet-phy@0 { + reg = <0>; + }; + }; + +* TBI Internal MDIO bus + +As of this writing, every tsec is associated with an internal TBI PHY. +This PHY is accessed through the local MDIO bus. These buses are defined +similarly to the mdio buses. The TBI PHYs underneath them are similar to +normal PHYs, but the reg property is considered instructive, rather than +descriptive. The reg property should be chosen so it doesn't interfere +with other PHYs on the bus. The TBI PHYs are referred to by a "tbi-handle" +property under the tsec node, which has a similar meaning of "phy-handle". + +Example: + ethernet@24000 { + phy-handle = <&tbi1>; + }; + + mdio@24520 { + tbi1: tbi-phy@1f { + reg = <0x1f>; + }; + }; diff --git a/roms/u-boot/doc/device-tree-bindings/net/marvell-mdio.txt b/roms/u-boot/doc/device-tree-bindings/net/marvell-mdio.txt new file mode 100644 index 000000000..e2038e214 --- /dev/null +++ b/roms/u-boot/doc/device-tree-bindings/net/marvell-mdio.txt @@ -0,0 +1,15 @@ +* Marvell MDIO Ethernet Controller interface + +The Ethernet controllers of the Marvel Armada 3700 and Armada 7k/8k +have an identical unit that provides an interface with the MDIO bus. +This driver handles this MDIO interface. + +Mandatory properties: +SoC specific: + - #address-cells: Must be <1>. + - #size-cells: Must be <0>. + - compatible: Should be "marvell,orion-mdio" (for SMI) + "marvell,xmdio" (for XSMI) + - reg: Base address and size SMI/XMSI bus. + +Please refer to "mdio.txt" for generic MDIO bus bindings. diff --git a/roms/u-boot/doc/device-tree-bindings/net/mdio-mux-reg.txt b/roms/u-boot/doc/device-tree-bindings/net/mdio-mux-reg.txt new file mode 100644 index 000000000..0ac34dc42 --- /dev/null +++ b/roms/u-boot/doc/device-tree-bindings/net/mdio-mux-reg.txt @@ -0,0 +1,82 @@ +Device tree structures used by register based MDIO muxes is described here. +This binding is based on reg-mux.txt binding in Linux and is currently used by +mdio-mux-i2creg driver in U-Boot. + +Required properties: +#mux-control-cells = <1> indicates how many registers are used for mux + selection. mux-reg-mask property described below must + include this number of pairs. +mux-reg-masks = <reg mask> describes pairs of register offset and register mask. + Register bits enabled in mask are set to the selection + value defined in reg property of child MDIOs to control + selection. +Properties described in mdio-mux.txt also apply. + +Example structure, used on Freescale LS1028A QDS board: + +&i2c0 { + status = "okay"; + u-boot,dm-pre-reloc; + + fpga@66 { + #address-cells = <1>; + #size-cells = <0>; + compatible = "simple-mfd"; + reg = <0x66>; + + mux-mdio@54 { + #address-cells = <1>; + #size-cells = <0>; + compatible = "mdio-mux-i2creg"; + reg = <0x54>; + #mux-control-cells = <1>; + mux-reg-masks = <0x54 0xf0>; + mdio-parent-bus = <&mdio0>; + + /* on-board MDIO with a single RGMII PHY */ + mdio@00 { + #address-cells = <1>; + #size-cells = <0>; + reg = <0x00>; + + /* on-board 1G RGMII PHY */ + qds_phy0: phy@5 { + reg = <5>; + }; + }; + /* card slot 1 */ + mdio@40 { + #address-cells = <1>; + #size-cells = <0>; + reg = <0x40>; + /* VSC8234 1G SGMII card */ + sgmii_port0: phy@1c { + reg = <0x1c>; + }; + }; + /* card slot 2 */ + mdio@50 { + #address-cells = <1>; + #size-cells = <0>; + reg = <0x50>; + }; + /* card slot 3 */ + mdio@60 { + #address-cells = <1>; + #size-cells = <0>; + reg = <0x60>; + }; + /* card slot 4 */ + mdio@70 { + #address-cells = <1>; + #size-cells = <0>; + reg = <0x70>; + }; + }; + }; +}; + +/* Parent MDIO, defined in SoC .dtsi file, just enabled here */ +&mdio0 { + status = "okay"; +}; diff --git a/roms/u-boot/doc/device-tree-bindings/net/mdio-mux.txt b/roms/u-boot/doc/device-tree-bindings/net/mdio-mux.txt new file mode 100644 index 000000000..eaa31efda --- /dev/null +++ b/roms/u-boot/doc/device-tree-bindings/net/mdio-mux.txt @@ -0,0 +1,138 @@ +The expected structure of an MDIO MUX device tree node is described here. This +is heavily based on current Linux specification. +One notable difference to Linux is that mdio-parent-bus is currently required +by U-Boot, not optional as is in Linux. Current U-Boot MDIO MUX udevice class +implementation does not have specific support for MDIOs with an integrated MUX, +the property should be made optional if such support is added. + +The MDIO buses downstream of the MUX should be described in the device tree as +child nodes as indicated below. + +Required properties: +mdio-parent-bus = a phandle to the MDIO bus used to perform actual I/O. This is + typically a real MDIO device, unless there are cascaded MUXes. +#address-cells = <1>, each MDIO group is identified by one 32b value. +#size-cells = <0> + +Other properties: +The properties described here are sufficient for MDIO MUX DM class code, but +MUX drivers may define additional properties, either required or optional. + +Required properties in child nodes: +reg = value to be configured on the MUX to select the respective downstream + MDIO. + +Child nodes should normally contain PHY nodes, referenced by phandle from +ethernet nodes of the eth interfaces using these PHYs. + +Example structure, extracted from Linux bindings document: + + /* The parent MDIO bus. */ + smi1: mdio@1180000001900 { + compatible = "cavium,octeon-3860-mdio"; + #address-cells = <1>; + #size-cells = <0>; + reg = <0x11800 0x00001900 0x0 0x40>; + }; + /* + * An NXP sn74cbtlv3253 dual 1-of-4 switch controlled by a + * pair of GPIO lines. Child busses 2 and 3 populated with 4 + * PHYs each. + */ + mdio-mux { + compatible = "mdio-mux-gpio"; + gpios = <&gpio1 3 0>, <&gpio1 4 0>; + mdio-parent-bus = <&smi1>; + #address-cells = <1>; + #size-cells = <0>; + mdio@2 { + reg = <2>; + #address-cells = <1>; + #size-cells = <0>; + phy11: ethernet-phy@1 { + reg = <1>; + compatible = "marvell,88e1149r"; + marvell,reg-init = <3 0x10 0 0x5777>, + <3 0x11 0 0x00aa>, + <3 0x12 0 0x4105>, + <3 0x13 0 0x0a60>; + interrupt-parent = <&gpio>; + interrupts = <10 8>; /* Pin 10, active low */ + }; + phy12: ethernet-phy@2 { + reg = <2>; + compatible = "marvell,88e1149r"; + marvell,reg-init = <3 0x10 0 0x5777>, + <3 0x11 0 0x00aa>, + <3 0x12 0 0x4105>, + <3 0x13 0 0x0a60>; + interrupt-parent = <&gpio>; + interrupts = <10 8>; /* Pin 10, active low */ + }; + phy13: ethernet-phy@3 { + reg = <3>; + compatible = "marvell,88e1149r"; + marvell,reg-init = <3 0x10 0 0x5777>, + <3 0x11 0 0x00aa>, + <3 0x12 0 0x4105>, + <3 0x13 0 0x0a60>; + interrupt-parent = <&gpio>; + interrupts = <10 8>; /* Pin 10, active low */ + }; + phy14: ethernet-phy@4 { + reg = <4>; + compatible = "marvell,88e1149r"; + marvell,reg-init = <3 0x10 0 0x5777>, + <3 0x11 0 0x00aa>, + <3 0x12 0 0x4105>, + <3 0x13 0 0x0a60>; + interrupt-parent = <&gpio>; + interrupts = <10 8>; /* Pin 10, active low */ + }; + }; + mdio@3 { + reg = <3>; + #address-cells = <1>; + #size-cells = <0>; + phy21: ethernet-phy@1 { + reg = <1>; + compatible = "marvell,88e1149r"; + marvell,reg-init = <3 0x10 0 0x5777>, + <3 0x11 0 0x00aa>, + <3 0x12 0 0x4105>, + <3 0x13 0 0x0a60>; + interrupt-parent = <&gpio>; + interrupts = <12 8>; /* Pin 12, active low */ + }; + phy22: ethernet-phy@2 { + reg = <2>; + compatible = "marvell,88e1149r"; + marvell,reg-init = <3 0x10 0 0x5777>, + <3 0x11 0 0x00aa>, + <3 0x12 0 0x4105>, + <3 0x13 0 0x0a60>; + interrupt-parent = <&gpio>; + interrupts = <12 8>; /* Pin 12, active low */ + }; + phy23: ethernet-phy@3 { + reg = <3>; + compatible = "marvell,88e1149r"; + marvell,reg-init = <3 0x10 0 0x5777>, + <3 0x11 0 0x00aa>, + <3 0x12 0 0x4105>, + <3 0x13 0 0x0a60>; + interrupt-parent = <&gpio>; + interrupts = <12 8>; /* Pin 12, active low */ + }; + phy24: ethernet-phy@4 { + reg = <4>; + compatible = "marvell,88e1149r"; + marvell,reg-init = <3 0x10 0 0x5777>, + <3 0x11 0 0x00aa>, + <3 0x12 0 0x4105>, + <3 0x13 0 0x0a60>; + interrupt-parent = <&gpio>; + interrupts = <12 8>; /* Pin 12, active low */ + }; + }; + }; diff --git a/roms/u-boot/doc/device-tree-bindings/net/mdio.txt b/roms/u-boot/doc/device-tree-bindings/net/mdio.txt new file mode 100644 index 000000000..159532505 --- /dev/null +++ b/roms/u-boot/doc/device-tree-bindings/net/mdio.txt @@ -0,0 +1,36 @@ +Common MDIO bus properties. + +These are generic properties that can apply to any MDIO bus. + +Optional properties: + - device-name - If present it is used to name the device and MDIO bus. + The name must be unique and must not contain spaces. + +A list of child nodes, one per device on the bus is expected. These could be +PHYs, switches or similar devices and child nodes should follow the specific +binding for the device type. + +Example : +This example shows the structure used for the external MDIO bus on NXP LS1028A +RDB board. Note that this MDIO device is an integrated PCI function and +requires no compatible property for probing. + +/* definition in SoC dtsi file */ + pcie@1f0000000 { + + mdio0: pci@0,3 { + #address-cells=<0>; + #size-cells=<1>; + reg = <0x000300 0 0 0 0>; + status = "disabled"; + device-name = "emdio"; + }; + }; +/* definition of PHYs in RDB dts file */ +&mdio0 { + status = "okay"; + rdb_phy0: phy@2 { + reg = <2>; + }; +}; + diff --git a/roms/u-boot/doc/device-tree-bindings/net/mediatek,mt7628-eth.txt b/roms/u-boot/doc/device-tree-bindings/net/mediatek,mt7628-eth.txt new file mode 100644 index 000000000..ec97504a3 --- /dev/null +++ b/roms/u-boot/doc/device-tree-bindings/net/mediatek,mt7628-eth.txt @@ -0,0 +1,17 @@ +* MediaTek Frame Engine Ethernet controller + +Required properties: +- compatible: should be "mediatek,mt7628-eth" +- reg: address and length of the register set for the frame + engine ethernet controller and the internal switch. +- syscon: phandle to the system controller + +Example: + +eth@10100000 { + compatible = "mediatek,mt7628-eth"; + reg = <0x10100000 0x10000 + 0x10110000 0x8000>; + + syscon = <&sysc>; +}; diff --git a/roms/u-boot/doc/device-tree-bindings/net/micrel-ksz90x1.txt b/roms/u-boot/doc/device-tree-bindings/net/micrel-ksz90x1.txt new file mode 100644 index 000000000..a214d35fc --- /dev/null +++ b/roms/u-boot/doc/device-tree-bindings/net/micrel-ksz90x1.txt @@ -0,0 +1,192 @@ +Micrel KSZ9021/KSZ9031 Gigabit Ethernet PHY + +Some boards require special tuning values, particularly when it comes to +clock delays. You can specify clock delay values by adding +micrel-specific properties to an Ethernet OF device node. + +Note that these settings are applied after any phy-specific fixup from +phy_fixup_list (see phy_init_hw() from drivers/net/phy/phy_device.c), +and therefore may overwrite them. + +KSZ9021: + + All skew control options are specified in picoseconds. The minimum + value is 0, the maximum value is 1800, and it is incremented by 120ps + steps. + + The KSZ9021 hardware supports a range of skew values from negative to + positive, where the specific range is property dependent. All values + specified in the devicetree are offset by the minimum value so they + can be represented as positive integers in the devicetree since it's + difficult to represent a negative number in the devictree. + + The following 4-bit values table applies to all the skew properties: + + Pad Skew Value Delay (ps) Devicetree Value + ------------------------------------------------------ + 0000 -840ps 0 + 0001 -720ps 120 + 0010 -600ps 240 + 0011 -480ps 360 + 0100 -360ps 480 + 0101 -240ps 600 + 0110 -120ps 720 + 0111 0ps 840 + 1000 120ps 960 + 1001 240ps 1080 + 1010 360ps 1200 + 1011 480ps 1320 + 1100 600ps 1440 + 1101 720ps 1560 + 1110 840ps 1680 + 1111 960ps 1800 + + Optional properties: + + - rxc-skew-ps : Skew control of RXC pad + - rxdv-skew-ps : Skew control of RX CTL pad + - txc-skew-ps : Skew control of TXC pad + - txen-skew-ps : Skew control of TX CTL pad + - rxd0-skew-ps : Skew control of RX data 0 pad + - rxd1-skew-ps : Skew control of RX data 1 pad + - rxd2-skew-ps : Skew control of RX data 2 pad + - rxd3-skew-ps : Skew control of RX data 3 pad + - txd0-skew-ps : Skew control of TX data 0 pad + - txd1-skew-ps : Skew control of TX data 1 pad + - txd2-skew-ps : Skew control of TX data 2 pad + - txd3-skew-ps : Skew control of TX data 3 pad + +KSZ9031: + + All skew control options are specified in picoseconds. The minimum + value is 0, and the maximum is property-dependent. The increment + step is 60ps. + + The KSZ9031 hardware supports a range of skew values from negative to + positive, where the specific range is property dependent. All values + specified in the devicetree are offset by the minimum value so they + can be represented as positive integers in the devicetree since it's + difficult to represent a negative number in the devictree. + + The following 5-bit values table apply to rxc-skew-ps and txc-skew-ps. + + Pad Skew Value Delay (ps) Devicetree Value + ------------------------------------------------------ + 0_0000 -900ps 0 + 0_0001 -840ps 60 + 0_0010 -780ps 120 + 0_0011 -720ps 180 + 0_0100 -660ps 240 + 0_0101 -600ps 300 + 0_0110 -540ps 360 + 0_0111 -480ps 420 + 0_1000 -420ps 480 + 0_1001 -360ps 540 + 0_1010 -300ps 600 + 0_1011 -240ps 660 + 0_1100 -180ps 720 + 0_1101 -120ps 780 + 0_1110 -60ps 840 + 0_1111 0ps 900 + 1_0000 60ps 960 + 1_0001 120ps 1020 + 1_0010 180ps 1080 + 1_0011 240ps 1140 + 1_0100 300ps 1200 + 1_0101 360ps 1260 + 1_0110 420ps 1320 + 1_0111 480ps 1380 + 1_1000 540ps 1440 + 1_1001 600ps 1500 + 1_1010 660ps 1560 + 1_1011 720ps 1620 + 1_1100 780ps 1680 + 1_1101 840ps 1740 + 1_1110 900ps 1800 + 1_1111 960ps 1860 + + The following 4-bit values table apply to the txdX-skew-ps, rxdX-skew-ps + data pads, and the rxdv-skew-ps, txen-skew-ps control pads. + + Pad Skew Value Delay (ps) Devicetree Value + ------------------------------------------------------ + 0000 -420ps 0 + 0001 -360ps 60 + 0010 -300ps 120 + 0011 -240ps 180 + 0100 -180ps 240 + 0101 -120ps 300 + 0110 -60ps 360 + 0111 0ps 420 + 1000 60ps 480 + 1001 120ps 540 + 1010 180ps 600 + 1011 240ps 660 + 1100 300ps 720 + 1101 360ps 780 + 1110 420ps 840 + 1111 480ps 900 + + Optional properties: + + Maximum value of 1860: + + - rxc-skew-ps : Skew control of RX clock pad + - txc-skew-ps : Skew control of TX clock pad + + Maximum value of 900: + + - rxdv-skew-ps : Skew control of RX CTL pad + - txen-skew-ps : Skew control of TX CTL pad + - rxd0-skew-ps : Skew control of RX data 0 pad + - rxd1-skew-ps : Skew control of RX data 1 pad + - rxd2-skew-ps : Skew control of RX data 2 pad + - rxd3-skew-ps : Skew control of RX data 3 pad + - txd0-skew-ps : Skew control of TX data 0 pad + - txd1-skew-ps : Skew control of TX data 1 pad + - txd2-skew-ps : Skew control of TX data 2 pad + - txd3-skew-ps : Skew control of TX data 3 pad + +Examples: + + /* Attach to an Ethernet device with autodetected PHY */ + &enet { + rxc-skew-ps = <1800>; + rxdv-skew-ps = <0>; + txc-skew-ps = <1800>; + txen-skew-ps = <0>; + status = "okay"; + }; + + /* Attach to an explicitly-specified PHY */ + mdio { + phy0: ethernet-phy@0 { + rxc-skew-ps = <1800>; + rxdv-skew-ps = <0>; + txc-skew-ps = <1800>; + txen-skew-ps = <0>; + reg = <0>; + }; + }; + ethernet@70000 { + status = "okay"; + phy = <&phy0>; + phy-mode = "rgmii-id"; + }; + +References + + Micrel ksz9021rl/rn Data Sheet, Revision 1.2. Dated 2/13/2014. + http://www.micrel.com/_PDF/Ethernet/datasheets/ksz9021rl-rn_ds.pdf + + Micrel ksz9031rnx Data Sheet, Revision 2.1. Dated 11/20/2014. + http://www.micrel.com/_PDF/Ethernet/datasheets/KSZ9031RNX.pdf + +Notes: + + Note that a previous version of the Micrel ksz9021rl/rn Data Sheet + was missing extended register 106 (transmit data pad skews), and + incorrectly specified the ps per step as 200ps/step instead of + 120ps/step. The latest update to this document reflects the latest + revision of the Micrel specification even though usage in the kernel + still reflects that incorrect document. diff --git a/roms/u-boot/doc/device-tree-bindings/net/phy.txt b/roms/u-boot/doc/device-tree-bindings/net/phy.txt new file mode 100644 index 000000000..6599c667b --- /dev/null +++ b/roms/u-boot/doc/device-tree-bindings/net/phy.txt @@ -0,0 +1,24 @@ +PHY nodes + +If the device tree is used to describe networking interfaces, U-Boot expects a +node for each PHY. Parent node for such a PHY node is expected to correspond to +a MDIO bus and the bus is used to access the PHY. + +Required properties: + + - reg : The ID number for the phy, usually a small integer + +Example: + +ethernet-phy@0 { + compatible = "ethernet-phy-id0141.0e90", "ethernet-phy-ieee802.3-c22"; + interrupt-parent = <&PIC>; + interrupts = <35 IRQ_TYPE_EDGE_RISING>; + reg = <0>; + + resets = <&rst 8>; + reset-names = "phy"; + reset-gpios = <&gpio1 4 GPIO_ACTIVE_LOW>; + reset-assert-us = <1000>; + reset-deassert-us = <2000>; +}; diff --git a/roms/u-boot/doc/device-tree-bindings/net/phy/atheros.txt b/roms/u-boot/doc/device-tree-bindings/net/phy/atheros.txt new file mode 100644 index 000000000..a72c6b050 --- /dev/null +++ b/roms/u-boot/doc/device-tree-bindings/net/phy/atheros.txt @@ -0,0 +1,35 @@ +* Qualcomm Atheros PHY Device Tree binding + +Required properties: +- reg: PHY address + +Optional properties: +- qca,clk-out-frequency: Clock frequency of the CLK_25M pin in Hz. + Either 25000000, 50000000, 62500000 or 125000000. +- qca,clk-out-strength: Clock output buffer driver strength. + Supported values are defined in dt-bindings/net/qca-ar803x.h +- qca,keep-pll-enabled: Keep the PLL running if no link is present. + Don't go into hibernation mode. + Only supported on the AR8031/AR8033. +- vddio-supply: RGMII I/O voltage regulator + Only supported on the AR8031/AR8033. + +Optional subnodes: +- vddio-regulator: Initial data for the VDDIO regulator, as covered + doc/device-tree-bindings/regulator/regulator.txt + +Example: + #include <dt-bindings/net/qca-ar803x.h> + + ethernet-phy@0 { + reg = <0>; + qca,clk-out-frequency = <125000000>; + qca,keep-pll-enabled; + + vddio-supply = <&vddio>; + + vddio: vddio-regulator { + regulator-min-microvolt = <1800000>; + regulator-max-microvolt = <1800000>; + }; + }; diff --git a/roms/u-boot/doc/device-tree-bindings/net/snps,dwc-qos-ethernet.txt b/roms/u-boot/doc/device-tree-bindings/net/snps,dwc-qos-ethernet.txt new file mode 100644 index 000000000..d93f71ce8 --- /dev/null +++ b/roms/u-boot/doc/device-tree-bindings/net/snps,dwc-qos-ethernet.txt @@ -0,0 +1,166 @@ +* Synopsys DWC Ethernet QoS IP version 4.10 driver (GMAC) + +This binding supports the Synopsys Designware Ethernet QoS (Quality Of Service) +IP block. The IP supports multiple options for bus type, clocking and reset +structure, and feature list. Consequently, a number of properties and list +entries in properties are marked as optional, or only required in specific HW +configurations. + +Required properties: +- compatible: One of: + - "axis,artpec6-eqos", "snps,dwc-qos-ethernet-4.10" + Represents the IP core when integrated into the Axis ARTPEC-6 SoC. + - "nvidia,tegra186-eqos", "snps,dwc-qos-ethernet-4.10" + Represents the IP core when integrated into the NVIDIA Tegra186 SoC. + - "snps,dwc-qos-ethernet-4.10" + This combination is deprecated. It should be treated as equivalent to + "axis,artpec6-eqos", "snps,dwc-qos-ethernet-4.10". It is supported to be + compatible with earlier revisions of this binding. +- reg: Address and length of the register set for the device +- clocks: Phandle and clock specifiers for each entry in clock-names, in the + same order. See ../clock/clock-bindings.txt. +- clock-names: May contain any/all of the following depending on the IP + configuration, in any order: + - "tx" + The EQOS transmit path clock. The HW signal name is clk_tx_i. + In some configurations (e.g. GMII/RGMII), this clock also drives the PHY TX + path. In other configurations, other clocks (such as tx_125, rmii) may + drive the PHY TX path. + - "rx" + The EQOS receive path clock. The HW signal name is clk_rx_i. + In some configurations (e.g. GMII/RGMII), this clock is derived from the + PHY's RX clock output. In other configurations, other clocks (such as + rx_125, rmii) may drive the EQOS RX path. + In cases where the PHY clock is directly fed into the EQOS receive path + without intervening logic, the DT need not represent this clock, since it + is assumed to be fully under the control of the PHY device/driver. In + cases where SoC integration adds additional logic to this path, such as a + SW-controlled clock gate, this clock should be represented in DT. + - "slave_bus" + The CPU/slave-bus (CSR) interface clock. This applies to any bus type; + APB, AHB, AXI, etc. The HW signal name is hclk_i (AHB) or clk_csr_i (other + buses). + - "master_bus" + The master bus interface clock. Only required in configurations that use a + separate clock for the master and slave bus interfaces. The HW signal name + is hclk_i (AHB) or aclk_i (AXI). + - "ptp_ref" + The PTP reference clock. The HW signal name is clk_ptp_ref_i. + - "phy_ref_clk" + This clock is deprecated and should not be used by new compatible values. + It is equivalent to "tx". + - "apb_pclk" + This clock is deprecated and should not be used by new compatible values. + It is equivalent to "slave_bus". + + Note: Support for additional IP configurations may require adding the + following clocks to this list in the future: clk_rx_125_i, clk_tx_125_i, + clk_pmarx_0_i, clk_pmarx1_i, clk_rmii_i, clk_revmii_rx_i, clk_revmii_tx_i. + Configurations exist where multiple similar clocks are used at once, e.g. all + of clk_rx_125_i, clk_pmarx_0_i, clk_pmarx1_i. For this reason it is best to + extend the binding with a separate clock-names entry for each of those RX + clocks, rather than repurposing the existing "rx" clock-names entry as a + generic/logical clock in a similar fashion to "master_bus" and "slave_bus". + This will allow easy support for configurations that support multiple PHY + interfaces using a mux, and hence need to have explicit control over + specific RX clocks. + + The following compatible values require the following set of clocks: + - "nvidia,tegra186-eqos", "snps,dwc-qos-ethernet-4.10": + - "slave_bus" + - "master_bus" + - "rx" + - "tx" + - "ptp_ref" + - "axis,artpec6-eqos", "snps,dwc-qos-ethernet-4.10": + - "slave_bus" + - "master_bus" + - "tx" + - "ptp_ref" + - "snps,dwc-qos-ethernet-4.10" (deprecated): + - "phy_ref_clk" + - "apb_clk" +- interrupt-parent: Should be the phandle for the interrupt controller + that services interrupts for this device +- interrupts: Should contain the core's combined interrupt signal +- phy-mode: See ethernet.txt file in the same directory +- resets: Phandle and reset specifiers for each entry in reset-names, in the + same order. See ../reset/reset.txt. +- reset-names: May contain any/all of the following depending on the IP + configuration, in any order: + - "eqos". The reset to the entire module. The HW signal name is hreset_n + (AHB) or aresetn_i (AXI). + + The following compatible values require the following set of resets: + (the reset properties may be omitted if empty) + - "nvidia,tegra186-eqos", "snps,dwc-qos-ethernet-4.10": + - "eqos". + - "axis,artpec6-eqos", "snps,dwc-qos-ethernet-4.10": + - None. + - "snps,dwc-qos-ethernet-4.10" (deprecated): + - None. + +Optional properties: +- dma-coherent: Present if dma operations are coherent +- mac-address: See ethernet.txt in the same directory +- local-mac-address: See ethernet.txt in the same directory +- phy-reset-gpios: Phandle and specifier for any GPIO used to reset the PHY. + See ../gpio/gpio.txt. +- snps,en-lpi: If present it enables use of the AXI low-power interface +- snps,write-requests: Number of write requests that the AXI port can issue. + It depends on the SoC configuration. +- snps,read-requests: Number of read requests that the AXI port can issue. + It depends on the SoC configuration. +- snps,burst-map: Bitmap of allowed AXI burst lengts, with the LSB + representing 4, then 8 etc. +- snps,txpbl: DMA Programmable burst length for the TX DMA +- snps,rxpbl: DMA Programmable burst length for the RX DMA +- snps,en-tx-lpi-clockgating: Enable gating of the MAC TX clock during + TX low-power mode. +- phy-handle: See ethernet.txt file in the same directory +- mdio device tree subnode: When the GMAC has a phy connected to its local + mdio, there must be device tree subnode with the following + required properties: + - compatible: Must be "snps,dwc-qos-ethernet-mdio". + - #address-cells: Must be <1>. + - #size-cells: Must be <0>. + + For each phy on the mdio bus, there must be a node with the following + fields: + + - reg: phy id used to communicate to phy. + - device_type: Must be "ethernet-phy". + - fixed-mode device tree subnode: see fixed-link.txt in the same directory + +Examples: +ethernet2@40010000 { + clock-names = "phy_ref_clk", "apb_pclk"; + clocks = <&clkc 17>, <&clkc 15>; + compatible = "snps,dwc-qos-ethernet-4.10"; + interrupt-parent = <&intc>; + interrupts = <0x0 0x1e 0x4>; + reg = <0x40010000 0x4000>; + phy-handle = <&phy2>; + phy-mode = "gmii"; + phy-reset-gpios = <&gpioctlr 43 GPIO_ACTIVE_LOW>; + + snps,en-tx-lpi-clockgating; + snps,en-lpi; + snps,write-requests = <2>; + snps,read-requests = <16>; + snps,burst-map = <0x7>; + snps,txpbl = <8>; + snps,rxpbl = <2>; + + dma-coherent; + + mdio { + #address-cells = <0x1>; + #size-cells = <0x0>; + phy2: phy@1 { + compatible = "ethernet-phy-ieee802.3-c22"; + device_type = "ethernet-phy"; + reg = <0x1>; + }; + }; +}; diff --git a/roms/u-boot/doc/device-tree-bindings/net/stmmac.txt b/roms/u-boot/doc/device-tree-bindings/net/stmmac.txt new file mode 100644 index 000000000..5f025174c --- /dev/null +++ b/roms/u-boot/doc/device-tree-bindings/net/stmmac.txt @@ -0,0 +1,63 @@ +* STMicroelectronics 10/100/1000 Ethernet driver (GMAC) + +Required properties: +- compatible: Should be "snps,dwmac-<ip_version>" "snps,dwmac" + For backwards compatibility: "st,spear600-gmac" is also supported. +- reg: Address and length of the register set for the device +- interrupt-parent: Should be the phandle for the interrupt controller + that services interrupts for this device +- interrupts: Should contain the STMMAC interrupts +- interrupt-names: Should contain the interrupt names "macirq" + "eth_wake_irq" if this interrupt is supported in the "interrupts" + property +- phy-mode: See ethernet.txt file in the same directory. +- snps,reset-gpio gpio number for phy reset. +- snps,reset-active-low boolean flag to indicate if phy reset is active low. +- snps,reset-delays-us is triplet of delays + The 1st cell is reset pre-delay in micro seconds. + The 2nd cell is reset pulse in micro seconds. + The 3rd cell is reset post-delay in micro seconds. +- snps,pbl Programmable Burst Length +- snps,fixed-burst Program the DMA to use the fixed burst mode +- snps,mixed-burst Program the DMA to use the mixed burst mode +- snps,force_thresh_dma_mode Force DMA to use the threshold mode for + both tx and rx +- snps,force_sf_dma_mode Force DMA to use the Store and Forward + mode for both tx and rx. This flag is + ignored if force_thresh_dma_mode is set. +- snps,multicast-filter-bins: Number of multicast filter hash bins + supported by this device instance +- snps,perfect-filter-entries: Number of perfect filter entries supported + by this device instance + +Optional properties: +- resets: Should contain a phandle to the STMMAC reset signal, if any +- reset-names: Should contain the reset signal name "stmmaceth", if a + reset phandle is given +- max-frame-size: See ethernet.txt file in the same directory +- clocks: If present, the first clock should be the GMAC main clock, + further clocks may be specified in derived bindings. +- clock-names: One name for each entry in the clocks property, the + first one should be "stmmaceth". +- clk_ptp_ref: this is the PTP reference clock; in case of the PTP is + available this clock is used for programming the Timestamp Addend Register. + If not passed then the system clock will be used and this is fine on some + platforms. +- snps,burst_len: The AXI burst lenth value of the AXI BUS MODE register. + +Examples: + + gmac0: ethernet@e0800000 { + compatible = "st,spear600-gmac"; + reg = <0xe0800000 0x8000>; + interrupt-parent = <&vic1>; + interrupts = <24 23>; + interrupt-names = "macirq", "eth_wake_irq"; + mac-address = [000000000000]; /* Filled in by U-Boot */ + max-frame-size = <3800>; + phy-mode = "gmii"; + snps,multicast-filter-bins = <256>; + snps,perfect-filter-entries = <128>; + clocks = <&clock>; + clock-names = "stmmaceth"; + }; diff --git a/roms/u-boot/doc/device-tree-bindings/pci/armada8k-pcie.txt b/roms/u-boot/doc/device-tree-bindings/pci/armada8k-pcie.txt new file mode 100644 index 000000000..7230f1044 --- /dev/null +++ b/roms/u-boot/doc/device-tree-bindings/pci/armada8k-pcie.txt @@ -0,0 +1,49 @@ +Armada-8K PCIe DT details: +========================== + +Armada-8k uses synopsis designware PCIe controller. + +Required properties: +- compatible : should be "marvell,armada8k-pcie", "snps,dw-pcie". +- reg: base addresses and lengths of the pcie control and global control registers. + "ctrl" registers points to the global control registers, while the "config" space + points to the pcie configuration registers as mentioned in dw-pcie dt bindings in the link below. +- interrupt-map-mask and interrupt-map, standard PCI properties to + define the mapping of the PCIe interface to interrupt numbers. +- All other definitions as per generic PCI bindings +See Linux kernel documentation: +"Documentation/devicetree/bindings/pci/designware-pcie.txt" + +Optional properties: +PHY support is still not supported for armada-8k, once it will, the following parameters can be used: +- phys : phandle to phy node associated with pcie controller. +- phy-names : must be "pcie-phy" +- marvell,reset-gpio : specifies a gpio that needs to be activated for plug-in + card reset signal release. +Example: + +cpm_pcie0: pcie@f2600000 { + compatible = "marvell,armada8k-pcie", "snps,dw-pcie"; + reg = <0 0xf2600000 0 0x10000>, + <0 0xf6f00000 0 0x80000>; + reg-names = "ctrl", "config"; + #address-cells = <3>; + #size-cells = <2>; + #interrupt-cells = <1>; + device_type = "pci"; + dma-coherent; + + bus-range = <0 0xff>; + ranges = + /* downstream I/O */ + <0x81000000 0 0xf9000000 0 0xf9000000 0 0x10000 + /* non-prefetchable memory */ + 0x82000000 0 0xf6000000 0 0xf6000000 0 0xf00000>; + interrupt-map-mask = <0 0 0 0>; + interrupt-map = <0 0 0 0 &gic 0 GIC_SPI 32 IRQ_TYPE_LEVEL_HIGH>; + interrupts = <GIC_SPI 32 IRQ_TYPE_LEVEL_HIGH>; + num-lanes = <1>; + clocks = <&cpm_syscon0 1 13>; + marvell,reset-gpio = <&cpm_gpio1 20 GPIO_ACTIVE_HIGH>; + status = "disabled"; +}; diff --git a/roms/u-boot/doc/device-tree-bindings/pci/mediatek-pcie.txt b/roms/u-boot/doc/device-tree-bindings/pci/mediatek-pcie.txt new file mode 100644 index 000000000..2f9f549b7 --- /dev/null +++ b/roms/u-boot/doc/device-tree-bindings/pci/mediatek-pcie.txt @@ -0,0 +1,122 @@ +MediaTek Gen2 PCIe controller + +Required properties: +- compatible: Should contain one of the following strings: + "mediatek,mt7623-pcie" +- device_type: Must be "pci" +- reg: Base addresses and lengths of the PCIe subsys and root ports. +- reg-names: Names of the above areas to use during resource lookup. +- #address-cells: Address representation for root ports (must be 3) +- #size-cells: Size representation for root ports (must be 2) +- clocks: Must contain an entry for each entry in clock-names. +- clock-names: + Mandatory entries: + - sys_ckN :transaction layer and data link layer clock + Required entries for MT7623: + - free_ck :for reference clock of PCIe subsys + where N starting from 0 to one less than the number of root ports. +- phys: List of PHY specifiers (used by generic PHY framework). +- phy-names : Must be "pcie-phy0", "pcie-phy1", "pcie-phyN".. based on the + number of PHYs as specified in *phys* property. +- power-domains: A phandle and power domain specifier pair to the power domain + which is responsible for collapsing and restoring power to the peripheral. +- bus-range: Range of bus numbers associated with this controller. +- ranges: Ranges for the PCI memory and I/O regions. + +Required properties for MT7623: +- #interrupt-cells: Size representation for interrupts (must be 1) +- interrupt-map-mask and interrupt-map: Standard PCI IRQ mapping properties + Please refer to the standard PCI bus binding document for a more detailed + explanation. +- resets: Must contain an entry for each entry in reset-names. +- reset-names: Must be "pcie-rst0", "pcie-rst1", "pcie-rstN".. based on the + number of root ports. + +In addition, the device tree node must have sub-nodes describing each +PCIe port interface, having the following mandatory properties: + +Required properties: +- device_type: Must be "pci" +- reg: Only the first four bytes are used to refer to the correct bus number + and device number. +- #address-cells: Must be 3 +- #size-cells: Must be 2 +- #interrupt-cells: Must be 1 +- interrupt-map-mask and interrupt-map: Standard PCI IRQ mapping properties + Please refer to the standard PCI bus binding document for a more detailed + explanation. +- ranges: Sub-ranges distributed from the PCIe controller node. An empty + property is sufficient. + +Examples for MT7623: + + hifsys: syscon@1a000000 { + compatible = "mediatek,mt7623-hifsys", + "syscon"; + reg = <0x1a000000 0x1000>; + #clock-cells = <1>; + #reset-cells = <1>; + }; + + pcie: pcie@1a140000 { + compatible = "mediatek,mt7623-pcie"; + device_type = "pci"; + reg = <0x1a140000 0x1000>, /* PCIe shared registers */ + <0x1a142000 0x1000>, /* Port0 registers */ + <0x1a143000 0x1000>, /* Port1 registers */ + <0x1a144000 0x1000>; /* Port2 registers */ + reg-names = "subsys", "port0", "port1", "port2"; + #address-cells = <3>; + #size-cells = <2>; + #interrupt-cells = <1>; + interrupt-map-mask = <0xf800 0 0 0>; + interrupt-map = <0x0000 0 0 0 &sysirq GIC_SPI 193 IRQ_TYPE_LEVEL_LOW>, + <0x0800 0 0 0 &sysirq GIC_SPI 194 IRQ_TYPE_LEVEL_LOW>, + <0x1000 0 0 0 &sysirq GIC_SPI 195 IRQ_TYPE_LEVEL_LOW>; + clocks = <&topckgen CLK_TOP_ETHIF_SEL>, + <&hifsys CLK_HIFSYS_PCIE0>, + <&hifsys CLK_HIFSYS_PCIE1>, + <&hifsys CLK_HIFSYS_PCIE2>; + clock-names = "free_ck", "sys_ck0", "sys_ck1", "sys_ck2"; + resets = <&hifsys HIFSYS_PCIE0_RST>, + <&hifsys HIFSYS_PCIE1_RST>, + <&hifsys HIFSYS_PCIE2_RST>; + reset-names = "pcie-rst0", "pcie-rst1", "pcie-rst2"; + phys = <&pcie0_phy PHY_TYPE_PCIE>, <&pcie1_phy PHY_TYPE_PCIE>, + <&pcie2_phy PHY_TYPE_PCIE>; + phy-names = "pcie-phy0", "pcie-phy1", "pcie-phy2"; + power-domains = <&scpsys MT7623_POWER_DOMAIN_HIF>; + bus-range = <0x00 0xff>; + ranges = <0x81000000 0 0x1a160000 0x1a160000 0 0x00010000 /* I/O space */ + 0x83000000 0 0x60000000 0x60000000 0 0x10000000>; /* memory space */ + + pcie@0,0 { + reg = <0x0000 0 0 0 0>; + #address-cells = <3>; + #size-cells = <2>; + #interrupt-cells = <1>; + interrupt-map-mask = <0 0 0 0>; + interrupt-map = <0 0 0 0 &sysirq GIC_SPI 193 IRQ_TYPE_LEVEL_LOW>; + ranges; + }; + + pcie@1,0 { + reg = <0x0800 0 0 0 0>; + #address-cells = <3>; + #size-cells = <2>; + #interrupt-cells = <1>; + interrupt-map-mask = <0 0 0 0>; + interrupt-map = <0 0 0 0 &sysirq GIC_SPI 194 IRQ_TYPE_LEVEL_LOW>; + ranges; + }; + + pcie@2,0 { + reg = <0x1000 0 0 0 0>; + #address-cells = <3>; + #size-cells = <2>; + #interrupt-cells = <1>; + interrupt-map-mask = <0 0 0 0>; + interrupt-map = <0 0 0 0 &sysirq GIC_SPI 195 IRQ_TYPE_LEVEL_LOW>; + ranges; + }; + }; diff --git a/roms/u-boot/doc/device-tree-bindings/pci/x86-pci.txt b/roms/u-boot/doc/device-tree-bindings/pci/x86-pci.txt new file mode 100644 index 000000000..95e370b3e --- /dev/null +++ b/roms/u-boot/doc/device-tree-bindings/pci/x86-pci.txt @@ -0,0 +1,47 @@ +x86 PCI DT details: +=================== + +Some options are available to affect how PCI operates on x86. + +Optional properties: +- u-boot,skip-auto-config-until-reloc : Don't set up PCI configuration until + after U-Boot has relocated. Normally if PCI is used before relocation, + this happens before relocation also. Some platforms set up static + configuration in TPL/SPL to reduce code size and boot time, since these + phases only know about a small subset of PCI devices. + +For PCI devices the following optional property is available: + +- pci,no-autoconfig : Don't automatically configure this PCI device at all. + This is used when the device is statically configured and must maintain + this same config throughout the boot process. An example is a serial + UART being used to debug PCI configuration, since reconfiguring it stops + the UART from working until the driver is re-probed, and this can cause + output to be lost. This should not generally be used in production code, + although it is often harmless. + + +Example: + +pci { + compatible = "pci-x86"; + #address-cells = <3>; + #size-cells = <2>; + u-boot,dm-pre-reloc; + ranges = <0x02000000 0x0 0xc0000000 0xc0000000 0 0x10000000 + 0x42000000 0x0 0xb0000000 0xb0000000 0 0x10000000 + 0x01000000 0x0 0x1000 0x1000 0 0xefff>; + u-boot,skip-auto-config-until-reloc; + + + serial: serial@18,2 { + reg = <0x0200c210 0 0 0 0>; + u-boot,dm-pre-reloc; + compatible = "intel,apl-ns16550"; + early-regs = <0xde000000 0x20>; + reg-shift = <2>; + clock-frequency = <1843200>; + current-speed = <115200>; + pci,no-autoconfig; + }; +}; diff --git a/roms/u-boot/doc/device-tree-bindings/pci_endpoint/cdns,cdns-pcie-ep.txt b/roms/u-boot/doc/device-tree-bindings/pci_endpoint/cdns,cdns-pcie-ep.txt new file mode 100644 index 000000000..770543055 --- /dev/null +++ b/roms/u-boot/doc/device-tree-bindings/pci_endpoint/cdns,cdns-pcie-ep.txt @@ -0,0 +1,18 @@ +* Cadence PCIe endpoint controller + +Required properties: +- compatible: Should contain "cdns,cdns-pcie-ep" to identify the IP used. +- reg: Should contain the controller register base address. + +Optional properties: +- max-functions: Maximum number of functions that can be configured (default 1). +- cdns,max-outbound-regions: Set to maximum number of outbound regions (default 8) + +Example: + +pcie_ep@fc000000 { + compatible = "cdns,cdns-pcie-ep"; + reg = <0x0 0xfc000000 0x0 0x01000000>; + cdns,max-outbound-regions = <16>; + max-functions = /bits/ 8 <8>; +}; diff --git a/roms/u-boot/doc/device-tree-bindings/phy/mvebu_comphy.txt b/roms/u-boot/doc/device-tree-bindings/phy/mvebu_comphy.txt new file mode 100644 index 000000000..65b838485 --- /dev/null +++ b/roms/u-boot/doc/device-tree-bindings/phy/mvebu_comphy.txt @@ -0,0 +1,68 @@ +Marvell COMPHY SerDes lane bindings +===================================== + +The COMPHY node includes a description of the COMPHY SerDes lane configuration. +The COMPHY driver initializes the MUX of the SerDes lanes, and powers up the SerDes +by dependencies on the FDT blob configurations + +Mandatory properties: +SoC specific: + - compatible: + The compatible should include "marvell,mvebu-comphy" + and the COMPHY per chip compatible: + "marvell,comphy-cp110" for CP110 available in Aramda70x0/80x0. + The COMPHY per chip used to set which MUX configuration to use, and COMPHY power-up revision. + - reg: Base address and size of the COMPHY and hpipe units. + - max-lanes: Maximum number of comphy lanes. + - mux-bitcount: Number of bits that are allocated for every MUX in the COMPHY-selector register. +Board specific: + - PHY: Entry that include the configuration of the PHY. + Every PHY should have the below parameters: + - phy-type: the mode of the PHY + Possible modes located in include/dt-bindings/comphy/comphy_data.h + Optional properties: + - phy-speed: the speed of the PHY + Possible speeds values located in include/dt-bindings/comphy/comphy_data.h + - phy-invert: Polarity invert (COMPHY_POLARITY_TXD_INVERT/COMPHY_POLARITY_RXD_INVERT) + the possible bits under include/dt-bindings/comphy/comphy_data.h + - clk-src: Set the clock source of PCIe, if configured to PCIe clock output + This relevant for SerDes lane 5 only (by default, lane 4 is the clock source) + for Armada-7040 boards. + - endpoint: Optional boolean specifying this SerDes should be configured as PCIe endpoint. + +Example: + cpm_comphy: comphy@441000 { + compatible = "marvell,mvebu-comphy", "marvell,comphy-cp110"; + reg = <0x441000 0x8>, <0x120000 0x8>; + mux-bitcount = <4>; + max-lanes = <6>; + + /* + * CP110 Serdes Configuration: + * Lane 0: SGMII1 + * Lane 1: SATA 0 + * Lane 2: USB HOST 0 + * Lane 3: SATA1 + * Lane 4: SFI (10G) + * Lane 5: SGMII2 + */ + phy0 { + phy-type = <COMPHY_TYPE_SGMII1>; + phy-speed = <COMPHY_SPEED_1_25G>; + }; + phy1 { + phy-type = <COMPHY_TYPE_SATA0>; + }; + phy2 { + phy-type = <COMPHY_TYPE_USB3_HOST0>; + }; + phy3 { + phy-type = <COMPHY_TYPE_SATA1>; + }; + phy4 { + phy-type = <COMPHY_TYPE_SFI>; + }; + phy5 { + phy-type = <COMPHY_TYPE_SGMII2>; + }; + }; diff --git a/roms/u-boot/doc/device-tree-bindings/phy/no-op.txt b/roms/u-boot/doc/device-tree-bindings/phy/no-op.txt new file mode 100644 index 000000000..a3381122e --- /dev/null +++ b/roms/u-boot/doc/device-tree-bindings/phy/no-op.txt @@ -0,0 +1,16 @@ +NOP PHY driver + +This driver is used to stub PHY operations in a driver (USB, SATA). +This is useful when the 'client' driver (USB, SATA, ...) uses the PHY framework +and there is no actual PHY harwdare to drive. + +Required properties: +- compatible : must contain "nop-phy" +- #phy-cells : must contain <0> + +Example: + +nop_phy { + compatible = "nop-phy"; + #phy-cells = <0>; +}; diff --git a/roms/u-boot/doc/device-tree-bindings/phy/phy-mtk-tphy.txt b/roms/u-boot/doc/device-tree-bindings/phy/phy-mtk-tphy.txt new file mode 100644 index 000000000..8cd23d8c0 --- /dev/null +++ b/roms/u-boot/doc/device-tree-bindings/phy/phy-mtk-tphy.txt @@ -0,0 +1,144 @@ +MediaTek T-PHY binding +-------------------------- + +T-phy controller supports physical layer functionality for a number of +controllers on MediaTek SoCs, such as, USB2.0, USB3.0, PCIe, and SATA. + +Required properties (controller (parent) node): + - compatible : should be one of + "mediatek,generic-tphy-v1" + "mediatek,generic-tphy-v2" + +- #address-cells: the number of cells used to represent physical + base addresses. +- #size-cells: the number of cells used to represent the size of an address. +- ranges: the address mapping relationship to the parent, defined with + - empty value: if optional 'reg' is used. + - non-empty value: if optional 'reg' is not used. should set + the child's base address to 0, the physical address + within parent's address space, and the length of + the address map. + +Required nodes : a sub-node is required for each port the controller + provides. Address range information including the usual + 'reg' property is used inside these nodes to describe + the controller's topology. + +Optional properties (controller (parent) node): + - reg : offset and length of register shared by multiple ports, + exclude port's private register. + - mediatek,src-ref-clk-mhz : frequency of reference clock for slew rate + calibrate + - mediatek,src-coef : coefficient for slew rate calibrate, depends on + SoC process + +Required properties (port (child) node): +- reg : address and length of the register set for the port. +- #phy-cells : should be 1 (See second example) + cell after port phandle is phy type from: + - PHY_TYPE_USB2 + - PHY_TYPE_USB3 + - PHY_TYPE_PCIE + - PHY_TYPE_SATA + +Optional properties (port (child) node): +- clocks : a list of phandle + clock-specifier pairs, one for each + entry in clock-names +- clock-names : may contain + "ref": 48M reference clock for HighSpeed (digital) phy; and 26M + reference clock for SuperSpeed (digital) phy, sometimes is + 24M, 25M or 27M, depended on platform. + "da_ref": the reference clock of analog phy, used if the clocks + of analog and digital phys are separated, otherwise uses + "ref" clock only if needed. + +Example: + + u3phy2: usb-phy@1a244000 { + compatible = "mediatek,generic-tphy-v1"; + reg = <0x1a244000 0x0700>; + #address-cells = <1>; + #size-cells = <1>; + ranges; + status = "disabled"; + + u2port1: usb-phy@1a244800 { + reg = <0x1a244800 0x0100>; + clocks = <&topckgen CLK_TOP_USB_PHY48M>; + clock-names = "ref"; + #phy-cells = <1>; + status = "okay"; + }; + + u3port1: usb-phy@1a244900 { + reg = <0x1a244900 0x0700>; + clocks = <&clk26m>; + clock-names = "ref"; + #phy-cells = <1>; + status = "okay"; + }; + }; + +Specifying phy control of devices +--------------------------------- + +Device nodes should specify the configuration required in their "phys" +property, containing a phandle to the phy port node and a device type; +phy-names for each port are optional. + +Example: + +#include <dt-bindings/phy/phy.h> + +usb30: usb@11270000 { + ... + phys = <&u2port0 PHY_TYPE_USB2>, <&u3port0 PHY_TYPE_USB3>; + phy-names = "usb2-0", "usb3-0"; + ... +}; + +Layout differences of banks between TPHY V1 and V2 +------------------------------------------------------------- +IP V1: +port offset bank +shared 0x0000 SPLLC + 0x0100 FMREG +u2 port0 0x0800 U2PHY_COM +u3 port0 0x0900 U3PHYD + 0x0a00 U3PHYD_BANK2 + 0x0b00 U3PHYA + 0x0c00 U3PHYA_DA +u2 port1 0x1000 U2PHY_COM +u3 port1 0x1100 U3PHYD + 0x1200 U3PHYD_BANK2 + 0x1300 U3PHYA + 0x1400 U3PHYA_DA +u2 port2 0x1800 U2PHY_COM + ... + +IP V2: +port offset bank +u2 port0 0x0000 MISC + 0x0100 FMREG + 0x0300 U2PHY_COM +u3 port0 0x0700 SPLLC + 0x0800 CHIP + 0x0900 U3PHYD + 0x0a00 U3PHYD_BANK2 + 0x0b00 U3PHYA + 0x0c00 U3PHYA_DA +u2 port1 0x1000 MISC + 0x1100 FMREG + 0x1300 U2PHY_COM +u3 port1 0x1700 SPLLC + 0x1800 CHIP + 0x1900 U3PHYD + 0x1a00 U3PHYD_BANK2 + 0x1b00 U3PHYA + 0x1c00 U3PHYA_DA +u2 port2 0x2000 MISC + ... + + SPLLC shared by u3 ports and FMREG shared by u2 ports on +TPHY V1 are put back into each port; a new bank MISC for +u2 ports and CHIP for u3 ports are added on TPHY V2. diff --git a/roms/u-boot/doc/device-tree-bindings/phy/phy-stih407-usb.txt b/roms/u-boot/doc/device-tree-bindings/phy/phy-stih407-usb.txt new file mode 100644 index 000000000..371a7fec0 --- /dev/null +++ b/roms/u-boot/doc/device-tree-bindings/phy/phy-stih407-usb.txt @@ -0,0 +1,24 @@ +ST STiH407 USB PHY controller + +This file documents the dt bindings for the usb picoPHY driver which is the PHY for both USB2 and USB3 +host controllers (when controlling usb2/1.1 devices) available on STiH407 SoC family from STMicroelectronics. + +Required properties: +- compatible : should be "st,stih407-usb2-phy" +- st,syscfg : phandle of sysconfig bank plus integer array containing phyparam and phyctrl register offsets +- resets : list of phandle and reset specifier pairs. There should be two entries, one + for the whole phy and one for the port +- reset-names : list of reset signal names. Should be "global" and "port" +See: Documentation/devicetree/bindings/reset/st,sti-powerdown.txt +See: Documentation/devicetree/bindings/reset/reset.txt + +Example: + +usb2_picophy0: usbpicophy { + compatible = "st,stih407-usb2-phy"; + #phy-cells = <0>; + st,syscfg = <&syscfg_core 0x100 0xf4>; + resets = <&softreset STIH407_PICOPHY_SOFTRESET>, + <&picophyreset STIH407_PICOPHY0_RESET>; + reset-names = "global", "port"; +}; diff --git a/roms/u-boot/doc/device-tree-bindings/phy/phy-stm32-usbphyc.txt b/roms/u-boot/doc/device-tree-bindings/phy/phy-stm32-usbphyc.txt new file mode 100644 index 000000000..edfe4b426 --- /dev/null +++ b/roms/u-boot/doc/device-tree-bindings/phy/phy-stm32-usbphyc.txt @@ -0,0 +1,75 @@ +STMicroelectronics STM32 USB HS PHY controller + +The STM32 USBPHYC block contains a dual port High Speed UTMI+ PHY and a UTMI +switch. It controls PHY configuration and status, and the UTMI+ switch that +selects either OTG or HOST controller for the second PHY port. It also sets +PLL configuration. + +USBPHYC + |_ PLL + | + |_ PHY port#1 _________________ HOST controller + | _ | + | / 1|________________| + |_ PHY port#2 ----| |________________ + | \_0| | + |_ UTMI switch_______| OTG controller + + +Phy provider node +================= + +Required properties: +- compatible: must be "st,stm32mp1-usbphyc" +- reg: address and length of the usb phy control register set +- clocks: phandle + clock specifier for the PLL phy clock +- vdda1v1-supply: phandle to the regulator providing 1V1 power to the PHY +- vdda1v8-supply: phandle to the regulator providing 1V8 power to the PHY +- #address-cells: number of address cells for phys sub-nodes, must be <1> +- #size-cells: number of size cells for phys sub-nodes, must be <0> + +Optional properties: +- assigned-clocks: phandle + clock specifier for the PLL phy clock +- assigned-clock-parents: the PLL phy clock parent +- resets: phandle + reset specifier + +Required nodes: one sub-node per port the controller provides. + +Phy sub-nodes +============== + +Required properties: +- reg: phy port index +- phy-supply: phandle to the regulator providing 3V3 power to the PHY, + see phy-bindings.txt in the same directory. +- #phy-cells: see phy-bindings.txt in the same directory, must be <0> for PHY + port#1 and must be <1> for PHY port#2, to select USB controller + +Optional properties: +- vbus-supply: phandle to the regulator providing 5V vbus to the USB connector + +Example: + usbphyc: usb-phy@5a006000 { + compatible = "st,stm32mp1-usbphyc"; + reg = <0x5a006000 0x1000>; + clocks = <&rcc_clk USBPHY_K>; + resets = <&rcc_rst USBPHY_R>; + #address-cells = <1>; + #size-cells = <0>; + + usbphyc_port0: usb-phy@0 { + reg = <0>; + phy-supply = <&vdd_usb>; + vdda1v1-supply = <®11>; + vdda1v8-supply = <®18> + #phy-cells = <0>; + }; + + usbphyc_port1: usb-phy@1 { + reg = <1>; + phy-supply = <&vdd_usb>; + vdda1v1-supply = <®11>; + vdda1v8-supply = <®18> + #phy-cells = <1>; + }; + }; diff --git a/roms/u-boot/doc/device-tree-bindings/phy/sun4i-usb-phy.txt b/roms/u-boot/doc/device-tree-bindings/phy/sun4i-usb-phy.txt new file mode 100644 index 000000000..c1ce5a0a6 --- /dev/null +++ b/roms/u-boot/doc/device-tree-bindings/phy/sun4i-usb-phy.txt @@ -0,0 +1,65 @@ +Allwinner sun4i USB PHY +----------------------- + +Required properties: +- compatible : should be one of + * allwinner,sun4i-a10-usb-phy + * allwinner,sun5i-a13-usb-phy + * allwinner,sun6i-a31-usb-phy + * allwinner,sun7i-a20-usb-phy + * allwinner,sun8i-a23-usb-phy + * allwinner,sun8i-a33-usb-phy + * allwinner,sun8i-a83t-usb-phy + * allwinner,sun8i-h3-usb-phy + * allwinner,sun8i-v3s-usb-phy + * allwinner,sun50i-a64-usb-phy +- reg : a list of offset + length pairs +- reg-names : + * "phy_ctrl" + * "pmu0" for H3, V3s and A64 + * "pmu1" + * "pmu2" for sun4i, sun6i, sun7i, sun8i-a83t or sun8i-h3 + * "pmu3" for sun8i-h3 +- #phy-cells : from the generic phy bindings, must be 1 +- clocks : phandle + clock specifier for the phy clocks +- clock-names : + * "usb_phy" for sun4i, sun5i or sun7i + * "usb0_phy", "usb1_phy" and "usb2_phy" for sun6i + * "usb0_phy", "usb1_phy" for sun8i + * "usb0_phy", "usb1_phy", "usb2_phy" and "usb2_hsic_12M" for sun8i-a83t + * "usb0_phy", "usb1_phy", "usb2_phy" and "usb3_phy" for sun8i-h3 +- resets : a list of phandle + reset specifier pairs +- reset-names : + * "usb0_reset" + * "usb1_reset" + * "usb2_reset" for sun4i, sun6i, sun7i, sun8i-a83t or sun8i-h3 + * "usb3_reset" for sun8i-h3 + +Optional properties: +- usb0_id_det-gpios : gpio phandle for reading the otg id pin value +- usb0_vbus_det-gpios : gpio phandle for detecting the presence of usb0 vbus +- usb0_vbus_power-supply: power-supply phandle for usb0 vbus presence detect +- usb0_vbus-supply : regulator phandle for controller usb0 vbus +- usb1_vbus-supply : regulator phandle for controller usb1 vbus +- usb2_vbus-supply : regulator phandle for controller usb2 vbus +- usb3_vbus-supply : regulator phandle for controller usb3 vbus + +Example: + usbphy: phy@01c13400 { + #phy-cells = <1>; + compatible = "allwinner,sun4i-a10-usb-phy"; + /* phy base regs, phy1 pmu reg, phy2 pmu reg */ + reg = <0x01c13400 0x10 0x01c14800 0x4 0x01c1c800 0x4>; + reg-names = "phy_ctrl", "pmu1", "pmu2"; + clocks = <&usb_clk 8>; + clock-names = "usb_phy"; + resets = <&usb_clk 0>, <&usb_clk 1>, <&usb_clk 2>; + reset-names = "usb0_reset", "usb1_reset", "usb2_reset"; + pinctrl-names = "default"; + pinctrl-0 = <&usb0_id_detect_pin>, <&usb0_vbus_detect_pin>; + usb0_id_det-gpios = <&pio 7 19 GPIO_ACTIVE_HIGH>; /* PH19 */ + usb0_vbus_det-gpios = <&pio 7 22 GPIO_ACTIVE_HIGH>; /* PH22 */ + usb0_vbus-supply = <®_usb0_vbus>; + usb1_vbus-supply = <®_usb1_vbus>; + usb2_vbus-supply = <®_usb2_vbus>; + }; diff --git a/roms/u-boot/doc/device-tree-bindings/pinctrl/atmel,at91-pio4-pinctrl.txt b/roms/u-boot/doc/device-tree-bindings/pinctrl/atmel,at91-pio4-pinctrl.txt new file mode 100644 index 000000000..6e936a08b --- /dev/null +++ b/roms/u-boot/doc/device-tree-bindings/pinctrl/atmel,at91-pio4-pinctrl.txt @@ -0,0 +1,69 @@ +* Atmel PIO4 Controller + +The Atmel PIO4 controller is used to select the function of a pin and to +configure it. + +Required properties: +- compatible: "atmel,sama5d2-pinctrl". +- reg: base address and length of the PIO controller. + +Please refer to pinctrl-bindings.txt in this directory for details of the +common pinctrl bindings used by client devices. + +Subnode format +Each node (or subnode) will list the pins it needs and how to configured these +pins. + + node { + pinmux = <PIN_NUMBER_PINMUX>; + GENERIC_PINCONFIG; + }; + +Required properties: +- pinmux: integer array. Each integer represents a pin number plus mux and +ioset settings. Use the macros from boot/dts/<soc>-pinfunc.h file to get the +right representation of the pin. + +Optional properties: +- GENERIC_PINCONFIG: generic pinconfig options to use: + - bias-disable, bias-pull-down, bias-pull-up, drive-open-drain, + input-schmitt-enable, input-debounce + - slew-rate: 0 - disabled, 1 - enabled (default) +- atmel,drive-strength: 0 or 1 for low drive, 2 for medium drive and 3 for +high drive. The default value is low drive. + +Example: + +#include <sama5d2-pinfunc.h> + +... +{ + spi0: spi@f8000000 { + cs-gpios = <&pioA 17 0>, <0>, <0>, <0>; + pinctrl-names = "default"; + pinctrl-0 = <&pinctrl_spi0_default>; + status = "okay"; + + spi_flash@0 { + compatible = "jedec,spi-nor"; + reg = <0>; + spi-max-frequency = <50000000>; + }; + }; + + ... + + pioA: pinctrl@fc038000 { + compatible = "atmel,sama5d2-pinctrl"; + reg = <0xfc038000 0x600>; + + pinctrl_spi0_default: spi0_default { + pinmux = <PIN_PA14__SPI0_SPCK>, + <PIN_PA15__SPI0_MOSI>, + <PIN_PA16__SPI0_MISO>; + bias-disable; + }; + ... + }; +}; +... diff --git a/roms/u-boot/doc/device-tree-bindings/pinctrl/bcm6838-pinctrl.txt b/roms/u-boot/doc/device-tree-bindings/pinctrl/bcm6838-pinctrl.txt new file mode 100644 index 000000000..2034f0599 --- /dev/null +++ b/roms/u-boot/doc/device-tree-bindings/pinctrl/bcm6838-pinctrl.txt @@ -0,0 +1,35 @@ +* broadcom bcm6838 pinctrl + +Required properties for the pinctrl driver: +- compatible: "brcm,bcm6838-pinctrl" +- regmap: specify the gpio test port syscon +- brcm,pins-count: the number of pin +- brcm,functions-count: the number of function + +Please refer to pinctrl-bindings.txt in this directory for details of the +common pinctrl bindings used by client devices. + +Example: + + gpio_test_port: syscon@14e00294 { + compatible = "syscon"; + reg = <0x14e00294 0x1c>; + }; + + pinctrl: pinctrl { + compatible = "brcm,bcm6838-pinctrl"; + regmap = <&gpio_test_port>; + brcm,pins-count = <74>; + brcm,functions-count = <8>; + + usb0: usb0 { + usb0_pwrflt { + pins = "69"; + function = "1"; + }; + usb0_pwron { + pins = "70"; + function = "1"; + }; + }; + }; diff --git a/roms/u-boot/doc/device-tree-bindings/pinctrl/intel,apl-pinctrl.txt b/roms/u-boot/doc/device-tree-bindings/pinctrl/intel,apl-pinctrl.txt new file mode 100644 index 000000000..12ec84610 --- /dev/null +++ b/roms/u-boot/doc/device-tree-bindings/pinctrl/intel,apl-pinctrl.txt @@ -0,0 +1,39 @@ +* Intel Apollo Lake pin controller + +The Apollo Lake (APL) pin controller is used to select the function of a pin +and to configure it. + +Required properties: +- compatible: "intel,apl-pinctrl" +- intel,p2sb-port-id: Port ID number within the parent P2SB +- reg: PCI address of the controller + +Please refer to pinctrl-bindings.txt in this directory for details of the +common pinctrl bindings used by client devices. + +Optional subnodes: + +GPIO nodes may be added as children of the pinctrl nodes. See intel,apl-gpio +for the binding. + + +Example: + +... +{ + p2sb: p2sb@d,0 { + reg = <0x02006810 0 0 0 0>; + compatible = "intel,p2sb"; + early-regs = <IOMAP_P2SB_BAR 0x100000>; + + n { + compatible = "intel,apl-pinctrl"; + intel,p2sb-port-id = <PID_GPIO_N>; + gpio_n: gpio-n { + compatible = "intel,apl-gpio"; + #gpio-cells = <2>; + }; + }; + }; +}; +... diff --git a/roms/u-boot/doc/device-tree-bindings/pinctrl/kendryte,k210-fpioa.txt b/roms/u-boot/doc/device-tree-bindings/pinctrl/kendryte,k210-fpioa.txt new file mode 100644 index 000000000..73871f593 --- /dev/null +++ b/roms/u-boot/doc/device-tree-bindings/pinctrl/kendryte,k210-fpioa.txt @@ -0,0 +1,102 @@ +Kendryte K210 FPIOA + +This binding describes the Fully-Programmable Input/Output Array (FPIOA) found +in Kendryte K210 SoCs. Any of the 256 functions can be mapped to any of the 48 +pins. + +Required properties: +- compatible: should be "kendryte,k210-fpioa" +- reg: address and length of the FPIOA registers +- kendryte,sysctl: phandle to the "sysctl" register map node +- kendryte,power-offset: offset in the register map of the power bank control + register (in bytes) + +Configuration nodes + +Pin configuration nodes are documented in pinctrl-bindings.txt + +Required properties for pin-configuration nodes or sub-nodes are: +- groups: list of power groups to which the configuration applies. Valid groups + are: + A0, A1, A2, B3, B4, B5, C6, C7 + (either this or "pinmux" must be specified) +- pinmux: integer array representing pin multiplexing configuration. In addition + to the 256 standard functions, each pin can also output the direction + indicator (DO) of any function. This signal is high whenever the function + would normally drive the output. Helper macros to ease assembling the "pinmux" + arguments from the pin and function are provided by the FPIOA header file at: + <dt-bindings/pinctrl/k210-pinctrl.h> + Integer values in the "pinmux" argument list are assembled as: + ((PIN << 16) | (DO << 8) | (FUNC)) + Valid values for PIN are numbers 0 through 47. + Valid values for DO are 0 or 1. + Valid values for FUNC are numbers 0 through 255. For a complete list of + acceptable functions, consult the FPIOA header file. + (either this or "groups" must be specified) + +Optional properties for "pinmux" nodes are: + bias-disable, bias-pull-down, bias-pull-up, drive-strength, + drive-strength-ua, input-enable, input-disable, input-schmitt-enable, + input-schmitt-disable, output-low, output-high, output-enable, + output-disable, slew-rate, output-polarity-invert, input-polarity-invert + +Optional properties for "groups" nodes are: + power-source + +Notes on specific properties include: +- bias-pull-up, -down, and -pin-default: The pull strength cannot be configured. +- drive-strength: There are 8 drive strength settings between 11 and 50 mA. +- input- and output-polarity-invert: Invert the polarity of either the input or + the output, respectively. +- power-source: Controls the output voltage of a bank of pins. Either + K210_PC_POWER_1V8 or K210_PC_POWER_3V3 may be specified. +- slew-rate: Specifying this property reduces the slew rate. + +Example: +fpioa: pinmux@502B0000 { + compatible = "kendryte,k210-fpioa"; + reg = <0x502B0000 0x100>; + kendryte,sysctl = <&sysctl>; + kendryte,power-offset = <K210_SYSCTL_POWER_SEL>; + + /* JTAG running at 3.3V and driven at 11 mA */ + fpioa_jtag: jtag { + voltage { + group = "A0"; + power-source = <K210_PC_POWER_3V3>; + }; + + jtag { + pinmux = <K210_FPIOA(0, K210_PCF_JTAG_TCK)>, + <K210_FPIOA(1, K210_PCF_JTAG_TDI)>, + <K210_FPIOA(2, K210_PCF_JTAG_TMS)>, + <K210_FPIOA(3, K210_PCF_JTAG_TDO)>; + drive-strength = <11>; + } + }; + + /* I2C configured for use with a TCA9800 level shifter */ + fpioa_i2c: i2c { + i2c { + pinmux = <K210_FPIOA(6, K210_PCF_I2C0_SCLK)>, + <K210_FPIOA(7, K210_PCF_I2C0_SDA)>; + }; + + direction { + pinmux = <K210_FPIOA_DO(8, K210_PCF_I2C0_SDA)>; + output-polarity-invert; + }; + }; + + /* UART with an active-high TX status LED */ + fpioa_uart1: uart1 { + uart { + pinmux = <K210_FPIOA(9, K210_PCF_UART1_TX)>, + <K210_FPIOA(10, K210_PCF_UART1_RX)>; + }; + + status { + pinmux = <K210_FPIOA_DO(11, K210_PCF_UART1_TX)>; + }; + }; +}; diff --git a/roms/u-boot/doc/device-tree-bindings/pinctrl/marvell,armada-37xx-pinctrl.txt b/roms/u-boot/doc/device-tree-bindings/pinctrl/marvell,armada-37xx-pinctrl.txt new file mode 100644 index 000000000..86ec11361 --- /dev/null +++ b/roms/u-boot/doc/device-tree-bindings/pinctrl/marvell,armada-37xx-pinctrl.txt @@ -0,0 +1,186 @@ +* Marvell Armada 37xx SoC pin and GPIO controller + +Each Armada 37xx SoC comes with two pin and GPIO controllers, one for the +South Bridge and the other for the North Bridge. + +GPIO and pin controller: +------------------------ + +Main node: + +Refer to pinctrl-bindings.txt in this directory for details of the +common pinctrl bindings used by client devices, including the meaning +of the phrase "pin configuration node". + +Required properties for pinctrl driver: + +- compatible: "marvell,armada3710-sb-pinctrl", "syscon, "simple-mfd" + for the South Bridge + "marvell,armada3710-nb-pinctrl", "syscon, "simple-mfd" + for the North Bridge +- reg: The first set of registers is for pinctrl/GPIO and the second + set is for the interrupt controller +- interrupts: list of interrupts used by the GPIO + +Available groups and functions for the North Bridge: + +group: jtag + - pins 20-24 + - functions jtag, gpio + +group sdio0 + - pins 8-10 + - functions sdio, gpio + +group emmc_nb + - pins 27-35 + - functions emmc, gpio + +group pwm0 + - pin 11 (GPIO1-11) + - functions pwm, gpio + +group pwm1 + - pin 12 + - functions pwm, gpio + +group pwm2 + - pin 13 + - functions pwm, gpio + +group pwm3 + - pin 14 + - functions pwm, gpio + +group pmic1 + - pin 7 + - functions pmic, gpio + +group pmic0 + - pin 6 + - functions pmic, gpio + +group i2c2 + - pins 2-3 + - functions i2c, gpio + +group i2c1 + - pins 0-1 + - functions i2c, gpio + +group spi_cs1 + - pin 17 + - functions spi, gpio + +group spi_cs2 + - pin 18 + - functions spi, gpio + +group spi_cs3 + - pin 19 + - functions spi, gpio + +group onewire + - pin 4 + - functions onewire, gpio + +group uart1 + - pins 25-26 + - functions uart, gpio + +group spi_quad + - pins 15-16 + - functions spi, gpio + +group uart_2 + - pins 9-10 + - functions uart, gpio + +Available groups and functions for the South Bridge: + +group usb32_drvvbus0 + - pin 36 + - functions drvbus, gpio + +group usb2_drvvbus1 + - pin 37 + - functions drvbus, gpio + +group sdio_sb + - pins 60-65 + - functions sdio, gpio + +group rgmii + - pins 42-53 + - functions mii, gpio + +group pcie1 + - pins 39-41 + - functions pcie, gpio + +group smi + - pins 54-55 + - functions smi, gpio + +group ptp + - pins 56-58 + - functions ptp, gpio + +group ptp_clk + - pin 57 + - functions ptp, mii + +group ptp_trig + - pin 58 + - functions ptp, mii + +group mii_col + - pin 59 + - functions mii, mii_err + +GPIO subnode: + +Please refer to gpio.txt in "gpio" directory for details of gpio-ranges property +and the common GPIO bindings used by client devices. + +Required properties for the GPIO driver under the gpio subnode: +- interrupts: List of interrupt specifiers for the controllers interrupt. +- gpio-controller: Marks the device node as a GPIO controller. +- #gpio-cells: Should be 2. The first cell is the GPIO number and the + second cell specifies GPIO flags, as defined in + <dt-bindings/gpio/gpio.h>. Only the GPIO_ACTIVE_HIGH and + GPIO_ACTIVE_LOW flags are supported. +- gpio-ranges: Range of pins managed by the GPIO controller. + +Example: +pinctrl_sb: pinctrl-sb@18800 { + compatible = "marvell,armada3710-sb-pinctrl", + "syscon", "simple-mfd"; + reg = <0x18800 0x100>, <0x18C00 0x20>; + gpiosb: gpiosb { + #gpio-cells = <2>; + gpio-ranges = <&pinctrl_sb 0 0 30>; + gpio-controller; + interrupts = + <GIC_SPI 160 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 159 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 158 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 157 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 156 IRQ_TYPE_LEVEL_HIGH>; + }; + + rgmii_pins: mii-pins { + groups = "rgmii"; + function = "mii"; + }; + + sdio_pins: sdio-pins { + groups = "sdio_sb"; + function = "sdio"; + }; + + pcie_pins: pcie-pins { + groups = "pcie1"; + function = "pcie"; + }; +};
\ No newline at end of file diff --git a/roms/u-boot/doc/device-tree-bindings/pinctrl/marvell,armada-apn806-pinctrl.txt b/roms/u-boot/doc/device-tree-bindings/pinctrl/marvell,armada-apn806-pinctrl.txt new file mode 100644 index 000000000..51f2f2c79 --- /dev/null +++ b/roms/u-boot/doc/device-tree-bindings/pinctrl/marvell,armada-apn806-pinctrl.txt @@ -0,0 +1,25 @@ + Functions of Armada APN806 pin controller + Function 0x0 for any MPP ID activates GPIO pin mode +---------------------------------------------------------------------- +MPP# 0x1 0x2 0x3 0x4 +---------------------------------------------------------------------- +0 SDIO_CLK - SPI0_CLK - +1 SDIO_CMD - SPI0_MISO - +2 SDIO_D[0] - SPI0_MOSI - +3 SDIO_D[1] - SPI0_CS0n - +4 SDIO_D[2] - I2C0_SDA SPI0_CS1n +5 SDIO_D[3] - I2C0_SCK - +6 SDIO_DS - - - +7 SDIO_D[4] - UART1_RXD - +8 SDIO_D[5] - UART1_TXD - +9 SDIO_D[6] - SPI0_CS1n - +10 SDIO_D[7] - - - +11 - - UART0_TXD - +12 SDIO_CARD_PW_OFF SDIO_HW_RST - - +13 - - - - +14 - - - - +15 - - - - +16 - - - - +17 - - - - +18 - - - - +19 - - UART0_RXD - diff --git a/roms/u-boot/doc/device-tree-bindings/pinctrl/marvell,armada-cp110-pinctrl.txt b/roms/u-boot/doc/device-tree-bindings/pinctrl/marvell,armada-cp110-pinctrl.txt new file mode 100644 index 000000000..3adcf3aae --- /dev/null +++ b/roms/u-boot/doc/device-tree-bindings/pinctrl/marvell,armada-cp110-pinctrl.txt @@ -0,0 +1,270 @@ + Functions of Armada CP110 pin controller + Function 0x0 for any MPP ID activates GPIO pin mode + Function 0xc for any MPP ID activates DEBUG_BUS pin mode +------------------------------------------------------------------------------- +MPP# 0x1 0x2 0x3 0x4 +------------------------------------------------------------------------------- +0 DEV_ALE[1] AU_I2SMCLK GE0_RXD[3] TDM_PCLK +1 DEV_ALE[0] AU_I2SDO_SPDIFO GE0_RXD[2] TDM_DRX +2 DEV_AD[15] AU_I2SEXTCLK GE0_RXD[1] TDM_DTX +3 DEV_AD[14] AU_I2SLRCLK GE0_RXD[0] TDM_FSYNC +4 DEV_AD[13] AU_I2SBCLK GE0_RXCTL TDM_RSTn +5 DEV_AD[12] AU_I2SDI GE0_RXCLK TDM_INTn +6 DEV_AD[11] - GE0_TXD[3] SPI0_CSn[2] +7 DEV_AD[10] - GE0_TXD[2] SPI0_CSn[1] +8 DEV_AD[9] - GE0_TXD[1] SPI0_CSn[0] +9 DEV_AD[8] - GE0_TXD[0] SPI0_MOSI +10 DEV_READYn - GE0_TXCTL SPI0_MISO +11 DEV_WEn[1] - GE0_TXCLKOUT SPI0_CLK +12 DEV_CLK_OUT NF_RBn[1] SPI1_CSn[1] GE0_RXCLK +13 DEV_BURSTn NF_RBn[0] SPI1_MISO GE0_RXCTL +14 DEV_BOOTCSn DEV_CSn[0] SPI1_CSn[0] SPI0_CSn[3] +15 DEV_AD[7] - SPI1_MOSI - +16 DEV_AD[6] - SPI1_CLK - +17 DEV_AD[5] - - GE0_TXD[3] +18 DEV_AD[4] - - GE0_TXD[2] +19 DEV_AD[3] - - GE0_TXD[1] +20 DEV_AD[2] - - GE0_TXD[0] +21 DEV_AD[1] - - GE0_TXCTL +22 DEV_AD[0] - - GE0_TXCLKOUT +23 DEV_A[1] - - - +24 DEV_A[0] - - - +25 DEV_OEn - - - - +26 DEV_WEn[0] - - - +27 DEV_CSn[0] SPI1_MISO MSS_GPIO[4] GE0_RXD[3] +28 DEV_CSn[1] SPI1_CSn[0] MSS_GPIO[5] GE0_RXD[2] +29 DEV_CSn[2] SPI1_MOSI MSS_GPIO[6] GE0_RXD[1] +30 DEV_CSn[3] SPI1_CLK MSS_GPIO[7] GE0_RXD[0] +31 DEV_A[2] - MSS_GPIO[4] - +32 MII_COL MII_TXERR MSS_SPI_MISO TDM_DRX +33 MII_TXCLK SDIO_PWR1[0] MSS_SPI_CSn TDM_FSYNC +34 MII_RXERR SDIO_PWR1[1] MSS_SPI_MOSI TDM_DTX +35 SATA1_PRESENT_ACTIVEn TWSI1_SDA MSS_SPI_CLK TDM_PCLK +36 SYNCE2_CLK TWSI1_SCK PTP_CLK SYNCE1_CLK +37 UART2_RXD TWSI0_SCK PTP_PCLK_OUT TDM_INTn +38 UART2_TXD TWSI0_SDA PTP_PULSE TDM_RSTn +39 SDIO_WR_PROTECT - - AU_I2SBCLK PTP_CLK +40 SDIO_PWR1[1] SYNCE1_CLK MSS_TWSI_SDA AU_I2SDO_SPDIFO +41 SDIO_PWR1[0] SDIO_BUS_PWR MSS_TWSI_SCK AU_I2SLRCLK +42 SDIO_V18_EN SDIO_WR_PROTECT SYNCE2_CLK AU_I2SMCLK +43 SDIO_CARD_DETECT - SYNCE1_CLK AU_I2SEXTCLK +44 GE1_TXD[2] - - - +45 GE1_TXD[3] - - - +46 GE1_TXD[1] - - - +47 GE1_TXD[0] - - - +48 GE1_TXCTL_MII_TXEN - - - +49 GE1_TXCLKOUT MII_CRS - - +50 GE1_RXCLK MSS_TWSI_SDA - - +51 GE1_RXD[0] MSS_TWSI_SCK - - +52 GE1_RXD[1] SYNCE1_CLK - SYNCE2_CLK +53 GE1_RXD[2] - PTP_CLK - +54 GE1_RXD[3] SYNCE2_CLK PTP_PCLK_OUT SYNCE1_CLK +55 GE1_RXCTL_MII_RXDV - PTP_PULSE - +56 - - - TDM_DRX +57 - MSS_TWSI_SDA PTP_PCLK_OUT TDM_INTn +58 - MSS_TWSI_SCK PTP_CLK TDM_RSTn +59 MSS_GPIO[7] SYNCE2_CLK - TDM_FSYNC +60 MSS_GPIO[6] - PTP_PULSE TDM_DTX +61 MSS_GPIO[5] - PTP_CLK TDM_PCLK +62 MSS_GPIO[4] SYNCE1_CLK PTP_PCLK_OUT - + +------------------------------------------------------------------------------- +MPP# 0x5 0x6 0x7 +------------------------------------------------------------------------------- +0 - PTP_PULSE MSS_TWSI_SDA +1 - PTP_CLK MSS_TWSI_SCK +2 MSS_UART_RXD PTP_PCLK_OUT TWSI1_SCK +3 MSS_UART_TXD PCIe_RSTOUTn TWSI1_SDA +4 MSS_UART_RXD UART1_CTS PCIe0_CLKREQ +5 MSS_UART_TXD UART1_RTS PCIe1_CLKREQ +6 AU_I2SEXTCLK SATA1_PRESENT_ACTIVEn PCIe2_CLKREQ +7 SPI1_CSn[1] SATA0_PRESENT_ACTIVEn LED_DATA +8 SPI1_CSn[0] UART0_CTS LED_STB +9 SPI1_MOSI - PCIe_RSTOUTn +10 SPI1_MISO UART0_CTS SATA1_PRESENT_ACTIVEn +11 SPI1_CLK UART0_RTS LED_CLK +12 - - - +13 - - - +14 AU_I2SEXTCLK SPI0_MISO SATA0_PRESENT_ACTIVEn +15 - SPI0_MOSI - +16 - - - +17 - - - +18 - - - +19 - - - +20 - - - +21 - - - +22 - - - +23 AU_I2SMCLK - - +24 AU_I2SLRCLK - - +25 AU_I2SDO_SPDIFO - - +26 AU_I2SBCLK - - +27 SPI0_CSn[4] - - +28 SPI0_CSn[5] PCIe2_CLKREQ PTP_PULSE +29 SPI0_CSn[6] PCIe1_CLKREQ PTP_CLK +30 SPI0_CSn[7] PCIe0_CLKREQ PTP_PCLK_OUT +31 - PCIe_RSTOUTn - +32 AU_I2SEXTCLK AU_I2SDI GE_MDIO +33 AU_I2SMCLK SDIO_BUS_PWR - +34 AU_I2SLRCLK SDIO_WR_PROTECT GE_MDC +35 AU_I2SDO_SPDIFO SDIO_CARD_DETECT XG_MDIO +36 AU_I2SBCLK SATA0_PRESENT_ACTIVEn XG_MDC +37 MSS_TWSI_SCK SATA1_PRESENT_ACTIVEn GE_MDC +38 MSS_TWSI_SDA SATA0_PRESENT_ACTIVEn GE_MDIO +39 SPI0_CSn[1] - - +40 PTP_PCLK_OUT SPI0_CLK UART1_TXD +41 PTP_PULSE SPI0_MOSI UART1_RXD +42 MSS_UART_TXD SPI0_MISO UART1_CTS +43 MSS_UART_RXD SPI0_CSn[0] UART1_RTS +44 - - UART0_RTS +45 - - UART0_TXD +46 - - UART1_RTS +47 SPI1_CLK - UART1_TXD +48 SPI1_MOSI - - +49 SPI1_MISO - UART1_RXD +50 SPI1_CSn[0] UART2_TXD UART0_RXD +51 SPI1_CSn[1] UART2_RXD UART0_CTS +52 SPI1_CSn[2] - UART1_CTS +53 SPI1_CSn[3] - UART1_RXD +54 - - - +55 - - - +56 AU_I2SDO_SPDIFO SPI0_CLK UART1_RXD +57 AU_I2SBCLK SPI0_MOSI UART1_TXD +58 AU_I2SDI SPI0_MISO UART1_CTS +59 AU_I2SLRCLK SPI0_CSn[0] UART0_CTS +60 AU_I2SMCLK SPI0_CSn[1] UART0_RTS +61 AU_I2SEXTCLK SPI0_CSn[2] UART0_TXD +62 SATA1_PRESENT_ACTIVEn SPI0_CSn[3] UART0_RXD + +------------------------------------------------------------------------------- +MPP# 0x8 0x9 0xA +------------------------------------------------------------------------------- +0 UART0_RXD SATA0_PRESENT_ACTIVEn GE_MDIO +1 UART0_TXD SATA1_PRESENT_ACTIVEn GE_MDC +2 UART1_RXD SATA0_PRESENT_ACTIVEn XG_MDC +3 UART1_TXD SATA1_PRESENT_ACTIVEn XG_MDIO +4 UART3_RXD - GE_MDC +5 UART3_TXD - GE_MDIO +6 UART0_RXD PTP_PULSE - +7 UART0_TXD PTP_CLK - +8 UART2_RXD PTP_PCLK_OUT SYNCE1_CLK +9 - - SYNCE2_CLK +10 - - - +11 UART2_TXD SATA0_PRESENT_ACTIVEn - +12 - - - +13 MSS_SPI_MISO - - +14 MSS_SPI_CSn - - +15 MSS_SPI_MOSI - - +16 MSS_SPI_CLK - - +17 - - - +18 - - - +19 - - - +20 - - - +21 - - - +22 - - - +23 - - - +24 - - - +25 - - - +26 - - - +27 GE_MDIO SATA0_PRESENT_ACTIVEn UART0_RTS +28 GE_MDC SATA1_PRESENT_ACTIVEn UART0_CTS +29 MSS_TWSI_SDA SATA0_PRESENT_ACTIVEn UART0_RXD +30 MSS_TWSI_SCK SATA1_PRESENT_ACTIVEn UART0_TXD +31 GE_MDC - - +32 SDIO_V18_EN PCIe1_CLKREQ MSS_GPIO[0] +33 XG_MDIO PCIe2_CLKREQ MSS_GPIO[1] +34 - PCIe0_CLKREQ MSS_GPIO[2] +35 GE_MDIO PCIe_RSTOUTn MSS_GPIO[3] +36 GE_MDC PCIe2_CLKREQ MSS_GPIO[5] +37 XG_MDC PCIe1_CLKREQ MSS_GPIO[6] +38 XG_MDIO AU_I2SEXTCLK MSS_GPIO[7] +39 SATA1_PRESENT_ACTIVEn MSS_GPIO[0] +40 GE_MDIO SATA0_PRESENT_ACTIVEn MSS_GPIO[1] +41 GE_MDC SATA1_PRESENT_ACTIVEn MSS_GPIO[2] +42 XG_MDC SATA0_PRESENT_ACTIVEn MSS_GPIO[4] +43 XG_MDIO SATA1_PRESENT_ACTIVEn MSS_GPIO[5] +44 - - - +45 - PCIe_RSTOUTn - +46 - - - +47 GE_MDC CLKOUT - +48 XG_MDC - - +49 GE_MDIO PCIe0_CLKREQ SDIO_V18_EN +50 XG_MDIO - SDIO_PWR1[1] +51 - - SDIO_PWR1[0] +52 LED_CLK PCIe_RSTOUTn PCIe0_CLKREQ +53 LED_STB - - +54 LED_DATA - SDIO_HW_RST +55 - - SDIO_LED +56 - SATA1_PRESENT_ACTIVEn - +57 - SATA0_PRESENT_ACTIVEn - +58 LED_CLK - - +59 LED_STB UART1_TXD - +60 LED_DATA UART1_RXD - +61 UART2_TXD SATA1_PRESENT_ACTIVEn GE_MDIO +62 UART2_RXD SATA0_PRESENT_ACTIVEn GE_MDC + +------------------------------------------------------------------------------- +MPP# 0xB 0xD 0xE +------------------------------------------------------------------------------- +0 - - - +1 - - - +2 - - - +3 - - - +4 - - - +5 - - - +6 - - - +7 - - - +8 - - - +9 - - - +10 - - - +11 - CLKOUT_MPP_11 - +12 - - - +13 - - - +14 - - - +15 PTP_PULSE_CP2CP SAR_IN[5] - +16 - SAR_IN[3] - +17 - SAR_IN[6] - +18 PTP_CLK_CP2CP SAR_IN[11] - +19 WAKEUP_OUT_CP2CP SAR_IN[7] - +20 - SAR_IN[9] - +21 SEI_IN_CP2CP SAR_IN[8] - +22 WAKEUP_IN_CP2CP SAR_IN[10] - +23 LINK_RD_IN_CP2CP SAR_IN[4] - +24 - - - +25 - CLKOUT_MPP_25 - +26 - SAR_IN[0] - +27 REI_IN_CP2CP SAR_IN[1] - +28 LED_DATA SAR_IN[2] - +29 LED_STB AVS_FB_IN_CP2CP - +30 LED_CLK SAR_IN[13] - +31 - - - +32 - SAR_CP2CP_OUT[0] - +33 - SAR_CP2CP_OUT[1] - +34 - SAR_CP2CP_OUT[2] - +35 - SAR_CP2CP_OUT[3] - +36 - CLKIN - +37 LINK_RD_OUT_CP2CP SAR_CP2CP_OUT[4] - +38 PTP_PULSE_CP2CP SAR_CP2CP_OUT[5] - +39 - AVS_FB_OUT_CP2CP - +40 - - - +41 REI_OUT_CP2CP - - +42 - SAR_CP2CP_OUT[9] - +43 WAKEUP_OUT_CP2CP SAR_CP2CP_OUT[10] - +44 PTP_CLK_CP2CP SAR_CP2CP_OUT[11] - +45 - SAR_CP2CP_OUT[6] - +46 - SAR_CP2CP_OUT[13] - +47 - - - +48 WAKEUP_IN_CP2CP SAR_CP2CP_OUT[7] - +49 SEI_OUT_CP2CP SAR_CP2CP_OUT[8] - +50 - - - +51 - - - +52 - - - +53 SDIO_LED - - +54 SDIO_WR_PROTECT - - +55 SDIO_CARD_DETECT - - +56 - - SDIO0_CLK +57 - - SDIO0_CMD +58 - - SDIO0_D[0] +59 - - SDIO0_D[1] +60 - - SDIO0_D[2] +61 - - SDIO0_D[3] +62 - - - diff --git a/roms/u-boot/doc/device-tree-bindings/pinctrl/marvell,mvebu-pinctrl.txt b/roms/u-boot/doc/device-tree-bindings/pinctrl/marvell,mvebu-pinctrl.txt new file mode 100644 index 000000000..1fc1bc664 --- /dev/null +++ b/roms/u-boot/doc/device-tree-bindings/pinctrl/marvell,mvebu-pinctrl.txt @@ -0,0 +1,113 @@ +The pinctrl driver enables Marvell Armada 8K SoCs to configure the multi-purpose +pins (mpp) to a specific function. +A Marvell SoC pin configuration node is a node of a group of pins which can +be used for a specific device or function. Each node requires one or more +mpp pins or group of pins and a mpp function common to all pins. + +Required properties for the pinctrl driver: +- compatible: "marvell,mvebu-pinctrl", + "marvell,ap806-pinctrl", + "marvell,armada-7k-pinctrl", + "marvell,armada-8k-cpm-pinctrl", + "marvell,armada-8k-cps-pinctrl" +- bank-name: A string defining the pinc controller bank name +- reg: A pair of values defining the pin controller base address + and the address space +- pin-count: Numeric value defining the amount of multi purpose pins + included in this bank +- max-func: Numeric value defining the maximum function value for + pins in this bank +- pin-func: Array of pin function values for every pin in the bank. + When the function value for a specific pin equal 0xFF, + the pin configuration is skipped and a default function + value is used for this pin. + +The A8K is a hybrid SoC that contains several silicon dies interconnected in +a single package. Each such die may have a separate pin controller. + +Example: +/ { + ap806 { + config-space { + pinctl: pinctl@6F4000 { + compatible = "marvell,mvebu-pinctrl", + "marvell,ap806-pinctrl"; + bank-name ="apn-806"; + reg = <0x6F4000 0x10>; + pin-count = <20>; + max-func = <3>; + /* MPP Bus: + * SPI0 [0-3] + * I2C0 [4-5] + * UART0 [11,19] + */ + /* 0 1 2 3 4 5 6 7 8 9 */ + pin-func = < 3 3 3 3 3 3 0 0 0 0 + 0 3 0 0 0 0 0 0 0 3>; + }; + }; + }; + + cp110-master { + config-space { + cpm_pinctl: pinctl@44000 { + compatible = "marvell,mvebu-pinctrl", + "marvell,armada-7k-pinctrl", + "marvell,armada-8k-cpm-pinctrl"; + bank-name ="cp0-110"; + reg = <0x440000 0x20>; + pin-count = <63>; + max-func = <0xf>; + /* MPP Bus: + * [0-31] = 0xff: Keep default CP0_shared_pins: + * [11] CLKOUT_MPP_11 (out) + * [23] LINK_RD_IN_CP2CP (in) + * [25] CLKOUT_MPP_25 (out) + * [29] AVS_FB_IN_CP2CP (in) + * [32,34] SMI + * [31] GPIO: push button/Wake + * [35-36] GPIO + * [37-38] I2C + * [40-41] SATA[0/1]_PRESENT_ACTIVEn + * [42-43] XSMI + * [44-55] RGMII1 + * [56-62] SD + */ + /* 0 1 2 3 4 5 6 7 8 9 */ + pin-func = < 0xff 0xff 0xff 0xff 0xff 0xff 0xff 0xff 0xff 0xff + 0xff 0xff 0xff 0xff 0xff 0xff 0xff 0xff 0xff 0xff + 0xff 0xff 0xff 0xff 0xff 0xff 0xff 0xff 0xff 0xff + 0xff 0 7 0 7 0 0 2 2 0 + 0 0 8 8 1 1 1 1 1 1 + 1 1 1 1 1 1 0xE 0xE 0xE 0xE + 0xE 0xE 0xE>; + }; + }; + }; + + cp110-slave { + config-space { + cps_pinctl: pinctl@44000 { + compatible = "marvell,mvebu-pinctrl", + "marvell,armada-8k-cps-pinctrl"; + bank-name ="cp1-110"; + reg = <0x440000 0x20>; + pin-count = <63>; + max-func = <0xf>; + /* MPP Bus: + * [0-11] RGMII0 + * [27,31] GE_MDIO/MDC + * [32-62] = 0xff: Keep default CP1_shared_pins: + */ + /* 0 1 2 3 4 5 6 7 8 9 */ + pin-func = < 0x3 0x3 0x3 0x3 0x3 0x3 0x3 0x3 0x3 0x3 + 0x3 0x3 0xff 0xff 0xff 0xff 0xff 0xff 0xff 0xff + 0xff 0xff 0xff 0xff 0xff 0xff 0xff 0x8 0xff 0xff + 0xff 0x8 0xff 0xff 0xff 0xff 0xff 0xff 0xff 0xff + 0xff 0xff 0xff 0xff 0xff 0xff 0xff 0xff 0xff 0xff + 0xff 0xff 0xff 0xff 0xff 0xff 0xff 0xff 0xff 0xff + 0xff 0xff 0xff>; + }; + }; + }; +} diff --git a/roms/u-boot/doc/device-tree-bindings/pinctrl/nexell,s5pxx18-pinctrl.txt b/roms/u-boot/doc/device-tree-bindings/pinctrl/nexell,s5pxx18-pinctrl.txt new file mode 100644 index 000000000..115ab53a4 --- /dev/null +++ b/roms/u-boot/doc/device-tree-bindings/pinctrl/nexell,s5pxx18-pinctrl.txt @@ -0,0 +1,78 @@ +Binding for Nexell s5pxx18 pin cotroller +======================================== + +Nexell's ARM bases SoC's integrates a GPIO and Pin mux/config hardware +controller. It controls the input/output settings on the available pads/pins +and also provides ability to multiplex and configure the output of various +on-chip controllers onto these pads. + +Please refer to pinctrl-bindings.txt in this directory for details of the +common pinctrl bindings used by client devices, including the meaning of the +phrase "pin configuration node". + + +Required properties: + - compatible: "nexell,s5pxx18-pinctrl" + - reg: should be register base and length as documented in the datasheet + - interrupts: interrupt specifier for the controller over gpio and alive pins + +Example: +pinctrl_0: pinctrl@c0010000 { + compatible = "nexell,s5pxx18-pinctrl"; + reg = <0xc0010000 0xf000>; + u-boot,dm-pre-reloc; +}; + +Nexell's pin configuration nodes act as a container for an arbitrary number of +subnodes. Each of these subnodes represents some desired configuration for a +pin, a group, or a list of pins or groups. This configuration can include the +mux function to select on those pin(s)/group(s), and various pin configuration +parameters. + + Child nodes must be set at least one of the following settings: + - pins = Select pins for using this function. + - pin-function = Select the function for use in a selected pin. + - pin-pull = Pull up/down configuration. + - pin-strength = Drive strength configuration. + + Valid values for nexell,pins are: + "gpioX-N" : X in {A,B,C,D,E}, N in {0-31} + Valid values for nexell,pin-function are: + "N" : N in {0-3}. + This setting means that the value is different for each pin. + Please refer to datasheet. + Valid values for nexell,pin-pull are: + "N" : 0 - Down, 1 - Up, 2 - Off + Valid values for nexell,pin-strength are: + "N" : 0,1,2,3 + + +Example: + - pin settings + mmc0_clk: mmc0-clk { + pins = "gpioa-29"; + pin-function = <1>; + pin-pull = <2>; + pin-strength = <2>; + }; + + mmc0_cmd: mmc0-cmd { + pins = "gpioa-31"; + pin-function = <1>; + pin-pull = <2>; + pin-strength = <1>; + }; + + mmc0_bus4: mmc0-bus-width4 { + pins = "gpiob-1, gpiob-3, gpiob-5, gpiob-7"; + pin-function = <1>; + pin-pull = <2>; + pin-strength = <1>; + }; + + - used by client devices + mmc0:mmc@... { + pinctrl-names = "default"; + pinctrl-0 = <&mmc0_clk>, <&mmc0_cmd>, <&mmc0_bus4>; + ... + }; diff --git a/roms/u-boot/doc/device-tree-bindings/pinctrl/pinctrl-bindings.txt b/roms/u-boot/doc/device-tree-bindings/pinctrl/pinctrl-bindings.txt new file mode 100644 index 000000000..603796f16 --- /dev/null +++ b/roms/u-boot/doc/device-tree-bindings/pinctrl/pinctrl-bindings.txt @@ -0,0 +1,289 @@ +== Introduction == + +Hardware modules that control pin multiplexing or configuration parameters +such as pull-up/down, tri-state, drive-strength etc are designated as pin +controllers. Each pin controller must be represented as a node in device tree, +just like any other hardware module. + +Hardware modules whose signals are affected by pin configuration are +designated client devices. Again, each client device must be represented as a +node in device tree, just like any other hardware module. + +For a client device to operate correctly, certain pin controllers must +set up certain specific pin configurations. Some client devices need a +single static pin configuration, e.g. set up during initialization. Others +need to reconfigure pins at run-time, for example to tri-state pins when the +device is inactive. Hence, each client device can define a set of named +states. The number and names of those states is defined by the client device's +own binding. + +The common pinctrl bindings defined in this file provide an infrastructure +for client device device tree nodes to map those state names to the pin +configuration used by those states. + +Note that pin controllers themselves may also be client devices of themselves. +For example, a pin controller may set up its own "active" state when the +driver loads. This would allow representing a board's static pin configuration +in a single place, rather than splitting it across multiple client device +nodes. The decision to do this or not somewhat rests with the author of +individual board device tree files, and any requirements imposed by the +bindings for the individual client devices in use by that board, i.e. whether +they require certain specific named states for dynamic pin configuration. + +== Pinctrl client devices == + +For each client device individually, every pin state is assigned an integer +ID. These numbers start at 0, and are contiguous. For each state ID, a unique +property exists to define the pin configuration. Each state may also be +assigned a name. When names are used, another property exists to map from +those names to the integer IDs. + +Each client device's own binding determines the set of states that must be +defined in its device tree node, and whether to define the set of state +IDs that must be provided, or whether to define the set of state names that +must be provided. + +Required properties: +pinctrl-0: List of phandles, each pointing at a pin configuration + node. These referenced pin configuration nodes must be child + nodes of the pin controller that they configure. Multiple + entries may exist in this list so that multiple pin + controllers may be configured, or so that a state may be built + from multiple nodes for a single pin controller, each + contributing part of the overall configuration. See the next + section of this document for details of the format of these + pin configuration nodes. + + In some cases, it may be useful to define a state, but for it + to be empty. This may be required when a common IP block is + used in an SoC either without a pin controller, or where the + pin controller does not affect the HW module in question. If + the binding for that IP block requires certain pin states to + exist, they must still be defined, but may be left empty. + +Optional properties: +pinctrl-1: List of phandles, each pointing at a pin configuration + node within a pin controller. +... +pinctrl-n: List of phandles, each pointing at a pin configuration + node within a pin controller. +pinctrl-names: The list of names to assign states. List entry 0 defines the + name for integer state ID 0, list entry 1 for state ID 1, and + so on. + +For example: + + /* For a client device requiring named states */ + device { + pinctrl-names = "active", "idle"; + pinctrl-0 = <&state_0_node_a>; + pinctrl-1 = <&state_1_node_a &state_1_node_b>; + }; + + /* For the same device if using state IDs */ + device { + pinctrl-0 = <&state_0_node_a>; + pinctrl-1 = <&state_1_node_a &state_1_node_b>; + }; + + /* + * For an IP block whose binding supports pin configuration, + * but in use on an SoC that doesn't have any pin control hardware + */ + device { + pinctrl-names = "active", "idle"; + pinctrl-0 = <>; + pinctrl-1 = <>; + }; + +== Pin controller devices == + +Pin controller devices should contain the pin configuration nodes that client +devices reference. + +For example: + + pincontroller { + ... /* Standard DT properties for the device itself elided */ + + state_0_node_a { + ... + }; + state_1_node_a { + ... + }; + state_1_node_b { + ... + }; + } + +The contents of each of those pin configuration child nodes is defined +entirely by the binding for the individual pin controller device. There +exists no common standard for this content. The pinctrl framework only +provides generic helper bindings that the pin controller driver can use. + +The pin configuration nodes need not be direct children of the pin controller +device; they may be grandchildren, for example. Whether this is legal, and +whether there is any interaction between the child and intermediate parent +nodes, is again defined entirely by the binding for the individual pin +controller device. + +== Generic pin multiplexing node content == + +pin multiplexing nodes: + +function - the mux function to select +groups - the list of groups to select with this function + (either this or "pins" must be specified) +pins - the list of pins to select with this function (either + this or "groups" must be specified) + +Example: + +state_0_node_a { + uart0 { + function = "uart0"; + groups = "u0rxtx", "u0rtscts"; + }; +}; +state_1_node_a { + spi0 { + function = "spi0"; + groups = "spi0pins"; + }; +}; +state_2_node_a { + function = "i2c0"; + pins = "mfio29", "mfio30"; +}; + +For hardware where pin multiplexing configurations have to be specified for +each single pin the number of required sub-nodes containing "pin" and +"function" properties can quickly escalate and become hard to write and +maintain. + +For cases like this, the pin controller driver may use the pinmux helper +property, where the pin identifier is provided with mux configuration settings +in a pinmux group. A pinmux group consists of the pin identifier and mux +settings represented as a single integer or an array of integers. + +The pinmux property accepts an array of pinmux groups, each of them describing +a single pin multiplexing configuration. + +pincontroller { + state_0_node_a { + pinmux = <PINMUX_GROUP>, <PINMUX_GROUP>, ...; + }; +}; + +Each individual pin controller driver bindings documentation shall specify +how pin IDs and pin multiplexing configuration are defined and assembled +together in a pinmux group. + +== Generic pin configuration node content == + +Many data items that are represented in a pin configuration node are common +and generic. Pin control bindings should use the properties defined below +where they are applicable; not all of these properties are relevant or useful +for all hardware or binding structures. Each individual binding document +should state which of these generic properties, if any, are used, and the +structure of the DT nodes that contain these properties. + +Supported generic properties are: + +pins - the list of pins that properties in the node + apply to (either this, "group" or "pinmux" has to be + specified) +group - the group to apply the properties to, if the driver + supports configuration of whole groups rather than + individual pins (either this, "pins" or "pinmux" has + to be specified) +pinmux - the list of numeric pin ids and their mux settings + that properties in the node apply to (either this, + "pins" or "groups" have to be specified) +bias-disable - disable any pin bias +bias-high-impedance - high impedance mode ("third-state", "floating") +bias-bus-hold - latch weakly +bias-pull-up - pull up the pin +bias-pull-down - pull down the pin +bias-pull-pin-default - use pin-default pull state +drive-push-pull - drive actively high and low +drive-open-drain - drive with open drain +drive-open-source - drive with open source +drive-strength - sink or source at most X mA +drive-strength-microamp - sink or source at most X uA +input-enable - enable input on pin (no effect on output, such as + enabling an input buffer) +input-disable - disable input on pin (no effect on output, such as + disabling an input buffer) +input-schmitt-enable - enable schmitt-trigger mode +input-schmitt-disable - disable schmitt-trigger mode +input-debounce - debounce mode with debound time X +power-source - select between different power supplies +low-power-enable - enable low power mode +low-power-disable - disable low power mode +output-disable - disable output on a pin (such as disable an output + buffer) +output-enable - enable output on a pin without actively driving it + (such as enabling an output buffer) +output-low - set the pin to output mode with low level +output-high - set the pin to output mode with high level +sleep-hardware-state - indicate this is sleep related state which will be programmed + into the registers for the sleep state. +slew-rate - set the slew rate +skew-delay - this affects the expected clock skew on input pins + and the delay before latching a value to an output + pin. Typically indicates how many double-inverters are + used to delay the signal. + +For example: + +state_0_node_a { + cts_rxd { + pins = "GPIO0_AJ5", "GPIO2_AH4"; /* CTS+RXD */ + bias-pull-up; + }; +}; +state_1_node_a { + rts_txd { + pins = "GPIO1_AJ3", "GPIO3_AH3"; /* RTS+TXD */ + output-high; + }; +}; +state_2_node_a { + foo { + group = "foo-group"; + bias-pull-up; + }; +}; +state_3_node_a { + mux { + pinmux = <GPIOx_PINm_MUXn>, <GPIOx_PINj_MUXk)>; + input-enable; + }; +}; + +Some of the generic properties take arguments. For those that do, the +arguments are described below. + +- pins takes a list of pin names or IDs as a required argument. The specific + binding for the hardware defines: + - Whether the entries are integers or strings, and their meaning. + +- pinmux takes a list of pin IDs and mux settings as required argument. The + specific bindings for the hardware defines: + - How pin IDs and mux settings are defined and assembled together in a single + integer or an array of integers. + +- bias-pull-up, -down and -pin-default take as optional argument on hardware + supporting it the pull strength in Ohm. bias-disable will disable the pull. + +- drive-strength takes as argument the target strength in mA. + +- drive-strength-microamp takes as argument the target strength in uA. + +- input-debounce takes the debounce time in usec as argument + or 0 to disable debouncing + +More in-depth documentation on these parameters can be found in +<include/linux/pinctrl/pinconf-generic.h> diff --git a/roms/u-boot/doc/device-tree-bindings/pinctrl/rockchip,pinctrl.txt b/roms/u-boot/doc/device-tree-bindings/pinctrl/rockchip,pinctrl.txt new file mode 100644 index 000000000..388b21324 --- /dev/null +++ b/roms/u-boot/doc/device-tree-bindings/pinctrl/rockchip,pinctrl.txt @@ -0,0 +1,157 @@ +* Rockchip Pinmux Controller + +The Rockchip Pinmux Controller, enables the IC +to share one PAD to several functional blocks. The sharing is done by +multiplexing the PAD input/output signals. For each PAD there are several +muxing options with option 0 being the use as a GPIO. + +Please refer to pinctrl-bindings.txt in this directory for details of the +common pinctrl bindings used by client devices, including the meaning of the +phrase "pin configuration node". + +The Rockchip pin configuration node is a node of a group of pins which can be +used for a specific device or function. This node represents both mux and +config of the pins in that group. The 'pins' selects the function mode(also +named pin mode) this pin can work on and the 'config' configures various pad +settings such as pull-up, etc. + +The pins are grouped into up to 5 individual pin banks which need to be +defined as gpio sub-nodes of the pinmux controller. + +Required properties for iomux controller: + - compatible: one of "rockchip,rk2928-pinctrl", "rockchip,rk3066a-pinctrl" + "rockchip,rk3066b-pinctrl", "rockchip,rk3188-pinctrl" + "rockchip,rk3288-pinctrl" + - rockchip,grf: phandle referencing a syscon providing the + "general register files" + +Optional properties for iomux controller: + - rockchip,pmu: phandle referencing a syscon providing the pmu registers + as some SoCs carry parts of the iomux controller registers there. + Required for at least rk3188 and rk3288. + +Deprecated properties for iomux controller: + - reg: first element is the general register space of the iomux controller + It should be large enough to contain also separate pull registers. + second element is the separate pull register space of the rk3188. + Use rockchip,grf and rockchip,pmu described above instead. + +Required properties for gpio sub nodes: + - compatible: "rockchip,gpio-bank" + - reg: register of the gpio bank (different than the iomux registerset) + - interrupts: base interrupt of the gpio bank in the interrupt controller + - clocks: clock that drives this bank + - gpio-controller: identifies the node as a gpio controller and pin bank. + - #gpio-cells: number of cells in GPIO specifier. Since the generic GPIO + binding is used, the amount of cells must be specified as 2. See generic + GPIO binding documentation for description of particular cells. + - interrupt-controller: identifies the controller node as interrupt-parent. + - #interrupt-cells: the value of this property should be 2 and the interrupt + cells should use the standard two-cell scheme described in + bindings/interrupt-controller/interrupts.txt + +Deprecated properties for gpio sub nodes: + - compatible: "rockchip,rk3188-gpio-bank0" + - reg: second element: separate pull register for rk3188 bank0, use + rockchip,pmu described above instead + +Required properties for pin configuration node: + - rockchip,pins: 3 integers array, represents a group of pins mux and config + setting. The format is rockchip,pins = <PIN_BANK PIN_BANK_IDX MUX &phandle>. + The MUX 0 means gpio and MUX 1 to N mean the specific device function. + The phandle of a node containing the generic pinconfig options + to use, as described in pinctrl-bindings.txt in this directory. + +Examples: + +#include <dt-bindings/pinctrl/rockchip.h> + +... + +pinctrl@20008000 { + compatible = "rockchip,rk3066a-pinctrl"; + rockchip,grf = <&grf>; + + #address-cells = <1>; + #size-cells = <1>; + ranges; + + gpio0: gpio0@20034000 { + compatible = "rockchip,gpio-bank"; + reg = <0x20034000 0x100>; + interrupts = <GIC_SPI 54 IRQ_TYPE_LEVEL_HIGH>; + clocks = <&clk_gates8 9>; + + gpio-controller; + #gpio-cells = <2>; + + interrupt-controller; + #interrupt-cells = <2>; + }; + + ... + + pcfg_pull_default: pcfg_pull_default { + bias-pull-pin-default + }; + + uart2 { + uart2_xfer: uart2-xfer { + rockchip,pins = <RK_GPIO1 8 1 &pcfg_pull_default>, + <RK_GPIO1 9 1 &pcfg_pull_default>; + }; + }; +}; + +uart2: serial@20064000 { + compatible = "snps,dw-apb-uart"; + reg = <0x20064000 0x400>; + interrupts = <GIC_SPI 36 IRQ_TYPE_LEVEL_HIGH>; + reg-shift = <2>; + reg-io-width = <1>; + clocks = <&mux_uart2>; + status = "okay"; + + pinctrl-names = "default"; + pinctrl-0 = <&uart2_xfer>; +}; + +Example for rk3188: + + pinctrl@20008000 { + compatible = "rockchip,rk3188-pinctrl"; + rockchip,grf = <&grf>; + rockchip,pmu = <&pmu>; + #address-cells = <1>; + #size-cells = <1>; + ranges; + + gpio0: gpio0@0x2000a000 { + compatible = "rockchip,rk3188-gpio-bank0"; + reg = <0x2000a000 0x100>; + interrupts = <GIC_SPI 54 IRQ_TYPE_LEVEL_HIGH>; + clocks = <&clk_gates8 9>; + + gpio-controller; + #gpio-cells = <2>; + + interrupt-controller; + #interrupt-cells = <2>; + }; + + gpio1: gpio1@0x2003c000 { + compatible = "rockchip,gpio-bank"; + reg = <0x2003c000 0x100>; + interrupts = <GIC_SPI 55 IRQ_TYPE_LEVEL_HIGH>; + clocks = <&clk_gates8 10>; + + gpio-controller; + #gpio-cells = <2>; + + interrupt-controller; + #interrupt-cells = <2>; + }; + + ... + + }; diff --git a/roms/u-boot/doc/device-tree-bindings/pinctrl/st,stm32-pinctrl.txt b/roms/u-boot/doc/device-tree-bindings/pinctrl/st,stm32-pinctrl.txt new file mode 100644 index 000000000..00169255e --- /dev/null +++ b/roms/u-boot/doc/device-tree-bindings/pinctrl/st,stm32-pinctrl.txt @@ -0,0 +1,208 @@ +* STM32 GPIO and Pin Mux/Config controller + +STMicroelectronics's STM32 MCUs intregrate a GPIO and Pin mux/config hardware +controller. It controls the input/output settings on the available pins and +also provides ability to multiplex and configure the output of various on-chip +controllers onto these pads. + +Pin controller node: +Required properies: + - compatible: value should be one of the following: + "st,stm32f429-pinctrl" + "st,stm32f469-pinctrl" + "st,stm32f746-pinctrl" + "st,stm32f769-pinctrl" + "st,stm32h743-pinctrl" + "st,stm32mp157-pinctrl" + "st,stm32mp157-z-pinctrl" + - #address-cells: The value of this property must be 1 + - #size-cells : The value of this property must be 1 + - ranges : defines mapping between pin controller node (parent) to + gpio-bank node (children). + - pins-are-numbered: Specify the subnodes are using numbered pinmux to + specify pins. + +GPIO controller/bank node: +Required properties: + - gpio-controller : Indicates this device is a GPIO controller + - #gpio-cells : Should be two. + The first cell is the pin number + The second one is the polarity: + - 0 for active high + - 1 for active low + - reg : The gpio address range, relative to the pinctrl range + - clocks : clock that drives this bank + - st,bank-name : Should be a name string for this bank as specified in + the datasheet + +Optional properties: + - reset: : Reference to the reset controller + - st,syscfg: Should be phandle/offset/mask. + -The phandle to the syscon node which includes IRQ mux selection register. + -The offset of the IRQ mux selection register + -The field mask of IRQ mux, needed if different of 0xf. + - gpio-ranges: Define a dedicated mapping between a pin-controller and + a gpio controller. Format is <&phandle a b c> with: + -(phandle): phandle of pin-controller. + -(a): gpio base offset in range. + -(b): pin base offset in range. + -(c): gpio count in range + This entry has to be used either if there are holes inside a bank: + GPIOB0/B1/B2/B14/B15 (see example 2) + or if banks are not contiguous: + GPIOA/B/C/E... + NOTE: If "gpio-ranges" is used for a gpio controller, all gpio-controller + have to use a "gpio-ranges" entry. + More details in Documentation/devicetree/bindings/gpio/gpio.txt. + - st,bank-ioport: should correspond to the EXTI IOport selection (EXTI line + used to select GPIOs as interrupts). + - hwlocks: reference to a phandle of a hardware spinlock provider node. + - st,package: Indicates the SOC package used. + More details in include/dt-bindings/pinctrl/stm32-pinfunc.h + +Example 1: +#include <dt-bindings/pinctrl/stm32f429-pinfunc.h> +... + + pin-controller { + #address-cells = <1>; + #size-cells = <1>; + compatible = "st,stm32f429-pinctrl"; + ranges = <0 0x40020000 0x3000>; + pins-are-numbered; + + gpioa: gpio@40020000 { + gpio-controller; + #gpio-cells = <2>; + reg = <0x0 0x400>; + resets = <&reset_ahb1 0>; + st,bank-name = "GPIOA"; + }; + ... + pin-functions nodes follow... + }; + +Example 2: +#include <dt-bindings/pinctrl/stm32f429-pinfunc.h> +... + + pinctrl: pin-controller { + #address-cells = <1>; + #size-cells = <1>; + compatible = "st,stm32f429-pinctrl"; + ranges = <0 0x40020000 0x3000>; + pins-are-numbered; + + gpioa: gpio@40020000 { + gpio-controller; + #gpio-cells = <2>; + reg = <0x0 0x400>; + resets = <&reset_ahb1 0>; + st,bank-name = "GPIOA"; + gpio-ranges = <&pinctrl 0 0 16>; + }; + + gpiob: gpio@40020400 { + gpio-controller; + #gpio-cells = <2>; + reg = <0x0 0x400>; + resets = <&reset_ahb1 0>; + st,bank-name = "GPIOB"; + ngpios = 4; + gpio-ranges = <&pinctrl 0 16 3>, + <&pinctrl 14 30 2>; + }; + + + ... + pin-functions nodes follow... + }; + + +Contents of function subnode node: +---------------------------------- +Subnode format +A pinctrl node should contain at least one subnode representing the +pinctrl group available on the machine. Each subnode will list the +pins it needs, and how they should be configured, with regard to muxer +configuration, pullups, drive, output high/low and output speed. + + node { + pinmux = <PIN_NUMBER_PINMUX>; + GENERIC_PINCONFIG; + }; + +Required properties: +- pinmux: integer array, represents gpio pin number and mux setting. + Supported pin number and mux varies for different SoCs, and are defined in + dt-bindings/pinctrl/<soc>-pinfunc.h directly. + These defines are calculated as: + ((port * 16 + line) << 8) | function + With: + - port: The gpio port index (PA = 0, PB = 1, ..., PK = 11) + - line: The line offset within the port (PA0 = 0, PA1 = 1, ..., PA15 = 15) + - function: The function number, can be: + * 0 : GPIO + * 1 : Alternate Function 0 + * 2 : Alternate Function 1 + * 3 : Alternate Function 2 + * ... + * 16 : Alternate Function 15 + * 17 : Analog + + To simplify the usage, macro is available to generate "pinmux" field. + This macro is available here: + - include/dt-bindings/pinctrl/stm32-pinfunc.h + + Some examples of using macro: + /* GPIO A9 set as alernate function 2 */ + ... { + pinmux = <STM32_PINMUX('A', 9, AF2)>; + }; + /* GPIO A9 set as GPIO */ + ... { + pinmux = <STM32_PINMUX('A', 9, GPIO)>; + }; + /* GPIO A9 set as analog */ + ... { + pinmux = <STM32_PINMUX('A', 9, ANALOG)>; + }; + +Optional properties: +- GENERIC_PINCONFIG: is the generic pinconfig options to use. + Available options are: + - bias-disable, + - bias-pull-down, + - bias-pull-up, + - drive-push-pull, + - drive-open-drain, + - output-low + - output-high + - slew-rate = <x>, with x being: + < 0 > : Low speed + < 1 > : Medium speed + < 2 > : Fast speed + < 3 > : High speed + +Example: + +pin-controller { +... + usart1_pins_a: usart1@0 { + pins1 { + pinmux = <STM32_PINMUX('A', 9, AF7)>; + bias-disable; + drive-push-pull; + slew-rate = <0>; + }; + pins2 { + pinmux = <STM32_PINMUX('A', 10, AF7)>; + bias-disable; + }; + }; +}; + +&usart1 { + pinctrl-0 = <&usart1_pins_a>; + pinctrl-names = "default"; +}; diff --git a/roms/u-boot/doc/device-tree-bindings/pmic/max77686.txt b/roms/u-boot/doc/device-tree-bindings/pmic/max77686.txt new file mode 100644 index 000000000..09aee647a --- /dev/null +++ b/roms/u-boot/doc/device-tree-bindings/pmic/max77686.txt @@ -0,0 +1,35 @@ +MAXIM, MAX77686 pmic + +This device uses two drivers: +- drivers/power/pmic/max77686.c (for parent device) +- drivers/power/regulator/max77686.c (for child regulators) + +This file describes the binding info for the PMIC driver. + +To bind the regulators, please read the additional binding info: +- doc/device-tree-bindings/regulator/max77686.txt + +Required properties: +- compatible: "maxim,max77686" +- reg = 0x9 + +With those two properties, the pmic device can be used for read/write only. +To bind each regulator, the optional regulators subnode should exists. + +Optional subnode: +- voltage-regulators: subnode list of each device's regulator + (see max77686.txt - regulator binding info) + +Example: + +max77686@09 { + compatible = "maxim,max77686"; + reg = <0x09>; + + voltage-regulators { + ldo1 { + ... + }; + ... + }; +}; diff --git a/roms/u-boot/doc/device-tree-bindings/pmic/pm8916.txt b/roms/u-boot/doc/device-tree-bindings/pmic/pm8916.txt new file mode 100644 index 000000000..15c598b8c --- /dev/null +++ b/roms/u-boot/doc/device-tree-bindings/pmic/pm8916.txt @@ -0,0 +1,18 @@ +Qualcomm pm8916 PMIC + +This PMIC is connected using SPMI bus so should be child of SPMI bus controller. + +Required properties: +- compatible: "qcom,spmi-pmic"; +- reg: SPMI Slave ID, size (ignored) +- #address-cells: 0x1 (peripheral ID) +- #size-cells: 0x1 (size of peripheral register space) + +Example: + +pm8916@0 { + compatible = "qcom,spmi-pmic"; + reg = <0x0 0x1>; + #address-cells = <0x1>; + #size-cells = <0x1>; +}; diff --git a/roms/u-boot/doc/device-tree-bindings/pmic/rn5t567.txt b/roms/u-boot/doc/device-tree-bindings/pmic/rn5t567.txt new file mode 100644 index 000000000..e9e688537 --- /dev/null +++ b/roms/u-boot/doc/device-tree-bindings/pmic/rn5t567.txt @@ -0,0 +1,17 @@ +Ricoh RN5T567 PMIC + +This file describes the binding info for the PMIC driver. + +Required properties: +- compatible: "ricoh,rn5t567" +- reg: depending on strapping, e.g. 0x33 + +With those two properties, the PMIC device can be used to read/write +registers. + +Example: + +rn5t567@33 { + compatible = "ricoh,rn5t567"; + reg = <0x33>; +}; diff --git a/roms/u-boot/doc/device-tree-bindings/pmic/s2mps11.txt b/roms/u-boot/doc/device-tree-bindings/pmic/s2mps11.txt new file mode 100644 index 000000000..422f14f13 --- /dev/null +++ b/roms/u-boot/doc/device-tree-bindings/pmic/s2mps11.txt @@ -0,0 +1,17 @@ +SAMSUNG, S2MPS11 PMIC + +This file describes the binding info for the PMIC driver: +- drivers/power/pmic/s2mps11.c + +Required properties: +- compatible: "samsung,s2mps11-pmic" +- reg = 0x66 + +With those two properties, the pmic device can be used for read/write only. + +Example: + +s2mps11@66 { + compatible = "samsung,s2mps11-pmic"; + reg = <0x66>; +}; diff --git a/roms/u-boot/doc/device-tree-bindings/pmic/sandbox.txt b/roms/u-boot/doc/device-tree-bindings/pmic/sandbox.txt new file mode 100644 index 000000000..d84c97717 --- /dev/null +++ b/roms/u-boot/doc/device-tree-bindings/pmic/sandbox.txt @@ -0,0 +1,35 @@ +Sandbox pmic + +This device uses two drivers: +- drivers/power/pmic/sandbox.c (for parent device) +- drivers/power/regulator/sandbox.c (for child regulators) + +This file describes the binding info for the PMIC driver. + +To bind the regulators, please read the regulator binding info: +- doc/device-tree-bindings/regulator/sandbox.txt + +Required PMIC node properties: +- compatible: "sandbox,pmic" +- reg = 0x40 + +Required PMIC's "emul" subnode, with property: +- compatible: "sandbox,i2c-pmic" + +With the above properties, the pmic device can be used for read/write only. +To bind each regulator, the optional regulator subnodes should exists. + +Optional subnodes: +- ldo/buck subnodes of each device's regulator (see regulator binding info) + +Example: + +sandbox_pmic { + compatible = "sandbox,pmic"; + reg = <0x40>; + + /* Mandatory for I/O */ + emul { + compatible = "sandbox,i2c-pmic"; + }; +}; diff --git a/roms/u-boot/doc/device-tree-bindings/power/ti,sci-pm-domain.txt b/roms/u-boot/doc/device-tree-bindings/power/ti,sci-pm-domain.txt new file mode 100644 index 000000000..72d9fbc83 --- /dev/null +++ b/roms/u-boot/doc/device-tree-bindings/power/ti,sci-pm-domain.txt @@ -0,0 +1,59 @@ +Texas Instruments TI SCI Generic Power Domain +============================================= + +Some TI SoCs contain a system controller (like the SYSFW, etc...) that is +responsible for controlling the state of the IPs that are present. +Communication between the host processor running an OS and the system +controller happens through a protocol known as TI SCI [1]. + +[1] http://processors.wiki.ti.com/index.php/TISCI + +PM Domain Node +============== +The PM domain node represents the global PM domain managed by the SYSFW. Because +this relies on the TI SCI protocol to communicate with the SYSFW it must be a +child of the sysfw node. + +Required Properties: +-------------------- +- compatible: Must be "ti,sci-pm-domain" +- #power-domain-cells: Can be one of the following: + 1: Containing the device id of each node + 2: First entry should be device id + Second entry should be one of the floowing: + TI_SCI_PD_EXCLUSIVE: To allow device to be + exclusively controlled by + the requesting hosts. + TI_SCI_PD_SHARED: To allow device to be shared + by multiple hosts. + +Example (AM65x): +---------------- + sysfw: sysfw { + compatible = "ti,am654-system-controller"; + ... + k3_pds: power-controller { + compatible = "ti,sci-pm-domain"; + #power-domain-cells = <1>; + }; + }; + +PM Domain Consumers +=================== +Hardware blocks belonging to a PM domain should contain a "power-domains" +property that is a phandle pointing to the corresponding PM domain node +along with an index representing the device id to be passed to the PMMC +for device control. + +Required Properties: +-------------------- +- power-domains: phandle pointing to the corresponding PM domain node + and an ID representing the device. + +Example (AM65x): +---------------- + uart2: serial@02800000 { + compatible = "ti,omap4-uart"; + ... + power-domains = <&k3_pds 0x3f>; + }; diff --git a/roms/u-boot/doc/device-tree-bindings/power/tps65090.txt b/roms/u-boot/doc/device-tree-bindings/power/tps65090.txt new file mode 100644 index 000000000..8e5e0d391 --- /dev/null +++ b/roms/u-boot/doc/device-tree-bindings/power/tps65090.txt @@ -0,0 +1,17 @@ +TPS65090 Frontend PMU with Switchmode Charger + +Required Properties: +-compatible: "ti,tps65090-charger" + +Optional Properties: +-ti,enable-low-current-chrg: Enables charging when a low current is detected + while the default logic is to stop charging. + +This node is a subnode of the tps65090 PMIC. + +Example: + + tps65090-charger { + compatible = "ti,tps65090-charger"; + ti,enable-low-current-chrg; + }; diff --git a/roms/u-boot/doc/device-tree-bindings/pwm/cros-ec-pwm.txt b/roms/u-boot/doc/device-tree-bindings/pwm/cros-ec-pwm.txt new file mode 100644 index 000000000..f198d0889 --- /dev/null +++ b/roms/u-boot/doc/device-tree-bindings/pwm/cros-ec-pwm.txt @@ -0,0 +1,23 @@ +PWM controlled by ChromeOS EC + +Google's ChromeOS EC PWM is a simple PWM attached to the Embedded Controller +(EC) and controlled via a host-command interface. + +An EC PWM node should be only found as a sub-node of the EC node (see +doc/device-tree-bindings/misc/cros-ec.txt). + +Required properties: +- compatible: Must contain "google,cros-ec-pwm" +- #pwm-cells: Should be 1. The cell specifies the PWM index. + +Example: + cros-ec@0 { + compatible = "google,cros-ec-spi"; + + ... + + cros_ec_pwm: ec-pwm { + compatible = "google,cros-ec-pwm"; + #pwm-cells = <1>; + }; + }; diff --git a/roms/u-boot/doc/device-tree-bindings/pwm/pwm-sifive.txt b/roms/u-boot/doc/device-tree-bindings/pwm/pwm-sifive.txt new file mode 100644 index 000000000..9a988372c --- /dev/null +++ b/roms/u-boot/doc/device-tree-bindings/pwm/pwm-sifive.txt @@ -0,0 +1,31 @@ +SiFive PWM controller + +Unlike most other PWM controllers, the SiFive PWM controller currently only +supports one period for all channels in the PWM. All PWMs need to run at +the same period. The period also has significant restrictions on the values +it can achieve, which the driver rounds to the nearest achievable period. +PWM RTL that corresponds to the IP block version numbers can be found +here: + +https://github.com/sifive/sifive-blocks/tree/master/src/main/scala/devices/pwm + +Required properties: +- compatible: Should be "sifive,<chip>-pwm" and "sifive,pwm<version>". + Supported compatible strings are: "sifive,fu540-c000-pwm" for the SiFive + PWM v0 as integrated onto the SiFive FU540 chip, and "sifive,pwm0" for the + SiFive PWM v0 IP block with no chip integration tweaks. +- reg: physical base address and length of the controller's registers +- clocks: Should contain a clock identifier for the PWM's parent clock. +- #pwm-cells: Should be 3. +- interrupts: one interrupt per PWM channel + +Examples: + +pwm: pwm@10020000 { + compatible = "sifive,fu540-c000-pwm", "sifive,pwm0"; + reg = <0x0 0x10020000 0x0 0x1000>; + clocks = <&tlclk>; + interrupt-parent = <&plic>; + interrupts = <42 43 44 45>; + #pwm-cells = <3>; +}; diff --git a/roms/u-boot/doc/device-tree-bindings/pwm/pwm.txt b/roms/u-boot/doc/device-tree-bindings/pwm/pwm.txt new file mode 100644 index 000000000..8556263b8 --- /dev/null +++ b/roms/u-boot/doc/device-tree-bindings/pwm/pwm.txt @@ -0,0 +1,69 @@ +Specifying PWM information for devices +====================================== + +1) PWM user nodes +----------------- + +PWM users should specify a list of PWM devices that they want to use +with a property containing a 'pwm-list': + + pwm-list ::= <single-pwm> [pwm-list] + single-pwm ::= <pwm-phandle> <pwm-specifier> + pwm-phandle : phandle to PWM controller node + pwm-specifier : array of #pwm-cells specifying the given PWM + (controller specific) + +PWM properties should be named "pwms". The exact meaning of each pwms +property must be documented in the device tree binding for each device. +An optional property "pwm-names" may contain a list of strings to label +each of the PWM devices listed in the "pwms" property. If no "pwm-names" +property is given, the name of the user node will be used as fallback. + +Drivers for devices that use more than a single PWM device can use the +"pwm-names" property to map the name of the PWM device requested by the +pwm_get() call to an index into the list given by the "pwms" property. + +The following example could be used to describe a PWM-based backlight +device: + + pwm: pwm { + #pwm-cells = <2>; + }; + + [...] + + bl: backlight { + pwms = <&pwm 0 5000000>; + pwm-names = "backlight"; + }; + +Note that in the example above, specifying the "pwm-names" is redundant +because the name "backlight" would be used as fallback anyway. + +pwm-specifier typically encodes the chip-relative PWM number and the PWM +period in nanoseconds. + +Optionally, the pwm-specifier can encode a number of flags (defined in +<dt-bindings/pwm/pwm.h>) in a third cell: +- PWM_POLARITY_INVERTED: invert the PWM signal polarity + +Example with optional PWM specifier for inverse polarity + + bl: backlight { + pwms = <&pwm 0 5000000 PWM_POLARITY_INVERTED>; + pwm-names = "backlight"; + }; + +2) PWM controller nodes +----------------------- + +PWM controller nodes must specify the number of cells used for the +specifier using the '#pwm-cells' property. + +An example PWM controller might look like this: + + pwm: pwm@7000a000 { + compatible = "nvidia,tegra20-pwm"; + reg = <0x7000a000 0x100>; + #pwm-cells = <2>; + }; diff --git a/roms/u-boot/doc/device-tree-bindings/pwm/tegra20-pwm.txt b/roms/u-boot/doc/device-tree-bindings/pwm/tegra20-pwm.txt new file mode 100644 index 000000000..01438ecd6 --- /dev/null +++ b/roms/u-boot/doc/device-tree-bindings/pwm/tegra20-pwm.txt @@ -0,0 +1,18 @@ +Tegra SoC PWFM controller + +Required properties: +- compatible: should be one of: + - "nvidia,tegra20-pwm" + - "nvidia,tegra30-pwm" +- reg: physical base address and length of the controller's registers +- #pwm-cells: On Tegra the number of cells used to specify a PWM is 2. The + first cell specifies the per-chip index of the PWM to use and the second + cell is the period in nanoseconds. + +Example: + + pwm: pwm@7000a000 { + compatible = "nvidia,tegra20-pwm"; + reg = <0x7000a000 0x100>; + #pwm-cells = <2>; + }; diff --git a/roms/u-boot/doc/device-tree-bindings/ram/fsl,mpc83xx-mem-controller.txt b/roms/u-boot/doc/device-tree-bindings/ram/fsl,mpc83xx-mem-controller.txt new file mode 100644 index 000000000..da01fe908 --- /dev/null +++ b/roms/u-boot/doc/device-tree-bindings/ram/fsl,mpc83xx-mem-controller.txt @@ -0,0 +1,314 @@ +MPC83xx RAM controller + +This driver supplies support for the embedded RAM controller on MCP83xx-series +SoCs. + +For static configuration mode, each controller node should have child nodes +describing the actual RAM modules installed. + +Controller node +=============== + +Required properties: +- compatible: Must be "fsl,mpc83xx-mem-controller" +- reg: The address of the RAM controller's register space +- #address-cells: Must be 2 +- #size-cells: Must be 1 +- driver_software_override: DDR driver software override is enabled (1) or + disabled (0) +- p_impedance_override: DDR driver software p-impedance override; possible + values: + * DSO_P_IMPEDANCE_HIGHEST_Z + * DSO_P_IMPEDANCE_MUCH_HIGHER_Z + * DSO_P_IMPEDANCE_HIGHER_Z + * DSO_P_IMPEDANCE_NOMINAL + * DSO_P_IMPEDANCE_LOWER_Z +- n_impedance_override: DDR driver software n-impedance override; possible + values: + * DSO_N_IMPEDANCE_HIGHEST_Z + * DSO_N_IMPEDANCE_MUCH_HIGHER_Z + * DSO_N_IMPEDANCE_HIGHER_Z + * DSO_N_IMPEDANCE_NOMINAL + * DSO_N_IMPEDANCE_LOWER_Z +- odt_termination_value: ODT termination value for I/Os; possible values: + * ODT_TERMINATION_75_OHM + * ODT_TERMINATION_150_OHM +- ddr_type: Selects voltage level for DDR pads; possible + values: + * DDR_TYPE_DDR2_1_8_VOLT + * DDR_TYPE_DDR1_2_5_VOLT +- mvref_sel: Determine where MVREF_SEL signal is generated; + possible values: + * MVREF_SEL_EXTERNAL + * MVREF_SEL_INTERNAL_GVDD +- m_odr: Disable memory transaction reordering; possible + values: + * M_ODR_ENABLE + * M_ODR_DISABLE +- clock_adjust: Clock adjust; possible values: + * CLOCK_ADJUST_025 + * CLOCK_ADJUST_05 + * CLOCK_ADJUST_075 + * CLOCK_ADJUST_1 +- ext_refresh_rec: Extended refresh recovery time; possible values: + 0, 16, 32, 48, 64, 80, 96, 112 +- read_to_write: Read-to-write turnaround; possible values: + 0, 1, 2, 3 +- write_to_read: Write-to-read turnaround; possible values: + 0, 1, 2, 3 +- read_to_read: Read-to-read turnaround; possible values: + 0, 1, 2, 3 +- write_to_write: Write-to-write turnaround; possible values: + 0, 1, 2, 3 +- active_powerdown_exit: Active powerdown exit timing; possible values: + 1, 2, 3, 4, 5, 6, 7 +- precharge_powerdown_exit: Precharge powerdown exit timing; possible values: + 1, 2, 3, 4, 5, 6, 7 +- odt_powerdown_exit: ODT powerdown exit timing; possible values: + 0, 1, 2, 3, 4, 5, 6, 7, 8, + 9, 10, 11, 12, 13, 14, 15 +- mode_reg_set_cycle: Mode register set cycle time; possible values: + 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15 +- precharge_to_activate: Precharge-to-acitvate interval; possible values: + 1, 2, 3, 4, 5, 6, 7 +- activate_to_precharge: Activate to precharge interval; possible values: + 4, 5, 6, 7, 8, 9, 10, 11, 12, + 13, 14, 15, 16, 17, 18, 19 +- activate_to_readwrite: Activate to read/write interval for SDRAM; + possible values: + 1, 2, 3, 4, 5, 6, 7 +- mcas_latency: MCAS latency from READ command; possible values: + * CASLAT_20 + * CASLAT_25 + * CASLAT_30 + * CASLAT_35 + * CASLAT_40 + * CASLAT_45 + * CASLAT_50 + * CASLAT_55 + * CASLAT_60 + * CASLAT_65 + * CASLAT_70 + * CASLAT_75 + * CASLAT_80 +- refresh_recovery: Refresh recovery time; possible values: + 8, 9, 10, 11, 12, 13, 14, 15, + 16, 17, 18, 19, 20, 21, 22, 23 +- last_data_to_precharge: Last data to precharge minimum interval; possible + values: + 1, 2, 3, 4, 5, 6, 7 +- activate_to_activate: Activate-to-activate interval; possible values: + 1, 2, 3, 4, 5, 6, 7 +- last_write_data_to_read: Last write data pair to read command issue + interval; possible values: + 1, 2, 3, 4, 5, 6, 7 +- additive_latency: Additive latency; possible values: + 0, 1, 2, 3, 4, 5 +- mcas_to_preamble_override: MCAS-to-preamble-override; possible values: + * READ_LAT + * READ_LAT_PLUS_1_4 + * READ_LAT_PLUS_1_2 + * READ_LAT_PLUS_3_4 + * READ_LAT_PLUS_1 + * READ_LAT_PLUS_5_4 + * READ_LAT_PLUS_3_2 + * READ_LAT_PLUS_7_4 + * READ_LAT_PLUS_2 + * READ_LAT_PLUS_9_4 + * READ_LAT_PLUS_5_2 + * READ_LAT_PLUS_11_4 + * READ_LAT_PLUS_3 + * READ_LAT_PLUS_13_4 + * READ_LAT_PLUS_7_2 + * READ_LAT_PLUS_15_4 + * READ_LAT_PLUS_4 + * READ_LAT_PLUS_17_4 + * READ_LAT_PLUS_9_2 + * READ_LAT_PLUS_19_4 +- write_latency: Write latency; possible values: + 1, 2, 3, 4, 5, 6, 7 +- read_to_precharge: Read to precharge; possible values: + 1, 2, 3, 4 +- write_cmd_to_write_data: Write command to write data strobe timing + adjustment; possible values: + * CLOCK_DELAY_0 + * CLOCK_DELAY_1_4 + * CLOCK_DELAY_1_2 + * CLOCK_DELAY_3_4 + * CLOCK_DELAY_1 + * CLOCK_DELAY_5_4 + * CLOCK_DELAY_3_2 +- minimum_cke_pulse_width: Minimum CKE pulse width; possible values: + 1, 2, 3, 4 +- four_activates_window: Window for four activates; possible values: + 1, 2, 3, 4 8, 9, 10, 11, 12, + 13, 14, 15, 16, 17, 18, 19 +- self_refresh: Self refresh (during sleep); possible values: + * SREN_DISABLE + * SREN_ENABLE +- ecc: Support for ECC; possible values: + * ECC_DISABLE + * ECC_ENABLE +- registered_dram: Support for registered DRAM; possible values: + * RD_DISABLE + * RD_ENABLE +- sdram_type: Type of SDRAM device to be used; possible values: + * TYPE_DDR1 + * TYPE_DDR2 +- dynamic_power_management: Dynamic power management mode; possible values: + * DYN_PWR_DISABLE + * DYN_PWR_ENABLE +- databus_width: DRAM data bus width; possible values + * DATA_BUS_WIDTH_16 + * DATA_BUS_WIDTH_32 +- nc_auto_precharge: Non-concurrent auto-precharge; possible values: + * NCAP_DISABLE + * NCAP_ENABLE +- timing_2t: 2T timing; possible values: + * TIMING_1T + * TIMING_2T +- bank_interleaving_ctrl: Bank (chip select) interleaving control; possible + values: + * INTERLEAVE_NONE + * INTERLEAVE_1_AND_2 +- precharge_bit_8: Precharge bin 8; possible values + * PRECHARGE_MA_10 + * PRECHARGE_MA_8 +- half_strength: Global half-strength override; possible values: + * STRENGTH_FULL + * STRENGTH_HALF +- bypass_initialization: Bypass initialization; possible values: + * INITIALIZATION_DONT_BYPASS + * INITIALIZATION_BYPASS +- force_self_refresh: Force self refresh; possible values: + * MODE_NORMAL + * MODE_REFRESH +- dll_reset: DLL reset; possible values: + * DLL_RESET_ENABLE + * DLL_RESET_DISABLE +- dqs_config: DQS configuration; possible values: + * DQS_TRUE +- odt_config: ODT configuration; possible values: + * ODT_ASSERT_NEVER + * ODT_ASSERT_WRITES + * ODT_ASSERT_READS + * ODT_ASSERT_ALWAYS +- posted_refreshes: Number of posted refreshes + 1, 2, 3, 4, 5, 6, 7, 8 +- sdmode: Initial value loaded into the DDR SDRAM mode + register +- esdmode: Initial value loaded into the DDR SDRAM extended + mode register +- esdmode2: Initial value loaded into the DDR SDRAM extended + mode 2 register +- esdmode3: Initial value loaded into the DDR SDRAM extended + mode 3 register +- refresh_interval: Refresh interval; possible values: + 0 - 65535 +- precharge_interval: Precharge interval; possible values: + 0 - 16383 + +RAM module node: +================ + +Required properties: +- reg: A triple <cs addr size>, which consists of: + * cs - the chipselect used to drive this RAM module + * addr - the address where this RAM module's memory is map + to in the global memory space + * size - the size of the RAM module's memory in bytes +- auto_precharge: Chip select auto-precharge; possible values: + * AUTO_PRECHARGE_ENABLE + * AUTO_PRECHARGE_DISABLE +- odt_rd_cfg: ODT for reads configuration; possible values: + * ODT_RD_NEVER + * ODT_RD_ONLY_CURRENT + * ODT_RD_ONLY_OTHER_CS + * ODT_RD_ONLY_OTHER_DIMM + * ODT_RD_ALL +- odt_wr_cfg: ODT for writes configuration; possible values: + * ODT_WR_NEVER + * ODT_WR_ONLY_CURRENT + * ODT_WR_ONLY_OTHER_CS + * ODT_WR_ONLY_OTHER_DIMM + * ODT_WR_ALL +- bank_bits: Number of bank bits for SDRAM on chip select; possible + values: + 2, 3 +- row_bits: Number of row bits for SDRAM on chip select; possible values: + 12, 13, 14 +- col_bits: Number of column bits for SDRAM on chip select; possible + values: + 8, 9, 10, 11 + +Example: + +memory@2000 { + #address-cells = <2>; + #size-cells = <1>; + compatible = "fsl,mpc83xx-mem-controller"; + reg = <0x2000 0x1000>; + device_type = "memory"; + u-boot,dm-pre-reloc; + + driver_software_override = <DSO_ENABLE>; + p_impedance_override = <DSO_P_IMPEDANCE_NOMINAL>; + n_impedance_override = <DSO_N_IMPEDANCE_NOMINAL>; + odt_termination_value = <ODT_TERMINATION_150_OHM>; + ddr_type = <DDR_TYPE_DDR2_1_8_VOLT>; + + clock_adjust = <CLOCK_ADJUST_05>; + + read_to_write = <0>; + write_to_read = <0>; + read_to_read = <0>; + write_to_write = <0>; + active_powerdown_exit = <2>; + precharge_powerdown_exit = <6>; + odt_powerdown_exit = <8>; + mode_reg_set_cycle = <2>; + + precharge_to_activate = <2>; + activate_to_precharge = <6>; + activate_to_readwrite = <2>; + mcas_latency = <CASLAT_40>; + refresh_recovery = <17>; + last_data_to_precharge = <2>; + activate_to_activate = <2>; + last_write_data_to_read = <2>; + + additive_latency = <0>; + mcas_to_preamble_override = <READ_LAT_PLUS_1_2>; + write_latency = <3>; + read_to_precharge = <2>; + write_cmd_to_write_data = <CLOCK_DELAY_1_2>; + minimum_cke_pulse_width = <3>; + four_activates_window = <5>; + + self_refresh = <SREN_ENABLE>; + sdram_type = <TYPE_DDR2>; + databus_width = <DATA_BUS_WIDTH_32>; + + force_self_refresh = <MODE_NORMAL>; + dll_reset = <DLL_RESET_ENABLE>; + dqs_config = <DQS_TRUE>; + odt_config = <ODT_ASSERT_READS>; + posted_refreshes = <1>; + + refresh_interval = <2084>; + precharge_interval = <256>; + + sdmode = <0x0242>; + esdmode = <0x0440>; + + ram@0 { + reg = <0x0 0x0 0x8000000>; + compatible = "nanya,nt5tu64m16hg"; + + odt_rd_cfg = <ODT_RD_NEVER>; + odt_wr_cfg = <ODT_WR_ONLY_CURRENT>; + bank_bits = <3>; + row_bits = <13>; + col_bits = <10>; + }; +}; diff --git a/roms/u-boot/doc/device-tree-bindings/regulator/fan53555.txt b/roms/u-boot/doc/device-tree-bindings/regulator/fan53555.txt new file mode 100644 index 000000000..b183738d6 --- /dev/null +++ b/roms/u-boot/doc/device-tree-bindings/regulator/fan53555.txt @@ -0,0 +1,23 @@ +Binding for Fairchild FAN53555 regulators + +Required properties: + - compatible: "fcs,fan53555" + - reg: I2C address + +Optional properties: + - fcs,suspend-voltage-selector: declare which of the two available + voltage selector registers should be used for the suspend + voltage. The other one is used for the runtime voltage setting + Possible values are either <0> or <1> + - vin-supply: regulator supplying the vin pin + +Example: + + regulator@40 { + compatible = "fcs,fan53555"; + regulator-name = "fan53555"; + regulator-min-microvolt = <1000000>; + regulator-max-microvolt = <1800000>; + vin-supply = <&parent_reg>; + fcs,suspend-voltage-selector = <1>; + }; diff --git a/roms/u-boot/doc/device-tree-bindings/regulator/fixed.txt b/roms/u-boot/doc/device-tree-bindings/regulator/fixed.txt new file mode 100644 index 000000000..453d2bef4 --- /dev/null +++ b/roms/u-boot/doc/device-tree-bindings/regulator/fixed.txt @@ -0,0 +1,44 @@ +Fixed Voltage regulator + +Binding: +The binding is done by the property "compatible" - this is different, than for +binding by the node prefix (doc/device-tree-bindings/regulator/regulator.txt). + +Required properties: +- compatible: "regulator-fixed" +- regulator-name: this is required by the regulator uclass + +Optional properties: +- gpio: GPIO to use for enable control +- startup-delay-us: startup time in microseconds +- u-boot,off-on-delay-us: off delay time in microseconds +- regulator constraints (binding info: regulator.txt) +- enable-active-high: Polarity of GPIO is Active high. If this property + is missing, the default assumed is Active low. + + +Other kernel-style properties, are currently not used. + +Note: +For the regulator constraints, driver expects that: +- regulator-min-microvolt is equal to regulator-max-microvolt +- regulator-min-microamp is equal to regulator-max-microamp + +Example: +fixed_regulator@0 { + /* Mandatory */ + compatible = "regulator-fixed"; + regulator-name = "LED_3.3V"; + + /* Optional: */ + gpio = <&gpc1 0 GPIO_ACTIVE_LOW>; + + /* Optional for regulator uclass */ + regulator-min-microvolt = <3300000>; + regulator-max-microvolt = <3300000>; + regulator-min-microamp = <15000>; + regulator-max-microamp = <15000>; + regulator-always-on; + regulator-boot-on; + enable-active-high; +}; diff --git a/roms/u-boot/doc/device-tree-bindings/regulator/fsl,anatop-regulator.txt b/roms/u-boot/doc/device-tree-bindings/regulator/fsl,anatop-regulator.txt new file mode 100644 index 000000000..2a60e4941 --- /dev/null +++ b/roms/u-boot/doc/device-tree-bindings/regulator/fsl,anatop-regulator.txt @@ -0,0 +1,45 @@ +ANATOP REGULATOR + +Anatop is an integrated regulator inside i.MX6 SoC. + +Required properties: +- compatible: Must be "fsl,anatop-regulator". +- regulator-name: Name of the regulator +- anatop-reg-offset: u32 value representing the anatop MFD register offset. +- anatop-vol-bit-shift: u32 value representing the bit shift for the register. +- anatop-vol-bit-width: u32 value representing the number of bits used in the + register. +- anatop-min-bit-val: u32 value representing the minimum value of this + register. +- anatop-min-voltage: u32 value representing the minimum voltage of this + regulator. +- anatop-max-voltage: u32 value representing the maximum voltage of this + regulator. + +Optional properties: +- anatop-delay-reg-offset: u32 value representing the anatop MFD step time + register offset. +- anatop-delay-bit-shift: u32 value representing the bit shift for the step + time register. +- anatop-delay-bit-width: u32 value representing the number of bits used in + the step time register. +- anatop-enable-bit: u32 value representing regulator enable bit offset. +- vin-supply: input supply phandle. + +Example: + regulator-vddpu { + compatible = "fsl,anatop-regulator"; + regulator-name = "vddpu"; + regulator-min-microvolt = <725000>; + regulator-max-microvolt = <1300000>; + regulator-always-on; + anatop-reg-offset = <0x140>; + anatop-vol-bit-shift = <9>; + anatop-vol-bit-width = <5>; + anatop-delay-reg-offset = <0x170>; + anatop-delay-bit-shift = <24>; + anatop-delay-bit-width = <2>; + anatop-min-bit-val = <1>; + anatop-min-voltage = <725000>; + anatop-max-voltage = <1300000>; + }; diff --git a/roms/u-boot/doc/device-tree-bindings/regulator/max77686.txt b/roms/u-boot/doc/device-tree-bindings/regulator/max77686.txt new file mode 100644 index 000000000..ae9b1b6e6 --- /dev/null +++ b/roms/u-boot/doc/device-tree-bindings/regulator/max77686.txt @@ -0,0 +1,70 @@ +MAXIM, MAX77686 regulators + +This device uses two drivers: +- drivers/power/pmic/max77686.c (as parent I/O device) +- drivers/power/regulator/max77686.c (for child regulators) + +This file describes the binding info for the REGULATOR driver. + +First, please read the binding info for the pmic: +- doc/device-tree-bindings/pmic/max77686.txt + +Required subnode: +- voltage-regulators: required for the PMIC driver + +Required properties: +- regulator-name: used for regulator uclass platform data '.name' + +Optional: +- regulator-min-microvolt: minimum allowed Voltage to set +- regulator-max-microvolt: minimum allowed Voltage to set +- regulator-always-on: regulator should be never disabled +- regulator-boot-on: regulator should be enabled by the bootloader + +Example: +(subnode of max77686 pmic node) +voltage-regulators { + ldo1 { + regulator-name = "VDD_ALIVE_1.0V"; + regulator-min-microvolt = <1000000>; + regulator-max-microvolt = <1000000>; + regulator-always-on; + regulator-boot-on; + }; + + ldo2 { + regulator-name = "VDDQ_VM1M2_1.2V"; + regulator-min-microvolt = <1200000>; + regulator-max-microvolt = <1200000>; + regulator-always-on; + regulator-boot-on; + }; + . + . + . + ldo26 { + regulator-name = "nc"; + regulator-min-microvolt = <3000000>; + regulator-max-microvolt = <3000000>; + regulator-always-on; + regulator-boot-on; + }; + + buck1 { + regulator-compatible = "BUCK1"; + regulator-name = "VDD_MIF_1.0V"; + regulator-min-microvolt = <8500000>; + regulator-max-microvolt = <1100000>; + regulator-always-on; + regulator-boot-on; + }; + . + . + . + buck9 { + regulator-compatible = "BUCK9"; + regulator-name = "nc"; + regulator-min-microvolt = <1200000>; + regulator-max-microvolt = <1200000>; + }; +}; diff --git a/roms/u-boot/doc/device-tree-bindings/regulator/regulator.txt b/roms/u-boot/doc/device-tree-bindings/regulator/regulator.txt new file mode 100644 index 000000000..6c9a02120 --- /dev/null +++ b/roms/u-boot/doc/device-tree-bindings/regulator/regulator.txt @@ -0,0 +1,92 @@ +Voltage/Current regulator + +Binding: +The regulator devices don't use the "compatible" property. The binding is done +by the prefix of regulator node's name, or, if this fails, by the prefix of the +regulator's "regulator-name" property. Usually the pmic I/O driver will provide +the array of 'struct pmic_child_info' with the prefixes and compatible drivers. +The bind is done by calling function: pmic_bind_childs(). +Example drivers: +pmic: drivers/power/pmic/max77686.c +regulator: drivers/power/regulator/max77686.c + +For the node name e.g.: "prefix[:alpha:]num { ... }": +- the driver prefix should be: "prefix" - case sensitive +- the node name's "num" is set as "dev->driver_data" on bind + +Example the prefix "ldo" will pass for: "ldo1", "ldo@1", "ldoreg@1, ... + +Binding by means of the node's name is preferred. However if the node names +would produce ambiguous prefixes (like "regulator@1" and "regualtor@11") and you +can't or do not want to change them then binding against the "regulator-name" +property is possible. The syntax for the prefix of the "regulator-name" property +is the same as the one for the regulator's node name. +Use case: a regulator named "regulator@1" to be bound to a driver named +"LDO_DRV" and a regulator named "regualator@11" to be bound to an other driver +named "BOOST_DRV". Using prefix "regualtor@1" for driver matching would load +the same driver for both regulators, hence the prefix is ambiguous. + +Optional properties: +- regulator-name: a string, required by the regulator uclass, used for driver + binding if binding by node's name prefix fails +- regulator-min-microvolt: a minimum allowed Voltage value +- regulator-max-microvolt: a maximum allowed Voltage value +- regulator-min-microamp: a minimum allowed Current value +- regulator-max-microamp: a maximum allowed Current value +- regulator-always-on: regulator should never be disabled +- regulator-boot-on: enabled by bootloader/firmware +- regulator-ramp-delay: ramp delay for regulator (in uV/us) +- regulator-init-microvolt: a init allowed Voltage value +- regulator-state-(standby|mem|disk) + type: object + description: + sub-nodes for regulator state in Standby, Suspend-to-RAM, and + Suspend-to-DISK modes. Equivalent with standby, mem, and disk Linux + sleep states. + + properties: + regulator-on-in-suspend: + description: regulator should be on in suspend state. + type: boolean + + regulator-off-in-suspend: + description: regulator should be off in suspend state. + type: boolean + + regulator-suspend-microvolt: + description: the default voltage which regulator would be set in + suspend. This property is now deprecated, instead setting voltage + for suspend mode via the API which regulator driver provides is + recommended. + +Note +The "regulator-name" constraint is used for setting the device's uclass +platform data '.name' field. And the regulator device name is set from +it's node name. If "regulator-name" is not provided in dts, node name +is chosen for setting the device's uclass platform data '.name' field. + +Other kernel-style properties, are currently not used. + +Note: +For the regulator autoset from constraints, the framework expects that: +- regulator-min-microvolt is equal to regulator-max-microvolt +- regulator-min-microamp is equal to regulator-max-microamp +- regulator-always-on or regulator-boot-on is set + +Example: +ldo0 { + /* Optional */ + regulator-name = "VDDQ_EMMC_1.8V"; + regulator-min-microvolt = <1800000>; + regulator-max-microvolt = <1800000>; + regulator-min-microamp = <100000>; + regulator-max-microamp = <100000>; + regulator-init-microvolt = <1800000>; + regulator-always-on; + regulator-boot-on; + regulator-ramp-delay = <12000>; + regulator-state-mem { + regulator-on-in-suspend; + regulator-suspend-microvolt = <1800000>; + }; +}; diff --git a/roms/u-boot/doc/device-tree-bindings/regulator/sandbox.txt b/roms/u-boot/doc/device-tree-bindings/regulator/sandbox.txt new file mode 100644 index 000000000..d70494c45 --- /dev/null +++ b/roms/u-boot/doc/device-tree-bindings/regulator/sandbox.txt @@ -0,0 +1,45 @@ +Sandbox, PMIC regulators + +This device uses two drivers: +- drivers/power/pmic/sandbox.c (as parent I/O device) +- drivers/power/regulator/sandbox.c (for child regulators) + +This file describes the binding info for the REGULATOR driver. + +First, please read the binding info for the PMIC: +- doc/device-tree-bindings/pmic/sandbox.txt + +Required subnodes: +- ldoN { }; +- buckN { }; + +The sandbox PMIC can support: ldo1, ldo2, buck1, buck2. + +For each PMIC's regulator subnode, there is one required property: +- regulator-name: used for regulator uclass platform data '.name' + +Optional: +- regulator-min-microvolt: minimum allowed Voltage to set +- regulator-max-microvolt: minimum allowed Voltage to set +- regulator-min-microamps: minimum allowed Current limit to set (LDO1/BUCK1) +- regulator-max-microamps: minimum allowed Current limit to set (LDO1/BUCK1) +- regulator-always-on: regulator should be never disabled +- regulator-boot-on: regulator should be enabled by the bootloader + +Example PMIC's regulator subnodes: + +ldo1 { + regulator-name = "VDD_1.0V"; + regulator-min-microvolt = <1000000>; + regulator-max-microvolt = <1200000>; + regulator-min-microamps = <100000>; + regulator-max-microamps = <400000>; + regulator-always-on; +}; + +buck2 { + regulator-name = "VDD_1.8V"; + regulator-min-microvolt = <1800000>; + regulator-max-microvolt = <1800000>; + regulator-boot-on; +}; diff --git a/roms/u-boot/doc/device-tree-bindings/regulator/st,stm32-vrefbuf.txt b/roms/u-boot/doc/device-tree-bindings/regulator/st,stm32-vrefbuf.txt new file mode 100644 index 000000000..0f6b6feda --- /dev/null +++ b/roms/u-boot/doc/device-tree-bindings/regulator/st,stm32-vrefbuf.txt @@ -0,0 +1,23 @@ +STM32 VREFBUF - Voltage reference buffer + +Some STM32 devices embed a voltage reference buffer which can be used as +voltage reference for ADCs, DACs and also as voltage reference for external +components through the dedicated VREF+ pin. + +Required properties: +- compatible: Must be "st,stm32-vrefbuf". +- reg: Offset and length of VREFBUF register set. +- clocks: Must contain an entry for peripheral clock. + +Optional properties: +- vdda-supply: Phandle to the parent vdda supply regulator node. + +Example: + vrefbuf: regulator@58003c00 { + compatible = "st,stm32-vrefbuf"; + reg = <0x58003C00 0x8>; + clocks = <&rcc VREF_CK>; + regulator-min-microvolt = <1500000>; + regulator-max-microvolt = <2500000>; + vdda-supply = <&vdda>; + }; diff --git a/roms/u-boot/doc/device-tree-bindings/regulator/tps65090.txt b/roms/u-boot/doc/device-tree-bindings/regulator/tps65090.txt new file mode 100644 index 000000000..313a60ba6 --- /dev/null +++ b/roms/u-boot/doc/device-tree-bindings/regulator/tps65090.txt @@ -0,0 +1,122 @@ +TPS65090 regulators + +Required properties: +- compatible: "ti,tps65090" +- reg: I2C slave address +- interrupts: the interrupt outputs of the controller +- regulators: A node that houses a sub-node for each regulator within the + device. Each sub-node is identified using the node's name, with valid + values listed below. The content of each sub-node is defined by the + standard binding for regulators; see regulator.txt. + dcdc[1-3], fet[1-7] and ldo[1-2] respectively. +- vsys[1-3]-supply: The input supply for DCDC[1-3] respectively. +- infet[1-7]-supply: The input supply for FET[1-7] respectively. +- vsys-l[1-2]-supply: The input supply for LDO[1-2] respectively. + +Optional properties: +- ti,enable-ext-control: This is applicable for DCDC1, DCDC2 and DCDC3. + If DCDCs are externally controlled then this property should be there. +- "dcdc-ext-control-gpios: This is applicable for DCDC1, DCDC2 and DCDC3. + If DCDCs are externally controlled and if it is from GPIO then GPIO + number should be provided. If it is externally controlled and no GPIO + entry then driver will just configure this rails as external control + and will not provide any enable/disable APIs. + +Each regulator is defined using the standard binding for regulators. + +Example: + + tps65090@48 { + compatible = "ti,tps65090"; + reg = <0x48>; + interrupts = <0 88 0x4>; + + vsys1-supply = <&some_reg>; + vsys2-supply = <&some_reg>; + vsys3-supply = <&some_reg>; + infet1-supply = <&some_reg>; + infet2-supply = <&some_reg>; + infet3-supply = <&some_reg>; + infet4-supply = <&some_reg>; + infet5-supply = <&some_reg>; + infet6-supply = <&some_reg>; + infet7-supply = <&some_reg>; + vsys_l1-supply = <&some_reg>; + vsys_l2-supply = <&some_reg>; + + regulators { + dcdc1 { + regulator-name = "dcdc1"; + regulator-boot-on; + regulator-always-on; + ti,enable-ext-control; + dcdc-ext-control-gpios = <&gpio 10 0>; + }; + + dcdc2 { + regulator-name = "dcdc2"; + regulator-boot-on; + regulator-always-on; + }; + + dcdc3 { + regulator-name = "dcdc3"; + regulator-boot-on; + regulator-always-on; + }; + + fet1 { + regulator-name = "fet1"; + regulator-boot-on; + regulator-always-on; + }; + + fet2 { + regulator-name = "fet2"; + regulator-boot-on; + regulator-always-on; + }; + + fet3 { + regulator-name = "fet3"; + regulator-boot-on; + regulator-always-on; + }; + + fet4 { + regulator-name = "fet4"; + regulator-boot-on; + regulator-always-on; + }; + + fet5 { + regulator-name = "fet5"; + regulator-boot-on; + regulator-always-on; + }; + + fet6 { + regulator-name = "fet6"; + regulator-boot-on; + regulator-always-on; + }; + + fet7 { + regulator-name = "fet7"; + regulator-boot-on; + regulator-always-on; + }; + + ldo1 { + regulator-name = "ldo1"; + regulator-boot-on; + regulator-always-on; + }; + + ldo2 { + regulator-name = "ldo2"; + regulator-boot-on; + regulator-always-on; + }; + }; + }; diff --git a/roms/u-boot/doc/device-tree-bindings/remoteproc/k3-rproc.txt b/roms/u-boot/doc/device-tree-bindings/remoteproc/k3-rproc.txt new file mode 100644 index 000000000..0a1e85822 --- /dev/null +++ b/roms/u-boot/doc/device-tree-bindings/remoteproc/k3-rproc.txt @@ -0,0 +1,50 @@ +Texas Instruments' K3 Remote processor driver +============================================= + +In K3 generation Socs, loading an image on any processing entity +cannot be done directly from U-Boot. In order to load an image, +remoteproc driver should communicate to SYSFW with a specific sequence. +Also enable the timer required for this remotecore. + +Required properties: +-------------------- +- compatible: Shall be: "ti,am654-rproc" +- reg: base address of the remoteproc timer. +- power-domains: Should contain two sets of entries: + First set corresponds to pm domain of the + remotecore timer. Seconf entry corresponds to the + remoteproc to start. + This property is as per the binding, + doc/device-tree-bindings/power/ti,sci-pm-domain.txt +- resets: Should contain a phandle to a reset controller node + and an args specifier containing the remote code + device id and reset mask value. This is as per the + doc/device-tree-bindings/reset/ti,sci-reset.txt +- ti,sci: Phandle to TI-SCI compatible System controller node. +- ti,sci-proc-id: Processor id as identified by TISCI + +Optional properties: +-------------------- +- assigned-clocks: Should contain a phandle to clock node and an args + specifier containing the remote core device id and + the clock id within the remote core. This is as per + doc/device-tree-bindings/clock/ti,sci-clk.txt +- assigned-clock-rates: One entry for each entry of assigned-clocks. This is + the frequency at which the corresponding clock needs + to be assigned. +- ti,sci-host-id: Host ID to which the processor control is transferred to + +Example: +--------- + +a53_0: a53@0 { + compatible = "ti,am654-rproc"; + power-domains = <&k3_pds 61>, + <&k3_pds 202>; + resets = <&k3_reset 202 0>; + assigned-clocks = <&k3_clks 202 0>; + assigned-clock-rates = <800000000>; + ti,sci = <&dmsc>; + ti,sci-proc-id = <32>; + ti,sci-host-id = <10>; +}; diff --git a/roms/u-boot/doc/device-tree-bindings/remoteproc/k3-system-controller.txt b/roms/u-boot/doc/device-tree-bindings/remoteproc/k3-system-controller.txt new file mode 100644 index 000000000..32f4720b0 --- /dev/null +++ b/roms/u-boot/doc/device-tree-bindings/remoteproc/k3-system-controller.txt @@ -0,0 +1,24 @@ +Texas Instruments' K3 System Controller +========================================= + +K3 specific SoCs have a dedicated microcontroller for doing +resource management. Any HLOS/firmware on compute clusters should +load a firmware to this microcontroller before accessing any resource. +This driver communicates with ROM for loading this firmware. + +Required properties: +-------------------- +- compatible: Shall be: "ti,am654-system-controller" +- mbox-names: "tx" for Transfer channel + "rx" for Receive channel +- mboxes: Corresponding phandles to mailbox channels. + + +Example: +-------- + +system-controller: system-controller { + compatible = "ti,am654-system-controller"; + mboxes= <&secproxy 4>, <&secproxy 5>; + mbox-names = "tx", "rx"; +}; diff --git a/roms/u-boot/doc/device-tree-bindings/remoteproc/remoteproc.txt b/roms/u-boot/doc/device-tree-bindings/remoteproc/remoteproc.txt new file mode 100644 index 000000000..031764f51 --- /dev/null +++ b/roms/u-boot/doc/device-tree-bindings/remoteproc/remoteproc.txt @@ -0,0 +1,14 @@ +Remote Processor uclass + +Binding: + +Remoteproc devices shall have compatible corresponding to thier +drivers. However the following generic properties will be supported + +Optional Properties: +- remoteproc-name: a string, used if provided to describe the processor. + This must be unique in an operational system. +- remoteproc-internal-memory-mapped: a bool, indicates that the remote + processor has internal memory that it uses to execute code and store + data. Such a device is not expected to have a MMU. If no type property + is provided, the device is assumed to map to such a model. diff --git a/roms/u-boot/doc/device-tree-bindings/remoteproc/ti,k3-dsp-rproc.txt b/roms/u-boot/doc/device-tree-bindings/remoteproc/ti,k3-dsp-rproc.txt new file mode 100644 index 000000000..80ab7a409 --- /dev/null +++ b/roms/u-boot/doc/device-tree-bindings/remoteproc/ti,k3-dsp-rproc.txt @@ -0,0 +1,101 @@ +TI K3 DSP devices +================= + +The TI K3 family of SoCs usually have one or more TI DSP Core sub-systems that +are used to offload some of the processor-intensive tasks or algorithms, for +achieving various system level goals. + +These processor sub-systems usually contain additional sub-modules like L1 +and/or L2 caches/SRAMs, an Interrupt Controller, an external memory controller, +a dedicated local power/sleep controller etc. The DSP processor cores in the +K3 SoCs is usually either a TMS320C66x CorePac processor or a TMS320C71x CorePac +processor. + +DSP Device Node: +================ +Each DSP Core sub-system is represented as a single DT node. Each node has a +number of required or optional properties that enable the OS running on the +host processor (Arm CorePac) to perform the device management of the remote +processor and to communicate with the remote processor. + +Required properties: +-------------------- +The following are the mandatory properties: + +- compatible: Should be one of the following, + "ti,j721e-c66-dsp" for C66x DSPs on K3 J721E SoCs + "ti,j721e-c71-dsp" for C71x DSPs on K3 J721E SoCs + +- reg: Should contain an entry for each value in 'reg-names'. + Each entry should have the memory region's start address + and the size of the region, the representation matching + the parent node's '#address-cells' and '#size-cells' values. + +- reg-names: Should contain strings with the following names, each + representing a specific internal memory region (if + present), and should be defined in this order, + "l2sram", "l1pram", "l1dram" + NOTE: C71x DSPs do not have a "l1pram" memory. + +- ti,sci: Should be a phandle to the TI-SCI System Controller node + +- ti,sci-dev-id: Should contain the TI-SCI device id corresponding to the + DSP Core. Please refer to the corresponding System + Controller documentation for valid values for the DSP + cores. + +- ti,sci-proc-ids: Should contain 2 integer values. The first cell should + contain the TI-SCI processor id for the DSP core device + and the second cell should contain the TI-SCI host id to + which the processor control ownership should be + transferred to. + +- resets: Should contain the phandle to the reset controller node + managing the resets for this device, and a reset + specifier. Please refer to the following reset bindings + for the reset argument specifier, + Documentation/devicetree/bindings/reset/ti,sci-reset.txt + +Example: +--------- + +1. J721E SoC + /* J721E remoteproc alias */ + aliases { + rproc6 = &c66_0; + rproc8 = &c71_0; + }; + + cbass_main: interconnect@100000 { + compatible = "simple-bus"; + #address-cells = <2>; + #size-cells = <2>; + ranges = <0x00 0x64800000 0x00 0x64800000 0x00 0x00800000>, /* C71_0 */ + <0x4d 0x80800000 0x4d 0x80800000 0x00 0x00800000>, /* C66_0 */ + <0x4d 0x81800000 0x4d 0x81800000 0x00 0x00800000>; /* C66_1 */ + + /* J721E C66_0 DSP node */ + c66_0: dsp@4d80800000 { + compatible = "ti,j721e-c66-dsp"; + reg = <0x4d 0x80800000 0x00 0x00048000>, + <0x4d 0x80e00000 0x00 0x00008000>, + <0x4d 0x80f00000 0x00 0x00008000>; + reg-names = "l2sram", "l1pram", "l1dram"; + ti,sci = <&dmsc>; + ti,sci-dev-id = <142>; + ti,sci-proc-ids = <0x03 0xFF>; + resets = <&k3_reset 142 1>; + }; + + /* J721E C71_0 DSP node */ + c71_0: dsp@64800000 { + compatible = "ti,j721e-c71-dsp"; + reg = <0x00 0x64800000 0x00 0x00080000>, + <0x00 0x64e00000 0x00 0x0000c000>; + reg-names = "l2sram", "l1dram"; + ti,sci = <&dmsc>; + ti,sci-dev-id = <15>; + ti,sci-proc-ids = <0x30 0xFF>; + resets = <&k3_reset 15 1>; + }; + }; diff --git a/roms/u-boot/doc/device-tree-bindings/remoteproc/ti,k3-r5f-rproc.txt b/roms/u-boot/doc/device-tree-bindings/remoteproc/ti,k3-r5f-rproc.txt new file mode 100644 index 000000000..25ee495fe --- /dev/null +++ b/roms/u-boot/doc/device-tree-bindings/remoteproc/ti,k3-r5f-rproc.txt @@ -0,0 +1,167 @@ +TI K3 R5F processor subsystems +============================== + +The TI K3 family of SoCs usually have one or more dual-core Arm Cortex +R5F processor subsystems/clusters (R5FSS). The dual core cluster can be +used either in a LockStep mode providing safety/fault tolerance features +or in a Split mode providing two individual compute cores for doubling +the compute capacity. These are used together with other processors +present on the SoC to achieve various system level goals. + +R5F Sub-System Device Node: +=========================== +Each Dual-Core R5F sub-system is represented as a single DTS node representing +the cluster, with a pair of child DT nodes representing the individual R5F +cores. Each node has a number of required or optional properties that enable +the OS running on the host processor to perform the device management of the +remote processor and to communicate with the remote processor. + +Required properties: +-------------------- +The following are the mandatory properties: + +- compatible: Should be one of the following, + "ti,am654-r5fss" for R5F clusters/subsystems on + K3 AM65x SoCs + "ti,j721e-r5fss" for R5F clusters/subsystems on + K3 J721E SoCs + "ti,j7200-r5fss" for R5F clusters/subsystems on + K3 J7200 SoCs +- power-domains: Should contain a phandle to a PM domain provider node + and an args specifier containing the R5FSS device id + value. This property is as per the binding, + Documentation/devicetree/bindings/soc/ti/sci-pm-domain.txt +- #address-cells: Should be 1 +- #size-cells: Should be 1 +- ranges: Standard ranges definition providing translations for + R5F TCM address spaces + +Optional properties: +-------------------- +- ti,cluster-mode: Configuration Mode for the Dual R5F cores within the R5F + cluster. Should be either a value of 1 (LockStep mode) or + 0 (Split mode), default is LockStep mode if omitted. + + +R5F Processor Child Nodes: +========================== +The R5F Sub-System device node should define two R5F child nodes, each node +representing a TI instantiation of the Arm Cortex R5F core. There are some +specific integration differences for the IP like the usage of a Region Address +Translator (RAT) for translating the larger SoC bus addresses into a 32-bit +address space for the processor. + +Required properties: +-------------------- +The following are the mandatory properties: + +- compatible: Should be one of the following, + "ti,am654-r5f" for the R5F cores in K3 AM65x SoCs + "ti,j721e-r5f" for the R5F cores in K3 J721E SOCs + "ti,j7200-r5f" for the R5F cores in K3 J7200 SOCs +- reg: Should contain an entry for each value in 'reg-names'. + Each entry should have the memory region's start address + and the size of the region, the representation matching + the parent node's '#address-cells' and '#size-cells' values. +- reg-names: Should contain strings with the following names, each + representing a specific internal memory region, and + should be defined in this order, + "atcm", "btcm" +- ti,sci: Should be a phandle to the TI-SCI System Controller node +- ti,sci-dev-id: Should contain the TI-SCI device id corresponding to the + R5F Core. Please refer to the corresponding System + Controller documentation for valid values for the R5F + cores. +- ti,sci-proc-ids: Should contain 2 integer values. The first cell should + contain the TI-SCI processor id for the R5F core device + and the second cell should contain the TI-SCI host id to + which the processor control ownership should be + transferred to. +- resets: Should contain the phandle to the reset controller node + managing the resets for this device, and a reset + specifier. Please refer to the following reset bindings + for the reset argument specifier, + Documentation/devicetree/bindings/reset/ti,sci-reset.txt + for AM65x, J721E and J7200 SoCs + +Optional properties: +-------------------- +The following properties are optional properties for each of the R5F cores: + +- ti,atcm-enable: R5F core configuration mode dictating if ATCM should be + enabled. Should be either a value of 1 (enabled) or + 0 (disabled), default is disabled if omitted. R5F view + of ATCM dictated by ti,loczrama property. +- ti,btcm-enable: R5F core configuration mode dictating if BTCM should be + enabled. Should be either a value of 1 (enabled) or + 0 (disabled), default is enabled if omitted. R5F view + of BTCM dictated by ti,loczrama property. +- ti,loczrama: R5F core configuration mode dictating which TCM should + appear at address 0 (from core's view). Should be either + a value of 1 (ATCM at 0x0) or 0 (BTCM at 0x0), default + value is 1 if omitted. + +Example: +-------- +1. AM654 SoC + /* AM65x remoteproc alias */ + aliases { + remoteproc0 = &mcu_r5fss0_core0; + }; + + cbass_main: interconnect@100000 { + compatible = "simple-bus"; + #address-cells = <2>; + #size-cells = <2>; + ranges = <0x00 0x41000000 0x00 0x41000000 0x00 0x00020000>, + <0x00 0x41400000 0x00 0x41400000 0x00 0x00020000>, + <0x00 0x41c00000 0x00 0x41c00000 0x00 0x00080000>; + + cbass_mcu: interconnect@28380000 { + compatible = "simple-bus"; + #address-cells = <2>; + #size-cells = <2>; + ranges = <0x00 0x41000000 0x00 0x41000000 0x00 0x00020000>, /* MCU R5F Core0 */ + <0x00 0x41400000 0x00 0x41400000 0x00 0x00020000>, /* MCU R5F Core1 */ + <0x00 0x41c00000 0x00 0x41c00000 0x00 0x00080000>; /* MCU SRAM */ + + /* AM65x MCU R5FSS node */ + mcu_r5fss0: r5fss@41000000 { + compatible = "ti,am654-r5fss"; + power-domains = <&k3_pds 129>; + ti,cluster-mode = <1>; + #address-cells = <1>; + #size-cells = <1>; + ranges = <0x41000000 0x00 0x41000000 0x20000>, + <0x41400000 0x00 0x41400000 0x20000>; + + mcu_r5f0: r5f@41000000 { + compatible = "ti,am654-r5f"; + reg = <0x41000000 0x00008000>, + <0x41010000 0x00008000>; + reg-names = "atcm", "btcm"; + ti,sci = <&dmsc>; + ti,sci-dev-id = <159>; + ti,sci-proc-ids = <0x01 0xFF>; + resets = <&k3_reset 159 1>; + ti,atcm-enable = <1>; + ti,btcm-enable = <1>; + ti,loczrama = <1>; + }; + + mcu_r5f1: r5f@41400000 { + compatible = "ti,am654-r5f"; + reg = <0x41400000 0x00008000>, + <0x41410000 0x00008000>; + reg-names = "atcm", "btcm"; + ti,sci = <&dmsc>; + ti,sci-dev-id = <245>; + ti,sci-proc-ids = <0x02 0xFF>; + resets = <&k3_reset 245 1>; + ti,atcm-enable = <1>; + ti,btcm-enable = <1>; + ti,loczrama = <1>; + }; + }; + }; + }; diff --git a/roms/u-boot/doc/device-tree-bindings/reserved-memory/reserved-memory.txt b/roms/u-boot/doc/device-tree-bindings/reserved-memory/reserved-memory.txt new file mode 100644 index 000000000..bac4afa3b --- /dev/null +++ b/roms/u-boot/doc/device-tree-bindings/reserved-memory/reserved-memory.txt @@ -0,0 +1,136 @@ +*** Reserved memory regions *** + +Reserved memory is specified as a node under the /reserved-memory node. +The operating system shall exclude reserved memory from normal usage +one can create child nodes describing particular reserved (excluded from +normal use) memory regions. Such memory regions are usually designed for +the special usage by various device drivers. + +Parameters for each memory region can be encoded into the device tree +with the following nodes: + +/reserved-memory node +--------------------- +#address-cells, #size-cells (required) - standard definition + - Should use the same values as the root node +ranges (required) - standard definition + - Should be empty + +/reserved-memory/ child nodes +----------------------------- +Each child of the reserved-memory node specifies one or more regions of +reserved memory. Each child node may either use a 'reg' property to +specify a specific range of reserved memory, or a 'size' property with +optional constraints to request a dynamically allocated block of memory. + +Following the generic-names recommended practice, node names should +reflect the purpose of the node (ie. "framebuffer" or "dma-pool"). Unit +address (@<address>) should be appended to the name if the node is a +static allocation. + +Properties: +Requires either a) or b) below. +a) static allocation + reg (required) - standard definition +b) dynamic allocation + size (required) - length based on parent's #size-cells + - Size in bytes of memory to reserve. + alignment (optional) - length based on parent's #size-cells + - Address boundary for alignment of allocation. + alloc-ranges (optional) - prop-encoded-array (address, length pairs). + - Specifies regions of memory that are + acceptable to allocate from. + +If both reg and size are present, then the reg property takes precedence +and size is ignored. + +Additional properties: +compatible (optional) - standard definition + - may contain the following strings: + - shared-dma-pool: This indicates a region of memory meant to be + used as a shared pool of DMA buffers for a set of devices. It can + be used by an operating system to instantiate the necessary pool + management subsystem if necessary. + - vendor specific string in the form <vendor>,[<device>-]<usage> +no-map (optional) - empty property + - Indicates the operating system must not create a virtual mapping + of the region as part of its standard mapping of system memory, + nor permit speculative access to it under any circumstances other + than under the control of the device driver using the region. +reusable (optional) - empty property + - The operating system can use the memory in this region with the + limitation that the device driver(s) owning the region need to be + able to reclaim it back. Typically that means that the operating + system can use that region to store volatile or cached data that + can be otherwise regenerated or migrated elsewhere. + +Linux implementation note: +- If a "linux,cma-default" property is present, then Linux will use the + region for the default pool of the contiguous memory allocator. + +- If a "linux,dma-default" property is present, then Linux will use the + region for the default pool of the consistent DMA allocator. + +Device node references to reserved memory +----------------------------------------- +Regions in the /reserved-memory node may be referenced by other device +nodes by adding a memory-region property to the device node. + +memory-region (optional) - phandle, specifier pairs to children of /reserved-memory + +Example +------- +This example defines 3 contiguous regions are defined for Linux kernel: +one default of all device drivers (named linux,cma@72000000 and 64MiB in size), +one dedicated to the framebuffer device (named framebuffer@78000000, 8MiB), and +one for multimedia processing (named multimedia-memory@77000000, 64MiB). + +/ { + #address-cells = <1>; + #size-cells = <1>; + + memory { + reg = <0x40000000 0x40000000>; + }; + + reserved-memory { + #address-cells = <1>; + #size-cells = <1>; + ranges; + + /* global autoconfigured region for contiguous allocations */ + linux,cma { + compatible = "shared-dma-pool"; + reusable; + size = <0x4000000>; + alignment = <0x2000>; + linux,cma-default; + }; + + display_reserved: framebuffer@78000000 { + reg = <0x78000000 0x800000>; + }; + + multimedia_reserved: multimedia@77000000 { + compatible = "acme,multimedia-memory"; + reg = <0x77000000 0x4000000>; + }; + }; + + /* ... */ + + fb0: video@12300000 { + memory-region = <&display_reserved>; + /* ... */ + }; + + scaler: scaler@12500000 { + memory-region = <&multimedia_reserved>; + /* ... */ + }; + + codec: codec@12600000 { + memory-region = <&multimedia_reserved>; + /* ... */ + }; +}; diff --git a/roms/u-boot/doc/device-tree-bindings/reset/reset.txt b/roms/u-boot/doc/device-tree-bindings/reset/reset.txt new file mode 100644 index 000000000..31db6ff84 --- /dev/null +++ b/roms/u-boot/doc/device-tree-bindings/reset/reset.txt @@ -0,0 +1,75 @@ += Reset Signal Device Tree Bindings = + +This binding is intended to represent the hardware reset signals present +internally in most IC (SoC, FPGA, ...) designs. Reset signals for whole +standalone chips are most likely better represented as GPIOs, although there +are likely to be exceptions to this rule. + +Hardware blocks typically receive a reset signal. This signal is generated by +a reset provider (e.g. power management or clock module) and received by a +reset consumer (the module being reset, or a module managing when a sub- +ordinate module is reset). This binding exists to represent the provider and +consumer, and provide a way to couple the two together. + +A reset signal is represented by the phandle of the provider, plus a reset +specifier - a list of DT cells that represents the reset signal within the +provider. The length (number of cells) and semantics of the reset specifier +are dictated by the binding of the reset provider, although common schemes +are described below. + +A word on where to place reset signal consumers in device tree: It is possible +in hardware for a reset signal to affect multiple logically separate HW blocks +at once. In this case, it would be unwise to represent this reset signal in +the DT node of each affected HW block, since if activated, an unrelated block +may be reset. Instead, reset signals should be represented in the DT node +where it makes most sense to control it; this may be a bus node if all +children of the bus are affected by the reset signal, or an individual HW +block node for dedicated reset signals. The intent of this binding is to give +appropriate software access to the reset signals in order to manage the HW, +rather than to slavishly enumerate the reset signal that affects each HW +block. + += Reset providers = + +Required properties: +#reset-cells: Number of cells in a reset specifier; Typically 0 for nodes + with a single reset output and 1 for nodes with multiple + reset outputs. + +For example: + + rst: reset-controller { + #reset-cells = <1>; + }; + += Reset consumers = + +Required properties: +resets: List of phandle and reset specifier pairs, one pair + for each reset signal that affects the device, or that the + device manages. Note: if the reset provider specifies '0' for + #reset-cells, then only the phandle portion of the pair will + appear. + +Optional properties: +reset-names: List of reset signal name strings sorted in the same order as + the resets property. Consumers drivers will use reset-names to + match reset signal names with reset specifiers. + +For example: + + device { + resets = <&rst 20>; + reset-names = "reset"; + }; + +This represents a device with a single reset signal named "reset". + + bus { + resets = <&rst 10> <&rst 11> <&rst 12> <&rst 11>; + reset-names = "i2s1", "i2s2", "dma", "mixer"; + }; + +This represents a bus that controls the reset signal of each of four sub- +ordinate devices. Consider for example a bus that fails to operate unless no +child device has reset asserted. diff --git a/roms/u-boot/doc/device-tree-bindings/reset/st,stm32-rcc.txt b/roms/u-boot/doc/device-tree-bindings/reset/st,stm32-rcc.txt new file mode 100644 index 000000000..01db34375 --- /dev/null +++ b/roms/u-boot/doc/device-tree-bindings/reset/st,stm32-rcc.txt @@ -0,0 +1,6 @@ +STMicroelectronics STM32 Peripheral Reset Controller +==================================================== + +The RCC IP is both a reset and a clock controller. + +Please see Documentation/devicetree/bindings/clock/st,stm32-rcc.txt diff --git a/roms/u-boot/doc/device-tree-bindings/reset/syscon-reset.txt b/roms/u-boot/doc/device-tree-bindings/reset/syscon-reset.txt new file mode 100644 index 000000000..f136b3d22 --- /dev/null +++ b/roms/u-boot/doc/device-tree-bindings/reset/syscon-reset.txt @@ -0,0 +1,36 @@ +Generic SYSCON mapped register reset driver + +This is a generic reset driver using syscon to map the reset register. +The reset is generally performed with a write to the reset register +defined by the register map pointed by syscon reference plus the offset and +shifted by the reset specifier/ + +To assert a reset on some device, the equivalent of the following operation is +performed, where reset_id is the reset specifier from the device's resets +property. + + if (BIT(reset_id) & mask) + regmap[offset][reset_id] = assert-high; + +Required properties: +- compatible: should contain "syscon-reset" +- #reset-cells: must be 1 +- regmap: this is phandle to the register map node +- offset: offset in the register map for the reboot register (in bytes) + +Optional properties: +- mask: accept only the reset specifiers defined by the mask (32 bit) +- assert-high: Bit to write when asserting a reset. Defaults to 1. + +Default will be little endian mode, 32 bit access only. + +Example: + + reset-controller { + compatible = "syscon-reset"; + #reset-cells = <1>; + regmap = <&sysctl>; + offset = <0x20>; + mask = <0x27FFFFFF>; + assert-high = <0>; + }; diff --git a/roms/u-boot/doc/device-tree-bindings/reset/ti,sci-reset.txt b/roms/u-boot/doc/device-tree-bindings/reset/ti,sci-reset.txt new file mode 100644 index 000000000..e7e2d13f9 --- /dev/null +++ b/roms/u-boot/doc/device-tree-bindings/reset/ti,sci-reset.txt @@ -0,0 +1,54 @@ +Texas Instruments TI SCI Reset Controller +========================================= + +Some TI SoCs contain a system controller (like the SYSFW, etc...) that is +responsible for controlling the state of the IPs that are present. +Communication between the host processor running an OS and the system +controller happens through a protocol known as TI SCI [1]. + +[1] http://processors.wiki.ti.com/index.php/TISCI + +Reset Controller Node +===================== +The reset controller node represents the resets of various hardware modules +present on the SoC managed by the SYSFW. Because this relies on the TI SCI +protocol to communicate with the SYSFW it must be a child of the sysfw node. + +Required Properties: +-------------------- + - compatible: Must be "ti,sci-reset" + - #reset-cells: Must be 2. Please see the reset consumer node below for + usage details. + +Example (AM65x): +---------------- + sysfw: sysfw { + compatible = "ti,am654-system-controller"; + ... + k3_reset: reset-controller { + compatible = "ti,sci-reset"; + #reset-cells = <2>; + }; + }; + +Reset Consumers +=============== +Each of the reset consumer nodes should have the following properties, +in addition to their own properties. + +Required Properties: +-------------------- + - resets: A phandle and reset specifier pair, one pair for each reset signal + that affects the device, or that the device manages. The phandle + should point to the TI SCI reset controller node, and the reset + specifier should have 2 cell-values. The first cell should contain + the device ID. The second cell should contain the reset mask value + used by system controller. + +Example (AM65x): +---------------- + uart2: serial@02800000 { + compatible = "ti,omap4-uart"; + ... + resets = <&k3_reset 5 1>; + }; diff --git a/roms/u-boot/doc/device-tree-bindings/root.txt b/roms/u-boot/doc/device-tree-bindings/root.txt new file mode 100644 index 000000000..001ccf36c --- /dev/null +++ b/roms/u-boot/doc/device-tree-bindings/root.txt @@ -0,0 +1,4 @@ +The root node + +Optional properties: + - serial-number : a string representing the device's serial number diff --git a/roms/u-boot/doc/device-tree-bindings/rtc/abracon,abx80x.txt b/roms/u-boot/doc/device-tree-bindings/rtc/abracon,abx80x.txt new file mode 100644 index 000000000..2405e35a1 --- /dev/null +++ b/roms/u-boot/doc/device-tree-bindings/rtc/abracon,abx80x.txt @@ -0,0 +1,31 @@ +Abracon ABX80X I2C ultra low power RTC/Alarm chip + +The Abracon ABX80X family consist of the ab0801, ab0803, ab0804, ab0805, ab1801, +ab1803, ab1804 and ab1805. The ab0805 is the superset of ab080x and the ab1805 +is the superset of ab180x. + +Required properties: + + - "compatible": should one of: + "abracon,abx80x" + "abracon,ab0801" + "abracon,ab0803" + "abracon,ab0804" + "abracon,ab0805" + "abracon,ab1801" + "abracon,ab1803" + "abracon,ab1804" + "abracon,ab1805" + "microcrystal,rv1805" + Using "abracon,abx80x" will enable chip autodetection. + - "reg": I2C bus address of the device + +Optional properties: + +The abx804 and abx805 have a trickle charger that is able to charge the +connected battery or supercap. Both the following properties have to be defined +and valid to enable charging: + + - "abracon,tc-diode": should be "standard" (0.6V) or "schottky" (0.3V) + - "abracon,tc-resistor": should be <0>, <3>, <6> or <11>. 0 disables the output + resistor, the other values are in kOhm. diff --git a/roms/u-boot/doc/device-tree-bindings/rtc/brcm,brcmstb-waketimer.txt b/roms/u-boot/doc/device-tree-bindings/rtc/brcm,brcmstb-waketimer.txt new file mode 100644 index 000000000..1d990bcc0 --- /dev/null +++ b/roms/u-boot/doc/device-tree-bindings/rtc/brcm,brcmstb-waketimer.txt @@ -0,0 +1,22 @@ +Broadcom STB wake-up Timer + +The Broadcom STB wake-up timer provides a 27Mhz resolution timer, with the +ability to wake up the system from low-power suspend/standby modes. + +Required properties: +- compatible : should contain "brcm,brcmstb-waketimer" +- reg : the register start and length for the WKTMR block +- interrupts : The TIMER interrupt +- interrupt-parent: The phandle to the Always-On (AON) Power Management (PM) L2 + interrupt controller node +- clocks : The phandle to the UPG fixed clock (27Mhz domain) + +Example: + +waketimer@f0411580 { + compatible = "brcm,brcmstb-waketimer"; + reg = <0xf0411580 0x14>; + interrupts = <0x3>; + interrupt-parent = <&aon_pm_l2_intc>; + clocks = <&upg_fixed>; +}; diff --git a/roms/u-boot/doc/device-tree-bindings/rtc/ds3232.txt b/roms/u-boot/doc/device-tree-bindings/rtc/ds3232.txt new file mode 100644 index 000000000..254b7bc3c --- /dev/null +++ b/roms/u-boot/doc/device-tree-bindings/rtc/ds3232.txt @@ -0,0 +1,15 @@ +DS3232 Real-Time Clock with SRAM + +The RTC driver provides time and date functionality. Also read and write +functions are provided that can be used to access the SRAM memory. + +Required properties: +- compatible : should contain "dallas,ds3232" +- reg : the I2C RTC address + +Example: + +rtc@68 { + compatible = "dallas,ds3232"; + reg = <0x68>; +}; diff --git a/roms/u-boot/doc/device-tree-bindings/serial/8250.txt b/roms/u-boot/doc/device-tree-bindings/serial/8250.txt new file mode 100644 index 000000000..ba8edae0e --- /dev/null +++ b/roms/u-boot/doc/device-tree-bindings/serial/8250.txt @@ -0,0 +1,66 @@ +* UART (Universal Asynchronous Receiver/Transmitter) + +Required properties: +- compatible : one of: + - "ns8250" + - "ns16450" + - "ns16550a" + - "ns16550" + - "ns16750" + - "ns16850" + - For Tegra20, must contain "nvidia,tegra20-uart" + - For other Tegra, must contain '"nvidia,<chip>-uart", + "nvidia,tegra20-uart"' where <chip> is tegra30, tegra114, tegra124, + tegra132, or tegra210. + - "nxp,lpc3220-uart" + - "ralink,rt2880-uart" + - "ibm,qpace-nwp-serial" + - "altr,16550-FIFO32" + - "altr,16550-FIFO64" + - "altr,16550-FIFO128" + - "fsl,16550-FIFO64" + - "fsl,ns16550" + - "serial" if the port type is unknown. +- reg : offset and length of the register set for the device. +- interrupts : should contain uart interrupt. +- clock-frequency : the input clock frequency for the UART + or + clocks phandle to refer to the clk used as per Documentation/devicetree + /bindings/clock/clock-bindings.txt + +Optional properties: +- current-speed : the current active speed of the UART. +- reg-offset : offset to apply to the mapbase from the start of the registers. +- reg-shift : quantity to shift the register offsets by. +- reg-io-width : the size (in bytes) of the IO accesses that should be + performed on the device. There are some systems that require 32-bit + accesses to the UART (e.g. TI davinci). +- used-by-rtas : set to indicate that the port is in use by the OpenFirmware + RTAS and should not be registered. +- no-loopback-test: set to indicate that the port does not implements loopback + test mode +- fifo-size: the fifo size of the UART. +- auto-flow-control: one way to enable automatic flow control support. The + driver is allowed to detect support for the capability even without this + property. + +Note: +* fsl,ns16550: + ------------ + Freescale DUART is very similar to the PC16552D (and to a + pair of NS16550A), albeit with some nonstandard behavior such as + erratum A-004737 (relating to incorrect BRK handling). + + Represents a single port that is compatible with the DUART found + on many Freescale chips (examples include mpc8349, mpc8548, + mpc8641d, p4080 and ls2080a). + +Example: + + uart@80230000 { + compatible = "ns8250"; + reg = <0x80230000 0x100>; + clock-frequency = <3686400>; + interrupts = <10>; + reg-shift = <2>; + }; diff --git a/roms/u-boot/doc/device-tree-bindings/serial/altera_jtaguart.txt b/roms/u-boot/doc/device-tree-bindings/serial/altera_jtaguart.txt new file mode 100644 index 000000000..97c7062c5 --- /dev/null +++ b/roms/u-boot/doc/device-tree-bindings/serial/altera_jtaguart.txt @@ -0,0 +1,4 @@ +Altera JTAG UART + +Required properties: +- compatible : should be "altr,juart-1.0" diff --git a/roms/u-boot/doc/device-tree-bindings/serial/altera_uart.txt b/roms/u-boot/doc/device-tree-bindings/serial/altera_uart.txt new file mode 100644 index 000000000..ebac3f5c1 --- /dev/null +++ b/roms/u-boot/doc/device-tree-bindings/serial/altera_uart.txt @@ -0,0 +1,7 @@ +Altera UART + +Required properties: +- compatible : should be "altr,uart-1.0" + +Optional properties: +- clock-frequency : frequency of the clock input to the UART diff --git a/roms/u-boot/doc/device-tree-bindings/serial/bcm2835-aux-uart.txt b/roms/u-boot/doc/device-tree-bindings/serial/bcm2835-aux-uart.txt new file mode 100644 index 000000000..75886e5fd --- /dev/null +++ b/roms/u-boot/doc/device-tree-bindings/serial/bcm2835-aux-uart.txt @@ -0,0 +1,10 @@ +* BCM283x mini UART + +Required properties: +- compatible: must be "brcm,bcm2835-aux-uart" +- reg: exactly one register range with length 0x1000 +- clock: input clock frequency for the UART (used to calculate the baud + rate divisor) + +Optional properties: +- skip-init: if present, the baud rate divisor is not changed diff --git a/roms/u-boot/doc/device-tree-bindings/serial/mcf-uart.txt b/roms/u-boot/doc/device-tree-bindings/serial/mcf-uart.txt new file mode 100644 index 000000000..d73f764c0 --- /dev/null +++ b/roms/u-boot/doc/device-tree-bindings/serial/mcf-uart.txt @@ -0,0 +1,19 @@ +Freescale ColdFire UART + +Required properties: +- compatible : should be "fsl,mcf-uart" +- reg: start address and size of the registers + +Example: + +soc { + compatible = "simple-bus"; + #address-cells = <1>; + #size-cells = <1>; + + uart0: uart@fc060000 { + compatible = "fsl,mcf-uart"; + reg = <0xfc060000 0x40>; + status = "disabled"; + }; +}; diff --git a/roms/u-boot/doc/device-tree-bindings/serial/microchip,pic32-uart.txt b/roms/u-boot/doc/device-tree-bindings/serial/microchip,pic32-uart.txt new file mode 100644 index 000000000..f00e215cf --- /dev/null +++ b/roms/u-boot/doc/device-tree-bindings/serial/microchip,pic32-uart.txt @@ -0,0 +1,5 @@ +* Microchip PIC32 serial UART + +Required properties: +- compatible: must be "microchip,pic32mzda-uart". +- reg: exactly one register range. diff --git a/roms/u-boot/doc/device-tree-bindings/serial/msm-serial.txt b/roms/u-boot/doc/device-tree-bindings/serial/msm-serial.txt new file mode 100644 index 000000000..dca995798 --- /dev/null +++ b/roms/u-boot/doc/device-tree-bindings/serial/msm-serial.txt @@ -0,0 +1,10 @@ +Qualcomm UART (Data Mover mode) + +Required properties: +- compatible: must be "qcom,msm-uartdm-v1.4" +- reg: start address and size of the registers +- clock: interface clock (must accept baudrate as a frequency) + +Optional properties: +- bit-rate: Data Mover bit rate register value + (If not defined then 0xCC is used as default) diff --git a/roms/u-boot/doc/device-tree-bindings/serial/mxc-serial.txt b/roms/u-boot/doc/device-tree-bindings/serial/mxc-serial.txt new file mode 100644 index 000000000..ede92a485 --- /dev/null +++ b/roms/u-boot/doc/device-tree-bindings/serial/mxc-serial.txt @@ -0,0 +1,8 @@ +NXP i.MX (MXC) UART + +Required properties: +- compatible: must be "fsl,imx7d-uart" +- reg: start address and size of the registers + +Optional properties: +- fsl,dte-mode: use DTE mode diff --git a/roms/u-boot/doc/device-tree-bindings/serial/omap_serial.txt b/roms/u-boot/doc/device-tree-bindings/serial/omap_serial.txt new file mode 100644 index 000000000..7a71b5de7 --- /dev/null +++ b/roms/u-boot/doc/device-tree-bindings/serial/omap_serial.txt @@ -0,0 +1,33 @@ +OMAP UART controller + +Required properties: +- compatible : should be "ti,omap2-uart" for OMAP2 controllers +- compatible : should be "ti,omap3-uart" for OMAP3 controllers +- compatible : should be "ti,omap4-uart" for OMAP4 controllers +- compatible : should be "ti,am4372-uart" for AM437x controllers +- compatible : should be "ti,am3352-uart" for AM335x controllers +- compatible : should be "ti,dra742-uart" for DRA7x controllers +- reg : address and length of the register space +- interrupts or interrupts-extended : Should contain the uart interrupt + specifier or both the interrupt + controller phandle and interrupt + specifier. +- ti,hwmods : Must be "uart<n>", n being the instance number (1-based) + +Optional properties: +- clock-frequency : frequency of the clock input to the UART +- dmas : DMA specifier, consisting of a phandle to the DMA controller + node and a DMA channel number. +- dma-names : "rx" for receive channel, "tx" for transmit channel. + +Example: + + uart4: serial@49042000 { + compatible = "ti,omap3-uart"; + reg = <0x49042000 0x400>; + interrupts = <80>; + dmas = <&sdma 81 &sdma 82>; + dma-names = "tx", "rx"; + ti,hwmods = "uart4"; + clock-frequency = <48000000>; + }; diff --git a/roms/u-boot/doc/device-tree-bindings/serial/pl01x.txt b/roms/u-boot/doc/device-tree-bindings/serial/pl01x.txt new file mode 100644 index 000000000..017b1e235 --- /dev/null +++ b/roms/u-boot/doc/device-tree-bindings/serial/pl01x.txt @@ -0,0 +1,10 @@ +* ARM AMBA Primecell PL011 & PL010 serial UART + +Required properties: +- compatible: must be "arm,primecell", "arm,pl011" or "arm,pl010" +- reg: exactly one register range with length 0x1000 +- clock: input clock frequency for the UART (used to calculate the baud + rate divisor) + +Optional properties: +- skip-init: if present, the baud rate divisor is not changed diff --git a/roms/u-boot/doc/device-tree-bindings/serial/qca,ar9330-uart.txt b/roms/u-boot/doc/device-tree-bindings/serial/qca,ar9330-uart.txt new file mode 100644 index 000000000..ec576a1ce --- /dev/null +++ b/roms/u-boot/doc/device-tree-bindings/serial/qca,ar9330-uart.txt @@ -0,0 +1,24 @@ +* Qualcomm Atheros AR9330 High-Speed UART + +Required properties: + +- compatible: Must be "qca,ar9330-uart" + +- reg: Specifies the physical base address of the controller and + the length of the memory mapped region. + +Additional requirements: + + Each UART port must have an alias correctly numbered in "aliases" + node. + +Example: + + aliases { + serial0 = &uart0; + }; + + uart0: uart@18020000 { + compatible = "qca,ar9330-uart"; + reg = <0x18020000 0x14>; + }; diff --git a/roms/u-boot/doc/device-tree-bindings/serial/sandbox-serial.txt b/roms/u-boot/doc/device-tree-bindings/serial/sandbox-serial.txt new file mode 100644 index 000000000..f429c9042 --- /dev/null +++ b/roms/u-boot/doc/device-tree-bindings/serial/sandbox-serial.txt @@ -0,0 +1,13 @@ +Sandbox serial + +The sandbox serial device is an emulated device which displays its output +on the host machine's console, and accepts input from its keyboard. + +Required properties: + compatible: "sandbox,serial" + +Optional properties: + sandbox,text-colour: If present, this is the colour of the console text. + Supported values are: + "black", "red", "green", "yellow", "blue", "megenta", "cyan", + "white" diff --git a/roms/u-boot/doc/device-tree-bindings/serial/sh.txt b/roms/u-boot/doc/device-tree-bindings/serial/sh.txt new file mode 100644 index 000000000..99634a5e7 --- /dev/null +++ b/roms/u-boot/doc/device-tree-bindings/serial/sh.txt @@ -0,0 +1,6 @@ +* Renesas SCI serial interface + +Required properties: +- compatible: must be "renesas,scif", "renesas,scifa" or "renesas,sci" +- reg: exactly one register range with length +- clock: input clock frequency for the SCI unit diff --git a/roms/u-boot/doc/device-tree-bindings/serial/snps-dw-apb-uart.txt b/roms/u-boot/doc/device-tree-bindings/serial/snps-dw-apb-uart.txt new file mode 100644 index 000000000..12bbe9f22 --- /dev/null +++ b/roms/u-boot/doc/device-tree-bindings/serial/snps-dw-apb-uart.txt @@ -0,0 +1,76 @@ +* Synopsys DesignWare ABP UART + +Required properties: +- compatible : "snps,dw-apb-uart" +- reg : offset and length of the register set for the device. +- interrupts : should contain uart interrupt. + +Clock handling: +The clock rate of the input clock needs to be supplied by one of +- clock-frequency : the input clock frequency for the UART. +- clocks : phandle to the input clock + +The supplying peripheral clock can also be handled, needing a second property +- clock-names: tuple listing input clock names. + Required elements: "baudclk", "apb_pclk" + +Optional properties: +- snps,uart-16550-compatible : reflects the value of UART_16550_COMPATIBLE + configuration parameter. Define this if your UART does not implement the busy + functionality. +- resets : phandle to the parent reset controller. +- reg-shift : quantity to shift the register offsets by. If this property is + not present then the register offsets are not shifted. +- reg-io-width : the size (in bytes) of the IO accesses that should be + performed on the device. If this property is not present then single byte + accesses are used. +- dcd-override : Override the DCD modem status signal. This signal will always + be reported as active instead of being obtained from the modem status + register. Define this if your serial port does not use this pin. +- dsr-override : Override the DTS modem status signal. This signal will always + be reported as active instead of being obtained from the modem status + register. Define this if your serial port does not use this pin. +- cts-override : Override the CTS modem status signal. This signal will always + be reported as active instead of being obtained from the modem status + register. Define this if your serial port does not use this pin. +- ri-override : Override the RI modem status signal. This signal will always be + reported as inactive instead of being obtained from the modem status register. + Define this if your serial port does not use this pin. + +Example: + + uart@80230000 { + compatible = "snps,dw-apb-uart"; + reg = <0x80230000 0x100>; + clock-frequency = <3686400>; + interrupts = <10>; + reg-shift = <2>; + reg-io-width = <4>; + dcd-override; + dsr-override; + cts-override; + ri-override; + }; + +Example with one clock: + + uart@80230000 { + compatible = "snps,dw-apb-uart"; + reg = <0x80230000 0x100>; + clocks = <&baudclk>; + interrupts = <10>; + reg-shift = <2>; + reg-io-width = <4>; + }; + +Example with two clocks: + + uart@80230000 { + compatible = "snps,dw-apb-uart"; + reg = <0x80230000 0x100>; + clocks = <&baudclk>, <&apb_pclk>; + clock-names = "baudclk", "apb_pclk"; + interrupts = <10>; + reg-shift = <2>; + reg-io-width = <4>; + }; diff --git a/roms/u-boot/doc/device-tree-bindings/serial/xilinx_uartlite.txt b/roms/u-boot/doc/device-tree-bindings/serial/xilinx_uartlite.txt new file mode 100644 index 000000000..d15753c8c --- /dev/null +++ b/roms/u-boot/doc/device-tree-bindings/serial/xilinx_uartlite.txt @@ -0,0 +1,13 @@ +Binding for Xilinx Uartlite Controller + +Required properties: +- compatible : should be "xlnx,xps-uartlite-1.00.a", or "xlnx,opb-uartlite-1.00.b" +- reg: Should contain UART controller registers location and length. +- interrupts: Should contain UART controller interrupts. + +Example: + serial@40600000 { + compatible = "xlnx,xps-uartlite-1.00.a"; + interrupts = <1 0>; + reg = <0x40600000 0x10000>; + }; diff --git a/roms/u-boot/doc/device-tree-bindings/soc/fsl/cpm_qe/qe/ucc.txt b/roms/u-boot/doc/device-tree-bindings/soc/fsl/cpm_qe/qe/ucc.txt new file mode 100644 index 000000000..2758f8643 --- /dev/null +++ b/roms/u-boot/doc/device-tree-bindings/soc/fsl/cpm_qe/qe/ucc.txt @@ -0,0 +1,53 @@ +* UCC (Unified Communications Controllers) + +Required properties: +- compatible : ucc_geth +- cell-index : the ucc number(1-8), corresponding to UCCx in UM. +- reg : Offset and length of the register set for the device +- rx-clock-name: the UCC receive clock source + "none": clock source is disabled + "brg1" through "brg16": clock source is BRG1-BRG16, respectively + "clk1" through "clk24": clock source is CLK1-CLK24, respectively +- tx-clock-name: the UCC transmit clock source + "none": clock source is disabled + "brg1" through "brg16": clock source is BRG1-BRG16, respectively + "clk1" through "clk24": clock source is CLK1-CLK24, respectively +The following two properties are deprecated. rx-clock has been replaced +with rx-clock-name, and tx-clock has been replaced with tx-clock-name. +Drivers that currently use the deprecated properties should continue to +do so, in order to support older device trees, but they should be updated +to check for the new properties first. +- rx-clock : represents the UCC receive clock source. + 0x00 : clock source is disabled; + 0x1~0x10 : clock source is BRG1~BRG16 respectively; + 0x11~0x28: clock source is QE_CLK1~QE_CLK24 respectively. +- tx-clock: represents the UCC transmit clock source; + 0x00 : clock source is disabled; + 0x1~0x10 : clock source is BRG1~BRG16 respectively; + 0x11~0x28: clock source is QE_CLK1~QE_CLK24 respectively. +- phy-handle : The phandle for the PHY connected to this controller. +- phy-connection-type : a string naming the controller/PHY interface type, + i.e., "mii" (default), "rmii", "gmii", "rgmii", "rgmii-id" (Internal + Delay), "rgmii-txid" (delay on TX only), "rgmii-rxid" (delay on RX only), + "tbi", or "rtbi". +- pio-handle : The phandle for the Parallel I/O port configuration. + +Deprecated properties: +- device-id : the ucc number(1-8), corresponding to UCCx in UM. + you should use cell-index + +Example: + ucc@2000 { + device_type = "network"; + compatible = "ucc_geth"; + cell-index = <1>; + reg = <2000 200>; + interrupts = <a0 0>; + interrupt-parent = <700>; + mac-address = [ 00 04 9f 00 23 23 ]; + rx-clock = "none"; + tx-clock = "clk9"; + phy-handle = <212000>; + phy-connection-type = "gmii"; + pio-handle = <140001>; + }; diff --git a/roms/u-boot/doc/device-tree-bindings/sound/da7219.txt b/roms/u-boot/doc/device-tree-bindings/sound/da7219.txt new file mode 100644 index 000000000..5fd8a9f1e --- /dev/null +++ b/roms/u-boot/doc/device-tree-bindings/sound/da7219.txt @@ -0,0 +1,113 @@ +Dialog Semiconductor DA7219 Audio Codec bindings + +DA7219 is an audio codec with advanced accessory detect features. + +====== + +Required properties: +- compatible : Should be "dlg,da7219" +- reg: Specifies the I2C slave address + +- interrupts : IRQ line info for DA7219. + (See Documentation/devicetree/bindings/interrupt-controller/interrupts.txt for + further information relating to interrupt properties) + +- VDD-supply: VDD power supply for the device +- VDDMIC-supply: VDDMIC power supply for the device +- VDDIO-supply: VDDIO power supply for the device + (See Documentation/devicetree/bindings/regulator/regulator.txt for further + information relating to regulators) + +Optional properties: +- interrupt-names : Name associated with interrupt line. Should be "wakeup" if + interrupt is to be used to wake system, otherwise "irq" should be used. +- wakeup-source: Flag to indicate this device can wake system (suspend/resume). + +- #clock-cells : Should be set to '<0>', only one clock source provided; +- clock-output-names : Name given for DAI clocks output; + +- clocks : phandle and clock specifier for codec MCLK. +- clock-names : Clock name string for 'clocks' attribute, should be "mclk". + +- dlg,micbias-lvl : Voltage (mV) for Mic Bias + [<1600>, <1800>, <2000>, <2200>, <2400>, <2600>] +- dlg,mic-amp-in-sel : Mic input source type + ["diff", "se_p", "se_n"] +- dlg,mclk-name : String name of MCLK for ACPI + +Deprecated properties: +- dlg,ldo-lvl : Required internal LDO voltage (mV) level for digital engine + (LDO unavailable in production HW so property no longer required). + +====== + +Child node - 'da7219_aad': + +Optional properties: +- dlg,micbias-pulse-lvl : Mic bias higher voltage pulse level (mV). + [<2800>, <2900>] +- dlg,micbias-pulse-time : Mic bias higher voltage pulse duration (ms) +- dlg,btn-cfg : Periodic button press measurements for 4-pole jack (ms) + [<2>, <5>, <10>, <50>, <100>, <200>, <500>] +- dlg,mic-det-thr : Impedance threshold for mic detection measurement (Ohms) + [<200>, <500>, <750>, <1000>] +- dlg,jack-ins-deb : Debounce time for jack insertion (ms) + [<5>, <10>, <20>, <50>, <100>, <200>, <500>, <1000>] +- dlg,jack-det-rate: Jack type detection latency (3/4 pole) + ["32ms_64ms", "64ms_128ms", "128ms_256ms", "256ms_512ms"] +- dlg,jack-rem-deb : Debounce time for jack removal (ms) + [<1>, <5>, <10>, <20>] +- dlg,a-d-btn-thr : Impedance threshold between buttons A and D + [0x0 - 0xFF] +- dlg,d-b-btn-thr : Impedance threshold between buttons D and B + [0x0 - 0xFF] +- dlg,b-c-btn-thr : Impedance threshold between buttons B and C + [0x0 - 0xFF] +- dlg,c-mic-btn-thr : Impedance threshold between button C and Mic + [0x0 - 0xFF] +- dlg,btn-avg : Number of 8-bit readings for averaged button measurement + [<1>, <2>, <4>, <8>] +- dlg,adc-1bit-rpt : Repeat count for 1-bit button measurement + [<1>, <2>, <4>, <8>] + +====== + +Example: + + codec: da7219@1a { + compatible = "dlg,da7219"; + reg = <0x1a>; + + interrupt-parent = <&gpio6>; + interrupts = <11 IRQ_TYPE_LEVEL_LOW>; + + VDD-supply = <®_audio>; + VDDMIC-supply = <®_audio>; + VDDIO-supply = <®_audio>; + + #clock-cells = <0>; + clock-output-names = "dai-clks"; + + clocks = <&clks 201>; + clock-names = "mclk"; + + dlg,ldo-lvl = <1200>; + dlg,micbias-lvl = <2600>; + dlg,mic-amp-in-sel = "diff"; + + da7219_aad { + dlg,btn-cfg = <50>; + dlg,mic-det-thr = <500>; + dlg,jack-ins-deb = <20>; + dlg,jack-det-rate = "32ms_64ms"; + dlg,jack-rem-deb = <1>; + + dlg,a-d-btn-thr = <0xa>; + dlg,d-b-btn-thr = <0x16>; + dlg,b-c-btn-thr = <0x21>; + dlg,c-mic-btn-thr = <0x3E>; + + dlg,btn-avg = <4>; + dlg,adc-1bit-rpt = <1>; + }; + }; diff --git a/roms/u-boot/doc/device-tree-bindings/sound/intel-hda.txt b/roms/u-boot/doc/device-tree-bindings/sound/intel-hda.txt new file mode 100644 index 000000000..aa96be06e --- /dev/null +++ b/roms/u-boot/doc/device-tree-bindings/sound/intel-hda.txt @@ -0,0 +1,26 @@ +* Intel High-definition Audio + +Configuration is set using 'verbs' which are blocks of 16 bytes of data each +with a different purpose, a little like a simple instruction set. + +Top-level node +-------------- + +Required properties: +- compatible: "intel,hd-audio" +- beep-verbs: list of verbs to send for a beep + +Optional properties +- intel,beep-nid: Node ID to use for beep (will be detected if not provided) +- codec-enable-gpio : The GPIO used to enable the audio codec + +Required subnodes: +- codecs: Contains a list of codec nodes + + +* Codec nodes + +Required properties: +- vendor-id: 16-bit vendor ID for audio codec +- device-id: 16-bit device ID for audio codec +- verbs: List of verbs, each 4 cells in length diff --git a/roms/u-boot/doc/device-tree-bindings/sound/max98357a.txt b/roms/u-boot/doc/device-tree-bindings/sound/max98357a.txt new file mode 100644 index 000000000..4bce14ce8 --- /dev/null +++ b/roms/u-boot/doc/device-tree-bindings/sound/max98357a.txt @@ -0,0 +1,22 @@ +Maxim MAX98357A audio DAC + +This node models the Maxim MAX98357A DAC. + +Required properties: +- compatible : "maxim,max98357a" + +Optional properties: +- sdmode-gpios : GPIO specifier for the chip's SD_MODE pin. + If this option is not specified then driver does not manage + the pin state (e.g. chip is always on). +- sdmode-delay : specify delay time for SD_MODE pin. + If this option is specified, which means it's required i2s clocks + ready before SD_MODE is unmuted in order to avoid the speaker pop noise. + It's observed that 5ms is sufficient. + +Example: + +max98357a { + compatible = "maxim,max98357a"; + sdmode-gpios = <&qcom_pinmux 25 0>; +}; diff --git a/roms/u-boot/doc/device-tree-bindings/sound/nvidia,tegra-audio-max98090.txt b/roms/u-boot/doc/device-tree-bindings/sound/nvidia,tegra-audio-max98090.txt new file mode 100644 index 000000000..25c63eac6 --- /dev/null +++ b/roms/u-boot/doc/device-tree-bindings/sound/nvidia,tegra-audio-max98090.txt @@ -0,0 +1,54 @@ +NVIDIA Tegra audio complex, with MAX98090 CODEC + +Required properties: +- compatible : "nvidia,tegra-audio-max98090" +- clocks : Must contain an entry for each entry in clock-names. + See ../clocks/clock-bindings.txt for details. +- clock-names : Must include the following entries: + - pll_a + - pll_a_out0 + - mclk (The Tegra cdev1/extern1 clock, which feeds the CODEC's mclk) +- nvidia,model : The user-visible name of this sound complex. +- nvidia,audio-routing : A list of the connections between audio components. + Each entry is a pair of strings, the first being the connection's sink, + the second being the connection's source. Valid names for sources and + sinks are the MAX98090's pins (as documented in its binding), and the jacks + on the board: + + * Headphones + * Speakers + * Mic Jack + * Int Mic + +- nvidia,i2s-controller : The phandle of the Tegra I2S controller that's + connected to the CODEC. +- nvidia,audio-codec : The phandle of the MAX98090 audio codec. + +Optional properties: +- nvidia,hp-det-gpios : The GPIO that detect headphones are plugged in +- nvidia,mic-det-gpios : The GPIO that detect microphones are plugged in +- codec-enable-gpio : The GPIO used to enable the audio codec + +Example: + +sound { + compatible = "nvidia,tegra-audio-max98090-venice2", + "nvidia,tegra-audio-max98090"; + nvidia,model = "NVIDIA Tegra Venice2"; + + nvidia,audio-routing = + "Headphones", "HPR", + "Headphones", "HPL", + "Speakers", "SPKR", + "Speakers", "SPKL", + "Mic Jack", "MICBIAS", + "IN34", "Mic Jack"; + + nvidia,i2s-controller = <&tegra_i2s1>; + nvidia,audio-codec = <&acodec>; + + clocks = <&tegra_car TEGRA124_CLK_PLL_A>, + <&tegra_car TEGRA124_CLK_PLL_A_OUT0>, + <&tegra_car TEGRA124_CLK_EXTERN1>; + clock-names = "pll_a", "pll_a_out0", "mclk"; +}; diff --git a/roms/u-boot/doc/device-tree-bindings/sound/snow.txt b/roms/u-boot/doc/device-tree-bindings/sound/snow.txt new file mode 100644 index 000000000..fa06956e7 --- /dev/null +++ b/roms/u-boot/doc/device-tree-bindings/sound/snow.txt @@ -0,0 +1,32 @@ +Audio Binding for Snow boards + +Required properties: +- compatible : Can be one of the following, + "google,snow-audio-max98090" or + "google,snow-audio-max98091" or + "google,snow-audio-max98095" +- samsung,i2s-controller (deprecated): The phandle of the Samsung I2S controller +- samsung,audio-codec (deprecated): The phandle of the audio codec + +Required sub-nodes: + + - 'cpu' subnode with a 'sound-dai' property containing the phandle of the I2S + controller + - 'codec' subnode with a 'sound-dai' property containing list of phandles + to the CODEC nodes, first entry must be the phandle of the MAX98090, + MAX98091 or MAX98095 CODEC (exact device type is indicated by the compatible + string) and the second entry must be the phandle of the HDMI IP block node + +Optional: +- samsung,model: The name of the sound-card +- codec-enable-gpio : The GPIO used to enable the audio codec + +Example: + +sound { + compatible = "google,snow-audio-max98095"; + + samsung,model = "Snow-I2S-MAX98095"; + samsung,i2s-controller = <&i2s0>; + samsung,audio-codec = <&max98095>; +}; diff --git a/roms/u-boot/doc/device-tree-bindings/spi/snps,dw-apb-ssi.txt b/roms/u-boot/doc/device-tree-bindings/spi/snps,dw-apb-ssi.txt new file mode 100644 index 000000000..8d2888fbe --- /dev/null +++ b/roms/u-boot/doc/device-tree-bindings/spi/snps,dw-apb-ssi.txt @@ -0,0 +1,56 @@ +Synopsys DesignWare AMBA 2.0 Synchronous Serial Interface +and Synopsys DesignWare High Performance Synchronous Serial Interface + +Required properties: +- compatible : One of + "altr,socfpga-spi", + "altr,socfpga-arria10-spi", + "canaan,kendryte-k210-spi", + "canaan,kendryte-k210-ssi", + "intel,stratix10-spi", + "intel,agilex-spi", + "mscc,ocelot-spi", + or "mscc,jaguar2-spi"; + and one of + "snps,dw-apb-ssi-3.20a", + "snps,dw-apb-ssi-3.22a", + "snps,dw-apb-ssi-3.23", + "snps,dw-apb-ssi-4.00a", + "snps,dw-apb-ssi-4.01", + or "snps,dwc-ssi-1.01a". + "snps,dw-apb-ssi" may also be used, but is deprecated in favor of specific + version strings. +- reg : The register base for the controller. For "mscc,<soc>-spi", a second + register set is required (named ICPU_CFG:SPI_MST) +- #address-cells : <1>, as required by generic SPI binding. +- #size-cells : <0>, also as required by generic SPI binding. +- clocks : phandles for the clocks, see the description of clock-names below. + The phandle for the "ssi_clk" is required. The phandle for the "pclk" clock + is optional. If a single clock is specified but no clock-name, it is the + "ssi_clk" clock. If both clocks are listed, the "ssi_clk" must be first. + +Optional properties: +- clock-names : Contains the names of the clocks: + "ssi_clk", for the core clock used to generate the external SPI clock. + "pclk", the interface clock, required for register access. +- cs-gpios : Specifies the gpio pins to be used for chipselects. +- num-cs : The number of chipselects. If omitted, this will default to 4. +- reg-io-width : The I/O register width (in bytes) implemented by this + device. Supported values are 2 or 4 (the default). + +Child nodes as per the generic SPI binding. + +Example: + + spi@fff00000 { + compatible = "altr,socfpga-arria10-spi", + "snps,dw-apb-ssi-4.00a", "snps,dw-apb-ssi"; + reg = <0xfff00000 0x1000>; + interrupts = <0 154 4>; + #address-cells = <1>; + #size-cells = <0>; + clocks = <&spi_m_clk>; + num-cs = <2>; + cs-gpios = <&gpio0 13 0>, + <&gpio0 14 0>; + }; diff --git a/roms/u-boot/doc/device-tree-bindings/spi/soft-spi.txt b/roms/u-boot/doc/device-tree-bindings/spi/soft-spi.txt new file mode 100644 index 000000000..dfb506647 --- /dev/null +++ b/roms/u-boot/doc/device-tree-bindings/spi/soft-spi.txt @@ -0,0 +1,38 @@ +Soft SPI + +The soft SPI bus implementation allows the use of GPIO pins to simulate a +SPI bus. No SPI host is required for this to work. The down-side is that the +performance will typically be much lower than a real SPI bus. + +The soft SPI node requires the following properties: + +Mandatory properties: +compatible: "spi-gpio" +cs-gpios: GPIOs to use for SPI chip select (output) +gpio-sck: GPIO to use for SPI clock (output) +And at least one of: +gpio-mosi: GPIO to use for SPI MOSI line (output) +gpio-miso: GPIO to use for SPI MISO line (input) + +Optional propertie: +spi-delay-us: Number of microseconds of delay between each CS transition + +The GPIOs should be specified as required by the GPIO controller referenced. +The first cell holds the phandle of the controller and the second cell +typically holds the GPIO number. + + +Example: + + soft-spi { + compatible = "spi-gpio"; + cs-gpios = <&gpio 235 0>; /* Y43 */ + gpio-sck = <&gpio 225 0>; /* Y31 */ + gpio-mosi = <&gpio 227 0>; /* Y33 */ + gpio-miso = <&gpio 224 0>; /* Y30 */ + spi-delay-us = <1>; + #address-cells = <1>; + #size-cells = <0>; + cs@0 { + }; + }; diff --git a/roms/u-boot/doc/device-tree-bindings/spi/spi-atcspi200.txt b/roms/u-boot/doc/device-tree-bindings/spi/spi-atcspi200.txt new file mode 100644 index 000000000..e67b3425f --- /dev/null +++ b/roms/u-boot/doc/device-tree-bindings/spi/spi-atcspi200.txt @@ -0,0 +1,37 @@ +Andestech ATCSPI200 SPI controller Device Tree Bindings +------------------------------------------------------- +ATCSPI200 is a Serial Peripheral Interface (SPI) controller +which serves as a SPI master or a SPI slave. + +It is often be embedded in AE3XX and AE250 platforms. + +Required properties: +- compatible: has to be "andestech,atcspi200". +- reg: Base address and size of the controllers memory area. +- #address-cells: <1>, as required by generic SPI binding. +- #size-cells: <0>, also as required by generic SPI binding. +- interrupts: Property with a value describing the interrupt number. +- clocks: Clock phandles (see clock bindings for details). +- spi-max-frequency: Maximum SPI clocking speed of device in Hz. + +Optional properties: +- num-cs: Number of chip selects used. + +Example: + + spi: spi@f0b00000 { + compatible = "andestech,atcspi200"; + reg = <0xf0b00000 0x1000>; + #address-cells = <1>; + #size-cells = <0>; + num-cs = <1>; + clocks = <&spiclk>; + interrupts = <3 4>; + flash@0 { + compatible = "jedec,spi-nor"; + spi-max-frequency = <50000000>; + reg = <0>; + spi-cpol; + spi-cpha; + }; + }; diff --git a/roms/u-boot/doc/device-tree-bindings/spi/spi-ath79.txt b/roms/u-boot/doc/device-tree-bindings/spi/spi-ath79.txt new file mode 100644 index 000000000..3fd9d67a2 --- /dev/null +++ b/roms/u-boot/doc/device-tree-bindings/spi/spi-ath79.txt @@ -0,0 +1,19 @@ +Binding for Qualcomm Atheros AR7xxx/AR9xxx SPI controller + +Required properties: +- compatible: has to be "qca,<soc-type>-spi", "qca,ar7100-spi" as fallback. +- reg: Base address and size of the controllers memory area +- #address-cells: <1>, as required by generic SPI binding. +- #size-cells: <0>, also as required by generic SPI binding. + +Child nodes as per the generic SPI binding. + +Example: + + spi@1f000000 { + compatible = "qca,ar9132-spi", "qca,ar7100-spi"; + reg = <0x1f000000 0x10>; + + #address-cells = <1>; + #size-cells = <0>; + }; diff --git a/roms/u-boot/doc/device-tree-bindings/spi/spi-bus.txt b/roms/u-boot/doc/device-tree-bindings/spi/spi-bus.txt new file mode 100644 index 000000000..420ec9529 --- /dev/null +++ b/roms/u-boot/doc/device-tree-bindings/spi/spi-bus.txt @@ -0,0 +1,94 @@ +SPI (Serial Peripheral Interface) busses + +SPI busses can be described with a node for the SPI master device +and a set of child nodes for each SPI slave on the bus. For this +discussion, it is assumed that the system's SPI controller is in +SPI master mode. This binding does not describe SPI controllers +in slave mode. + +The SPI master node requires the following properties: +- #address-cells - number of cells required to define a chip select + address on the SPI bus. +- #size-cells - should be zero. +- compatible - name of SPI bus controller following generic names + recommended practice. +- cs-gpios - (optional) gpios chip select. +No other properties are required in the SPI bus node. It is assumed +that a driver for an SPI bus device will understand that it is an SPI bus. +However, the binding does not attempt to define the specific method for +assigning chip select numbers. Since SPI chip select configuration is +flexible and non-standardized, it is left out of this binding with the +assumption that board specific platform code will be used to manage +chip selects. Individual drivers can define additional properties to +support describing the chip select layout. + +Optional property: +- num-cs : total number of chipselects + +If cs-gpios is used the number of chip select will automatically increased +with max(cs-gpios > hw cs) + +So if for example the controller has 2 CS lines, and the cs-gpios +property looks like this: + +cs-gpios = <&gpio1 0 0> <0> <&gpio1 1 0> <&gpio1 2 0>; + +Then it should be configured so that num_chipselect = 4 with the +following mapping: + +cs0 : &gpio1 0 0 +cs1 : native +cs2 : &gpio1 1 0 +cs3 : &gpio1 2 0 + +SPI slave nodes must be children of the SPI master node and can +contain the following properties. +- reg - (required) chip select address of device. +- compatible - (required) name of SPI device following generic names + recommended practice +- spi-max-frequency - (required) Maximum SPI clocking speed of device in Hz +- spi-cpol - (optional) Empty property indicating device requires + inverse clock polarity (CPOL) mode +- spi-cpha - (optional) Empty property indicating device requires + shifted clock phase (CPHA) mode +- spi-cs-high - (optional) Empty property indicating device requires + chip select active high +- spi-3wire - (optional) Empty property indicating device requires + 3-wire mode. +- spi-tx-bus-width - (optional) The bus width(number of data wires) that + used for MOSI. Defaults to 1 if not present. +- spi-rx-bus-width - (optional) The bus width(number of data wires) that + used for MISO. Defaults to 1 if not present. +- spi-half-duplex - (optional) Indicates that the SPI bus should wait for + a header byte before reading data from the slave. + +Some SPI controllers and devices support Dual and Quad SPI transfer mode. +It allows data in SPI system transferred in 2 wires(DUAL) or 4 wires(QUAD). +Now the value that spi-tx-bus-width and spi-rx-bus-width can receive is +only 1(SINGLE), 2(DUAL) and 4(QUAD). +Dual/Quad mode is not allowed when 3-wire mode is used. + +If a gpio chipselect is used for the SPI slave the gpio number will be passed +via the cs_gpio + +SPI example for an MPC5200 SPI bus: + spi@f00 { + #address-cells = <1>; + #size-cells = <0>; + compatible = "fsl,mpc5200b-spi","fsl,mpc5200-spi"; + reg = <0xf00 0x20>; + interrupts = <2 13 0 2 14 0>; + interrupt-parent = <&mpc5200_pic>; + + ethernet-switch@0 { + compatible = "micrel,ks8995m"; + spi-max-frequency = <1000000>; + reg = <0>; + }; + + codec@1 { + compatible = "ti,tlv320aic26"; + spi-max-frequency = <100000>; + reg = <1>; + }; + }; diff --git a/roms/u-boot/doc/device-tree-bindings/spi/spi-cadence.txt b/roms/u-boot/doc/device-tree-bindings/spi/spi-cadence.txt new file mode 100644 index 000000000..69e02c1c4 --- /dev/null +++ b/roms/u-boot/doc/device-tree-bindings/spi/spi-cadence.txt @@ -0,0 +1,31 @@ +Cadence QSPI controller device tree bindings +-------------------------------------------- + +Required properties: +- compatible : should be "cdns,qspi-nor" +- reg : 1.Physical base address and size of SPI registers map. + 2. Physical base address & size of NOR Flash. +- clocks : Clock phandles (see clock bindings for details). +- cdns,fifo-depth : Size of the data FIFO in words. +- cdns,fifo-width : Bus width of the data FIFO in bytes. +- cdns,trigger-address : 32-bit indirect AHB trigger address. +- cdns,is-decoded-cs : Flag to indicate whether decoder is used or not. +- status : enable in requried dts. + +connected flash properties +-------------------------- + +- spi-max-frequency : Max supported spi frequency. +- page-size : Flash page size. +- block-size : Flash memory block size. +- cdns,tshsl-ns : Added delay in master reference clocks (ref_clk) for + the length that the master mode chip select outputs + are de-asserted between transactions. +- cdns,tsd2d-ns : Delay in master reference clocks (ref_clk) between one + chip select being de-activated and the activation of + another. +- cdns,tchsh-ns : Delay in master reference clocks between last bit of + current transaction and de-asserting the device chip + select (n_ss_out). +- cdns,tslch-ns : Delay in master reference clocks between setting + n_ss_out low and first bit transfer diff --git a/roms/u-boot/doc/device-tree-bindings/spi/spi-mcf-dspi.txt b/roms/u-boot/doc/device-tree-bindings/spi/spi-mcf-dspi.txt new file mode 100644 index 000000000..4684d7846 --- /dev/null +++ b/roms/u-boot/doc/device-tree-bindings/spi/spi-mcf-dspi.txt @@ -0,0 +1,34 @@ +Freescale ColdFire DSPI controller + +Required properties: +- compatible : "fsl,mcf-dspi" +- #address-cells: <1>, as required by generic SPI binding +- #size-cells: <0>, also as required by generic SPI binding +- reg : offset and length of the register set for the device + +Optional properties: +- spi-max-frequency : max supported spi frequency +- num-cs : the number of the chipselect signals +- spi-mode: spi motorola mode, 0 to 3 +- ctar-params: CTAR0 to 7 register configuration, as an array + of 8 integer fields for each register, where each register + is defined as: <fmsz, pcssck, pasc, pdt, cssck, asc, dt, br>. +- fsl,spi-cs-sck-delay: a delay in nanoseconds between activating chip + select and the start of clock signal, at the start of a transfer. +- fsl,spi-sck-cs-delay: a delay in nanoseconds between stopping the clock + signal and deactivating chip select, at the end of a transfer. + +Example: + +dspi0: dspi@fc05c000 { + compatible = "fsl,mcf-dspi"; + #address-cells = <1>; + #size-cells = <0>; + reg = <0xfc05c000 0x100>; + spi-max-frequency = <50000000>; + num-cs = <4>; + spi-mode = <0>; + ctar-fields = <7, 0, 0, 0, 0, 0, 1, 6>, + <7, 0, 0, 0, 0, 0, 1, 6>, + <7, 0, 0, 0, 0, 0, 1, 6>; +}; diff --git a/roms/u-boot/doc/device-tree-bindings/spi/spi-qup.txt b/roms/u-boot/doc/device-tree-bindings/spi/spi-qup.txt new file mode 100644 index 000000000..3697df263 --- /dev/null +++ b/roms/u-boot/doc/device-tree-bindings/spi/spi-qup.txt @@ -0,0 +1,33 @@ +Qualcomm QUP SPI controller Device Tree Bindings +------------------------------------------- + +Required properties: +- compatible : Should be "qcom,spi-qup-v1.1.1", "qcom,spi-qup-v2.1.1" + or "qcom,spi-qup-v2.2.1" +- reg : Physical base address and size of SPI registers map. +- clock : Clock phandle (see clock bindings for details). +- #address-cells : Number of cells required to define a chip select + address on the SPI bus. Should be set to 1. +- #size-cells : Should be zero. +- pinctrl-names : Must be "default" +- pinctrl-n : At least one pinctrl phandle +- cs-gpios : Should specify GPIOs used for chipselects. + The gpios will be referred to as reg = <index> in the + SPI child nodes. + +Optional properties: +- num-cs : total number of chipselects + +Example: + + blsp1_spi1: spi@78b5000 { + compatible = "qcom,spi-qup-v2.2.1"; + reg = <0x78b5000 0x600>; + clock = <&gcc 23>; + #address-cells = <1>; + #size-cells = <0>; + pinctrl-names = "spi"; + pinctrl-0 = <&blsp_spi0>; + num-cs = <2>; + cs-gpios = <&soc_gpios 54 GPIO_ACTIVE_HIGH>, <&soc_gpios 4 GPIO_ACTIVE_HIGH>; + }; diff --git a/roms/u-boot/doc/device-tree-bindings/spi/spi-stm32-qspi.txt b/roms/u-boot/doc/device-tree-bindings/spi/spi-stm32-qspi.txt new file mode 100644 index 000000000..adeeb63e8 --- /dev/null +++ b/roms/u-boot/doc/device-tree-bindings/spi/spi-stm32-qspi.txt @@ -0,0 +1,44 @@ +* STMicroelectronics Quad Serial Peripheral Interface(QSPI) + +Required properties: +- compatible: should be "st,stm32f469-qspi" +- reg: the first contains the register location and length. + the second contains the memory mapping address and length +- reg-names: should contain the reg names "qspi" "qspi_mm" +- interrupts: should contain the interrupt for the device +- clocks: the phandle of the clock needed by the QSPI controller +- A pinctrl must be defined to set pins in mode of operation for QSPI transfer + +Optional properties: +- resets: must contain the phandle to the reset controller. + +A spi flash (NOR/NAND) must be a child of spi node and could have some +properties. Also see jedec,spi-nor.txt. + +Required properties: +- reg: chip-Select number (QSPI controller may connect 2 flashes) +- spi-max-frequency: max frequency of spi bus + +Optional property: +- spi-rx-bus-width: see ./spi-bus.txt for the description + +Example: + +qspi: spi@a0001000 { + compatible = "st,stm32f469-qspi"; + reg = <0xa0001000 0x1000>, <0x90000000 0x10000000>; + reg-names = "qspi", "qspi_mm"; + interrupts = <91>; + resets = <&rcc STM32F4_AHB3_RESET(QSPI)>; + clocks = <&rcc 0 STM32F4_AHB3_CLOCK(QSPI)>; + pinctrl-names = "default"; + pinctrl-0 = <&pinctrl_qspi0>; + + flash@0 { + compatible = "jedec,spi-nor"; + reg = <0>; + spi-rx-bus-width = <4>; + spi-max-frequency = <108000000>; + ... + }; +}; diff --git a/roms/u-boot/doc/device-tree-bindings/spi/spi-zynq-qspi.txt b/roms/u-boot/doc/device-tree-bindings/spi/spi-zynq-qspi.txt new file mode 100644 index 000000000..47472fdb8 --- /dev/null +++ b/roms/u-boot/doc/device-tree-bindings/spi/spi-zynq-qspi.txt @@ -0,0 +1,26 @@ +Xilinx Zynq QSPI controller Device Tree Bindings +------------------------------------------------- + +Required properties: +- compatible : Should be "xlnx,zynq-qspi-1.0". +- reg : Physical base address and size of QSPI registers map. +- interrupts : Property with a value describing the interrupt + number. +- interrupt-parent : Must be core interrupt controller +- clock-names : List of input clock names - "ref_clk", "pclk" + (See clock bindings for details). +- clocks : Clock phandles (see clock bindings for details). + +Optional properties: +- num-cs : Number of chip selects used. + +Example: + qspi@e000d000 { + compatible = "xlnx,zynq-qspi-1.0"; + clock-names = "ref_clk", "pclk"; + clocks = <&clkc 10>, <&clkc 43>; + interrupt-parent = <&intc>; + interrupts = <0 19 4>; + num-cs = <1>; + reg = <0xe000d000 0x1000>; + } ; diff --git a/roms/u-boot/doc/device-tree-bindings/spi/spi-zynq.txt b/roms/u-boot/doc/device-tree-bindings/spi/spi-zynq.txt new file mode 100644 index 000000000..cb2945789 --- /dev/null +++ b/roms/u-boot/doc/device-tree-bindings/spi/spi-zynq.txt @@ -0,0 +1,32 @@ +Cadence SPI controller Device Tree Bindings +------------------------------------------- + +Required properties: +- compatible : Should be "cdns,spi-r1p6" or "xlnx,zynq-spi-r1p6". +- reg : Physical base address and size of SPI registers map. +- interrupts : Property with a value describing the interrupt + number. +- interrupt-parent : Must be core interrupt controller +- clock-names : List of input clock names - "ref_clk", "pclk" + (See clock bindings for details). +- clocks : Clock phandles (see clock bindings for details). +- spi-max-frequency : Maximum SPI clocking speed of device in Hz + +Optional properties: +- num-cs : Number of chip selects used. + If a decoder is used, this will be the number of + chip selects after the decoder. +- is-decoded-cs : Flag to indicate whether decoder is used or not. + +Example: + + spi@e0007000 { + compatible = "xlnx,zynq-spi-r1p6"; + clock-names = "ref_clk", "pclk"; + clocks = <&clkc 26>, <&clkc 35>; + interrupt-parent = <&intc>; + interrupts = <0 49 4>; + num-cs = <4>; + is-decoded-cs = <0>; + reg = <0xe0007000 0x1000>; + } ; diff --git a/roms/u-boot/doc/device-tree-bindings/spi/spi_altera.txt b/roms/u-boot/doc/device-tree-bindings/spi/spi_altera.txt new file mode 100644 index 000000000..de4fae831 --- /dev/null +++ b/roms/u-boot/doc/device-tree-bindings/spi/spi_altera.txt @@ -0,0 +1,4 @@ +Altera SPI + +Required properties: +- compatible : should be "altr,spi-1.0". diff --git a/roms/u-boot/doc/device-tree-bindings/spmi/spmi-msm.txt b/roms/u-boot/doc/device-tree-bindings/spmi/spmi-msm.txt new file mode 100644 index 000000000..ae47673b7 --- /dev/null +++ b/roms/u-boot/doc/device-tree-bindings/spmi/spmi-msm.txt @@ -0,0 +1,26 @@ +Qualcomm SPMI arbiter/bus driver + +This is bus driver for Qualcomm chips that use SPMI to communicate with PMICs. + +Required properties: +- compatible: "qcom,spmi-pmic-arb" +- reg: Register block adresses and sizes for various parts of device: + 1) PMIC arbiter channel mapping base (PMIC_ARB_REG_CHNLn) + 2) SPMI write command (master) registers (PMIC_ARB_CORE_SW_DEC_CHANNELS) + 3) SPMI read command (observer) registers (PMIC_ARB_CORE_REGISTERS_OBS) + +Optional properties (if not set by parent): +- #address-cells: 0x1 - childs slave ID address +- #size-cells: 0x1 + +All PMICs should be placed as a child nodes of bus arbiter. +Automatic detection of childs is currently not supported. + +Example: + +spmi@200f000 { + compatible = "qcom,spmi-pmic-arb"; + reg = <0x200f800 0x200 0x2400000 0x400000 0x2c00000 0x400000>; + #address-cells = <0x1>; + #size-cells = <0x1>; +}; diff --git a/roms/u-boot/doc/device-tree-bindings/spmi/spmi-sandbox.txt b/roms/u-boot/doc/device-tree-bindings/spmi/spmi-sandbox.txt new file mode 100644 index 000000000..8569a1a84 --- /dev/null +++ b/roms/u-boot/doc/device-tree-bindings/spmi/spmi-sandbox.txt @@ -0,0 +1,31 @@ +Sandbox SPMI emulated arbiter. + +This is bus driver for Sandbox. It includes part of emulated pm8916 pmic. + +Required properties: +- compatible: "sandbox,spmi" +- #address-cells: 0x1 - childs slave ID address +- #size-cells: 0x1 + +Example: + +spmi: spmi@0 { + compatible = "sandbox,spmi"; + #address-cells = <0x1>; + #size-cells = <0x1>; + pm8916@0 { + compatible = "qcom,spmi-pmic"; + reg = <0x0 0x1>; + #address-cells = <0x1>; + #size-cells = <0x1>; + + spmi_gpios: gpios@c000 { + compatible = "qcom,pm8916-gpio"; + reg = <0xc000 0x400>; + gpio-controller; + gpio-count = <4>; + #gpio-cells = <2>; + gpio-bank-name="spmi"; + }; + }; +}; diff --git a/roms/u-boot/doc/device-tree-bindings/sysinfo/gdsys,sysinfo_gazerbeam.txt b/roms/u-boot/doc/device-tree-bindings/sysinfo/gdsys,sysinfo_gazerbeam.txt new file mode 100644 index 000000000..f70652d3c --- /dev/null +++ b/roms/u-boot/doc/device-tree-bindings/sysinfo/gdsys,sysinfo_gazerbeam.txt @@ -0,0 +1,46 @@ +gdsys Gazerbeam sysinfo driver + +This driver provides capabilities to access the gdsys Gazerbeam board's device +information. Furthermore, phandles to some internal devices are provided for +the board files. + +Required properties: +- compatible: should be "gdsys,sysinfo-gazerbeam" +- csb: phandle to the board's coherent system bus (CSB) device node +- rxaui[0-3]: phandles to the rxaui control device nodes +- fpga[0-1]: phandles to the board's gdsys FPGA device nodes +- ioep[0-1]: phandles to the board's IO endpoint device nodes +- ver-gpios: GPIO list to read the hardware version from +- var-gpios: GPIO list to read the hardware variant information from +- reset-gpios: GPIO list for the board's reset GPIOs + +Example: + + +sysinfo { + compatible = "gdsys,sysinfo-gazerbeam"; + csb = <&board_soc>; + serdes = <&SERDES>; + rxaui0 = <&RXAUI0>; + rxaui1 = <&RXAUI1>; + rxaui2 = <&RXAUI2>; + rxaui3 = <&RXAUI3>; + fpga0 = <&FPGA0>; + fpga1 = <&FPGA1>; + ioep0 = <&IOEP0>; + ioep1 = <&IOEP1>; + + ver-gpios = <&PPCPCA 12 0 + &PPCPCA 13 0 + &PPCPCA 14 0 + &PPCPCA 15 0>; + + /* MC2/SC-Board */ + var-gpios-mc2 = <&GPIO_VB0 0 0 /* VAR-MC_SC */ + &GPIO_VB0 11 0>; /* VAR-CON */ + /* MC4-Board */ + var-gpios-mc4 = <&GPIO_VB1 0 0 /* VAR-MC_SC */ + &GPIO_VB1 11 0>; /* VAR-CON */ + + reset-gpios = <&gpio0 1 0 &gpio0 2 1>; +}; diff --git a/roms/u-boot/doc/device-tree-bindings/sysinfo/google,coral.txt b/roms/u-boot/doc/device-tree-bindings/sysinfo/google,coral.txt new file mode 100644 index 000000000..d8a1a7968 --- /dev/null +++ b/roms/u-boot/doc/device-tree-bindings/sysinfo/google,coral.txt @@ -0,0 +1,37 @@ +Google Coral sysinfo information +================================ + +This binding allows information about the board to be described. It includes +the SMBIOS binding as well. + +Required properties: + + - compatible: "google,coral" + - recovery-gpios: GPIO to use for recovery button (-1 if none) + - wite-protect-gpios: GPIO to use for write-protect screw + - phase-enforce-gpios: GPIO to indicate the board is in final ship mode + - memconfig-gpios: 4 GPIOs to use to read memory config (as base2 int) + +Optional properties: + - skuconfig-gpios: 2 GPIOs to use to read SKU ID. If not present, the + Chromium OS EC SKU_ID is used instead + +Example: + +board: board { + compatible = "google,coral"; + recovery-gpios = <&gpio_nw (-1) GPIO_ACTIVE_LOW>; + write-protect-gpios = <&gpio_nw GPIO_75 GPIO_ACTIVE_HIGH>; + phase-enforce-gpios = <&gpio_n GPIO_10 GPIO_ACTIVE_HIGH>; + memconfig-gpios = <&gpio_nw GPIO_101 GPIO_ACTIVE_HIGH + &gpio_nw GPIO_102 GPIO_ACTIVE_HIGH + &gpio_n GPIO_38 GPIO_ACTIVE_HIGH + &gpio_n GPIO_45 GPIO_ACTIVE_HIGH>; + + /* + * This is used for reef only: + * + * skuconfig-gpios = <&gpio_nw GPIO_16 GPIO_ACTIVE_HIGH + * &gpio_nw GPIO_17 GPIO_ACTIVE_HIGH>; + */ + }; diff --git a/roms/u-boot/doc/device-tree-bindings/sysinfo/gpio-sysinfo.txt b/roms/u-boot/doc/device-tree-bindings/sysinfo/gpio-sysinfo.txt new file mode 100644 index 000000000..b5739d94e --- /dev/null +++ b/roms/u-boot/doc/device-tree-bindings/sysinfo/gpio-sysinfo.txt @@ -0,0 +1,37 @@ +GPIO-based Sysinfo device + +This binding describes several GPIOs which specify a board revision. Each GPIO +forms a digit in a ternary revision number. This revision is then mapped to a +name using the revisions and names properties. + +Each GPIO may be floating, pulled-up, or pulled-down, mapping to digits 2, 1, +and 0, respectively. The first GPIO forms the least-significant digit of the +revision. For example, consider the property + + gpios = <&gpio 0>, <&gpio 1>, <&gpio 2>; + +If GPIO 0 is pulled-up, GPIO 1 is pulled-down, and GPIO 2 is floating, then the +revision would be + + 0t201 = 2*9 + 0*3 + 1*3 = 19 + +If instead GPIO 0 is floating, GPIO 1 is pulled-up, and GPIO 2 is pulled-down, +then the revision would be + + 0t012 = 0*9 + 1*3 + 2*1 = 5 + +Required properties: +- compatible: should be "gpio-sysinfo". +- gpios: should be a list of gpios forming the revision number, + least-significant-digit first +- revisions: a list of known revisions; any revisions not present will have the + name "unknown" +- names: the name of each revision in revisions + +Example: +sysinfo { + compatible = "gpio-sysinfo"; + gpios = <&gpio_a 15>, <&gpio_a 16>, <&gpio_a 17>; + revisions = <19>, <5>; + names = "rev_a", "foo"; +}; diff --git a/roms/u-boot/doc/device-tree-bindings/sysinfo/smbios.txt b/roms/u-boot/doc/device-tree-bindings/sysinfo/smbios.txt new file mode 100644 index 000000000..b52232280 --- /dev/null +++ b/roms/u-boot/doc/device-tree-bindings/sysinfo/smbios.txt @@ -0,0 +1,77 @@ +SMBIOS sysinfo information +========================== + +This binding allows the values for the SMBIOS tables to be specified in the +devicetree, as below. + +Required properties: + + - compatible: "u-boot,smbios" or any other string depending on your board + +This driver allows providing board-specific features such as power control +GPIOs. In addition, the SMBIOS values can be specified in the device tree, +as below: + +An optional 'smbios' subnode can be used to provide these properties. Within +that, the properties are broken down by table type, as in the System Management +BIOS (Basic Input/Output System) Specification. + +Available subnodes for each table type are: + + - 1 : system + - 2 : baseboard + - 3 : chassis + +Within each subnode the following tables are recognised: + +"system" subnode optional properties: + + - manufacturer: Product manufacturer for system + - product: Product name + - version: Product version string + - serial: Serial number for system (note that this can be overridden by + the serial# environment variable) + - sku: Product SKU (Stock-Keeping Unit) + - family: Product family + +"baseboard" subnode optional properties: + + - manufacturer: Product manufacturer for baseboard + - product: Product name + - asset-tag: Asset tag for the motherboard, sometimes used in organisations + to track devices + +"chassis" subnode optional properties: + + - manufacturer: Product manufacturer for chassis + + +Example: + +sysinfo { + compatible = "sandbox,sysinfo-sandbox"; + + smbios { + /* Type 1 table */ + system { + manufacturer = "Google"; + product = "Coral"; + version = "rev2"; + serial = "123456789"; + sku = "sku3"; + family = "Google_Coral"; + }; + + /* Type 2 table */ + baseboard { + manufacturer = "Google"; + product = "Coral"; + asset-tag = "ABC123"; + }; + + /* Type 3 table */ + chassis { + manufacturer = "Google"; + }; + }; +}; diff --git a/roms/u-boot/doc/device-tree-bindings/sysinfo/sysinfo.txt b/roms/u-boot/doc/device-tree-bindings/sysinfo/sysinfo.txt new file mode 100644 index 000000000..9445031b1 --- /dev/null +++ b/roms/u-boot/doc/device-tree-bindings/sysinfo/sysinfo.txt @@ -0,0 +1,19 @@ +Sysinfo +======= + +This provides capabilities to access information about a board/system, for +use by drivers. + +Required properties: + + - compatible: any suitable string where the driver is in the UCLASS_SYSINFO + class + +See also smbios.txt + + +Example + +sysinfo { + compatible = "sandbox,sysinfo-sandbox"; +}; diff --git a/roms/u-boot/doc/device-tree-bindings/sysreset/ti,sci-sysreset.txt b/roms/u-boot/doc/device-tree-bindings/sysreset/ti,sci-sysreset.txt new file mode 100644 index 000000000..02704c648 --- /dev/null +++ b/roms/u-boot/doc/device-tree-bindings/sysreset/ti,sci-sysreset.txt @@ -0,0 +1,29 @@ +Texas Instruments TI SCI System Reset Controller +================================================ + +Some TI SoCs contain a system controller (like the SYSFW, etc...) that is +responsible for controlling the state of the IPs that are present. +Communication between the host processor running an OS and the system +controller happens through a protocol known as TI SCI [1]. + +[1] http://processors.wiki.ti.com/index.php/TISCI + +System Reset Controller Node +============================ +The sysreset controller node represents the reset for the overall SoC +which is managed by the SYSFW. Because this relies on the TI SCI protocol +to communicate with the SYSFW it must be a child of the sysfw node. + +Required Properties: +-------------------- + - compatible: Must be "ti,sci-sysreset" + +Example (AM65x): +---------------- + sysfw: sysfw { + compatible = "ti,am654-system-controller"; + ... + k3_sysreset: sysreset-controller { + compatible = "ti,sci-sysreset"; + }; + }; diff --git a/roms/u-boot/doc/device-tree-bindings/thermal/rockchip-thermal.txt b/roms/u-boot/doc/device-tree-bindings/thermal/rockchip-thermal.txt new file mode 100644 index 000000000..ef802de49 --- /dev/null +++ b/roms/u-boot/doc/device-tree-bindings/thermal/rockchip-thermal.txt @@ -0,0 +1,68 @@ +* Temperature Sensor ADC (TSADC) on rockchip SoCs + +Required properties: +- compatible : "rockchip,rk3288-tsadc" +- reg : physical base address of the controller and length of memory mapped + region. +- interrupts : The interrupt number to the cpu. The interrupt specifier format + depends on the interrupt controller. +- clocks : Must contain an entry for each entry in clock-names. +- clock-names : Shall be "tsadc" for the converter-clock, and "apb_pclk" for + the peripheral clock. +- resets : Must contain an entry for each entry in reset-names. + See ../reset/reset.txt for details. +- reset-names : Must include the name "tsadc-apb". +- #thermal-sensor-cells : Should be 1. See ./thermal.txt for a description. +- rockchip,hw-tshut-temp : The hardware-controlled shutdown temperature value. +- rockchip,hw-tshut-mode : The hardware-controlled shutdown mode 0:CRU 1:GPIO. +- rockchip,hw-tshut-polarity : The hardware-controlled active polarity 0:LOW + 1:HIGH. + +Exiample: +tsadc: tsadc@ff280000 { + compatible = "rockchip,rk3288-tsadc"; + reg = <0xff280000 0x100>; + interrupts = <GIC_SPI 37 IRQ_TYPE_LEVEL_HIGH>; + clocks = <&cru SCLK_TSADC>, <&cru PCLK_TSADC>; + clock-names = "tsadc", "apb_pclk"; + resets = <&cru SRST_TSADC>; + reset-names = "tsadc-apb"; + pinctrl-names = "default"; + pinctrl-0 = <&otp_out>; + #thermal-sensor-cells = <1>; + rockchip,hw-tshut-temp = <95000>; + rockchip,hw-tshut-mode = <0>; + rockchip,hw-tshut-polarity = <0>; +}; + +Example: referring to thermal sensors: +thermal-zones { + cpu_thermal: cpu_thermal { + polling-delay-passive = <1000>; /* milliseconds */ + polling-delay = <5000>; /* milliseconds */ + + /* sensor ID */ + thermal-sensors = <&tsadc 1>; + + trips { + cpu_alert0: cpu_alert { + temperature = <70000>; /* millicelsius */ + hysteresis = <2000>; /* millicelsius */ + type = "passive"; + }; + cpu_crit: cpu_crit { + temperature = <90000>; /* millicelsius */ + hysteresis = <2000>; /* millicelsius */ + type = "critical"; + }; + }; + + cooling-maps { + map0 { + trip = <&cpu_alert0>; + cooling-device = + <&cpu0 THERMAL_NO_LIMIT THERMAL_NO_LIMIT>; + }; + }; + }; +}; diff --git a/roms/u-boot/doc/device-tree-bindings/thermal/ti_soc_thermal.txt b/roms/u-boot/doc/device-tree-bindings/thermal/ti_soc_thermal.txt new file mode 100644 index 000000000..b4e88c2d1 --- /dev/null +++ b/roms/u-boot/doc/device-tree-bindings/thermal/ti_soc_thermal.txt @@ -0,0 +1,35 @@ +* Texas Instrument dra7xx SCM bandgap bindings + +In the System Control Module, SoC supplies a voltage reference +and a temperature sensor feature that are gathered in the band +gap voltage and temperature sensor (VBGAPTS) module. The band +gap provides current and voltage reference for its internal +circuits and other analog IP blocks. The analog-to-digital +converter (ADC) produces an output value that is proportional +to the silicon temperature. + +Required properties: +- compatible : Should be: + - "ti,dra752-bandgap" +- interrupts : this entry should indicate which interrupt line +the talert signal is routed to; +- regs : this is specific to each bandgap version, because +the mapping may change from soc to soc, apart from depending +on available features. + +Optional: +- gpios : this entry should be used to inform which GPIO +line the tshut signal is routed to. The informed GPIO will +be treated as an IRQ; + +Example: +bandgap { + reg = <0x4a0021e0 0xc + 0x4a00232c 0xc + 0x4a002380 0x2c + 0x4a0023C0 0x3c + 0x4a002564 0x8 + 0x4a002574 0x50>; + compatible = "ti,dra752-bandgap"; + interrupts = <0 126 4>; /* talert */ +}; diff --git a/roms/u-boot/doc/device-tree-bindings/timer/altera_timer.txt b/roms/u-boot/doc/device-tree-bindings/timer/altera_timer.txt new file mode 100644 index 000000000..904a5846d --- /dev/null +++ b/roms/u-boot/doc/device-tree-bindings/timer/altera_timer.txt @@ -0,0 +1,19 @@ +Altera Timer + +Required properties: + +- compatible : should be "altr,timer-1.0" +- reg : Specifies base physical address and size of the registers. +- interrupt-parent: phandle of the interrupt controller +- interrupts : Should contain the timer interrupt number +- clock-frequency : The frequency of the clock that drives the counter, in Hz. + +Example: + +timer { + compatible = "altr,timer-1.0"; + reg = <0x00400000 0x00000020>; + interrupt-parent = <&cpu>; + interrupts = <11>; + clock-frequency = <125000000>; +}; diff --git a/roms/u-boot/doc/device-tree-bindings/timer/arc_timer.txt b/roms/u-boot/doc/device-tree-bindings/timer/arc_timer.txt new file mode 100644 index 000000000..5493b21d2 --- /dev/null +++ b/roms/u-boot/doc/device-tree-bindings/timer/arc_timer.txt @@ -0,0 +1,24 @@ +ARC Timer + +Required properties: + +- compatible : should be "snps,arc-timer". +- reg : Specifies timer ID, could be either 0 or 1. +- clocks : Specifies clocks that drives the counter. + +Examples: + +timer@0 { + compatible = "snps,arc-timer"; + clocks = <&core_clk>; + reg = <0>; +}; + +timer@1 { + compatible = "snps,arc-timer"; + clocks = <&core_clk>; + reg = <1>; +}; + +NOTE: if you specify both timers, clocks always should be the same +as each timer is driven by the same core clock. diff --git a/roms/u-boot/doc/device-tree-bindings/timer/atcpit100_timer.txt b/roms/u-boot/doc/device-tree-bindings/timer/atcpit100_timer.txt new file mode 100644 index 000000000..620814e94 --- /dev/null +++ b/roms/u-boot/doc/device-tree-bindings/timer/atcpit100_timer.txt @@ -0,0 +1,31 @@ +Andestech ATCPIT100 timer +------------------------------------------------------------------ +ATCPIT100 is a generic IP block from Andes Technology, embedded in +Andestech AE3XX, AE250 platforms and other designs. + +This timer is a set of compact multi-function timers, which can be +used as pulse width modulators (PWM) as well as simple timers. + +It supports up to 4 PIT channels. Each PIT channel is a +multi-function timer and provide the following usage scenarios: +One 32-bit timer +Two 16-bit timers +Four 8-bit timers +One 16-bit PWM +One 16-bit timer and one 8-bit PWM +Two 8-bit timer and one 8-bit PWM + +Required properties: +- compatible : Should be "andestech,atcpit100" +- reg : Address and length of the register set +- interrupts : Reference to the timer interrupt +- clock-frequency : The rate in HZ in input of the Andestech ATCPIT100 timer + +Examples: + +timer0: timer@f0400000 { + compatible = "andestech,atcpit100"; + reg = <0xf0400000 0x1000>; + interrupts = <2 4>; + clock-frequency = <30000000>; +}: diff --git a/roms/u-boot/doc/device-tree-bindings/timer/fsl,mpc83xx-timer.txt b/roms/u-boot/doc/device-tree-bindings/timer/fsl,mpc83xx-timer.txt new file mode 100644 index 000000000..608d24110 --- /dev/null +++ b/roms/u-boot/doc/device-tree-bindings/timer/fsl,mpc83xx-timer.txt @@ -0,0 +1,21 @@ +MPC83xx timer devices + +MPC83xx SoCs offer a decrementer interrupt that can be used to implement delay +functionality, and periodically triggered actions. + +Required properties: +- compatible: must be "fsl,mpc83xx-timer" +- clocks: must be a reference to the system's CSB (coherent system bus) clock, + provided by one of the "fsl,mpc83xx-clk" devices + +Example: + +socclocks: clocks { + compatible = "fsl,mpc832x-clk"; + #clock-cells = <1>; +}; + +timer { + compatible = "fsl,mpc83xx-timer"; + clocks = <&socclocks MPC83XX_CLK_CSB>; +}; diff --git a/roms/u-boot/doc/device-tree-bindings/timer/sandbox_timer.txt b/roms/u-boot/doc/device-tree-bindings/timer/sandbox_timer.txt new file mode 100644 index 000000000..3e113f83f --- /dev/null +++ b/roms/u-boot/doc/device-tree-bindings/timer/sandbox_timer.txt @@ -0,0 +1,7 @@ +Sandbox timer + +The sandbox timer device is an emulated device which gets time from +host os. + +Required properties: + compatible: "sandbox,timer" diff --git a/roms/u-boot/doc/device-tree-bindings/tpm2/sandbox.txt b/roms/u-boot/doc/device-tree-bindings/tpm2/sandbox.txt new file mode 100644 index 000000000..3d0f727cc --- /dev/null +++ b/roms/u-boot/doc/device-tree-bindings/tpm2/sandbox.txt @@ -0,0 +1,11 @@ +Sandbox TPMv2.0 bindings +------------------------ + +Required properties: +- compatible : Should be "sandbox,tpm2" + +Example: + + tpm { + compatible = "sandbox,tpm2"; + }; diff --git a/roms/u-boot/doc/device-tree-bindings/tpm2/tis-tpm2-spi.txt b/roms/u-boot/doc/device-tree-bindings/tpm2/tis-tpm2-spi.txt new file mode 100644 index 000000000..3a2ee4bd1 --- /dev/null +++ b/roms/u-boot/doc/device-tree-bindings/tpm2/tis-tpm2-spi.txt @@ -0,0 +1,18 @@ +ST33TPHF20 SPI TPMv2.0 bindings +------------------------------- + +Required properties: +- compatible : Should be "tcg,tpm_tis-spi" +- reg : SPI Chip select + +Optional properties: +- gpio-reset : Reset GPIO (if not connected to the SoC reset line) +- spi-max-frequency : See spi-bus.txt + +Example: + + tpm@1 { + compatible = "tcg,tpm_tis-spi"; + reg = <1>; + spi-max-frequency = <10000000>; + }; diff --git a/roms/u-boot/doc/device-tree-bindings/usb/dwc2.txt b/roms/u-boot/doc/device-tree-bindings/usb/dwc2.txt new file mode 100644 index 000000000..61493f7cb --- /dev/null +++ b/roms/u-boot/doc/device-tree-bindings/usb/dwc2.txt @@ -0,0 +1,58 @@ +Platform DesignWare HS OTG USB 2.0 controller +----------------------------------------------------- + +Required properties: +- compatible : One of: + - brcm,bcm2835-usb: The DWC2 USB controller instance in the BCM2835 SoC. + - hisilicon,hi6220-usb: The DWC2 USB controller instance in the hi6220 SoC. + - rockchip,rk3066-usb: The DWC2 USB controller instance in the rk3066 Soc; + - "rockchip,px30-usb", "rockchip,rk3066-usb", "snps,dwc2": for px30 Soc; + - "rockchip,rk3188-usb", "rockchip,rk3066-usb", "snps,dwc2": for rk3188 Soc; + - "rockchip,rk3288-usb", "rockchip,rk3066-usb", "snps,dwc2": for rk3288 Soc; + - "lantiq,arx100-usb": The DWC2 USB controller instance in Lantiq ARX SoCs; + - "lantiq,xrx200-usb": The DWC2 USB controller instance in Lantiq XRX SoCs; + - "amlogic,meson8-usb": The DWC2 USB controller instance in Amlogic Meson8 SoCs; + - "amlogic,meson8b-usb": The DWC2 USB controller instance in Amlogic Meson8b SoCs; + - "amlogic,meson-gxbb-usb": The DWC2 USB controller instance in Amlogic S905 SoCs; + - "amcc,dwc-otg": The DWC2 USB controller instance in AMCC Canyonlands 460EX SoCs; + - snps,dwc2: A generic DWC2 USB controller with default parameters. + - "st,stm32f4x9-fsotg": The DWC2 USB FS/HS controller instance in STM32F4x9 SoCs + configured in FS mode; + - "st,stm32f4x9-hsotg": The DWC2 USB HS controller instance in STM32F4x9 SoCs + configured in HS mode; + - "st,stm32f7-hsotg": The DWC2 USB HS controller instance in STM32F7 SoCs + configured in HS mode; +- reg : Should contain 1 register range (address and length) +- interrupts : Should contain 1 interrupt +- clocks: clock provider specifier +- clock-names: shall be "otg" +Refer to clk/clock-bindings.txt for generic clock consumer properties + +Optional properties: +- phys: phy provider specifier +- phy-names: shall be "usb2-phy" +Refer to phy/phy-bindings.txt for generic phy consumer properties +- dr_mode: shall be one of "host", "peripheral" and "otg" + Refer to usb/generic.txt +- g-rx-fifo-size: size of rx fifo size in gadget mode. +- g-np-tx-fifo-size: size of non-periodic tx fifo size in gadget mode. +- g-tx-fifo-size: size of periodic tx fifo per endpoint (except ep0) in gadget mode. +- usb33d-supply: external VBUS and ID sensing comparators supply, in order to + perform OTG operation, used on STM32MP1 SoCs. +- u-boot,force-b-session-valid: force B-peripheral session instead of relying on + VBUS sensing (only valid when dr_mode = "peripheral" and for u-boot). + +Deprecated properties: +- g-use-dma: gadget DMA mode is automatically detected + +Example: + + usb@101c0000 { + compatible = "ralink,rt3050-usb, snps,dwc2"; + reg = <0x101c0000 40000>; + interrupts = <18>; + clocks = <&usb_otg_ahb_clk>; + clock-names = "otg"; + phys = <&usbphy>; + phy-names = "usb2-phy"; + }; diff --git a/roms/u-boot/doc/device-tree-bindings/usb/dwc3-st.txt b/roms/u-boot/doc/device-tree-bindings/usb/dwc3-st.txt new file mode 100644 index 000000000..a26a1397e --- /dev/null +++ b/roms/u-boot/doc/device-tree-bindings/usb/dwc3-st.txt @@ -0,0 +1,60 @@ +ST DWC3 glue logic + +This file documents the parameters for the dwc3-st driver. +This driver controls the glue logic used to configure the dwc3 core on +STiH407 based platforms. + +Required properties: + - compatible : must be "st,stih407-dwc3" + - reg : glue logic base address and USB syscfg ctrl register offset + - reg-names : should be "reg-glue" and "syscfg-reg" + - st,syscon : should be phandle to system configuration node which + encompasses the glue registers + - resets : list of phandle and reset specifier pairs. There should be two entries, one + for the powerdown and softreset lines of the usb3 IP + - reset-names : list of reset signal names. Names should be "powerdown" and "softreset" + + - #address-cells, #size-cells : should be '1' if the device has sub-nodes + with 'reg' property + + - pinctl-names : A pinctrl state named "default" must be defined + + - pinctrl-0 : Pin control group + + - ranges : allows valid 1:1 translation between child's address space and + parent's address space + +Sub-nodes: +The dwc3 core should be added as subnode to ST DWC3 glue as shown in the +example below. + +NB: The dr_mode property is NOT optional for this driver, as the default value +is "otg", which isn't supported by this SoC. Valid dr_mode values for dwc3-st are +either "host" or "device". + +Example: + +st_dwc3: dwc3@8f94000 { + status = "disabled"; + compatible = "st,stih407-dwc3"; + reg = <0x08f94000 0x1000>, <0x110 0x4>; + reg-names = "reg-glue", "syscfg-reg"; + st,syscfg = <&syscfg_core>; + resets = <&powerdown STIH407_USB3_POWERDOWN>, + <&softreset STIH407_MIPHY2_SOFTRESET>; + reset-names = "powerdown", "softreset"; + #address-cells = <1>; + #size-cells = <1>; + pinctrl-names = "default"; + pinctrl-0 = <&pinctrl_usb3>; + ranges; + + dwc3: dwc3@9900000 { + compatible = "snps,dwc3"; + reg = <0x09900000 0x100000>; + interrupts = <GIC_SPI 155 IRQ_TYPE_NONE>; + dr_mode = "host"; + phy-names = "usb2-phy", "usb3-phy"; + phys = <&usb2_picophy2>, <&phy_port2 PHY_TYPE_USB3>; + }; +}; diff --git a/roms/u-boot/doc/device-tree-bindings/usb/ehci-msm.txt b/roms/u-boot/doc/device-tree-bindings/usb/ehci-msm.txt new file mode 100644 index 000000000..205bb0722 --- /dev/null +++ b/roms/u-boot/doc/device-tree-bindings/usb/ehci-msm.txt @@ -0,0 +1,10 @@ +Chipidea EHCI controller (part of OTG controller) used on Qualcomm devices. + +Required properties: +- compatible: must be "qcom,ehci-host" +- reg: start address and size of the registers + +ehci@78d9000 { + compatible = "qcom,ehci-host"; + reg = <0x78d9000 0x400>; +}; diff --git a/roms/u-boot/doc/device-tree-bindings/usb/generic.txt b/roms/u-boot/doc/device-tree-bindings/usb/generic.txt new file mode 100644 index 000000000..a02a198df --- /dev/null +++ b/roms/u-boot/doc/device-tree-bindings/usb/generic.txt @@ -0,0 +1,31 @@ +Generic USB Properties + +Optional properties: + - maximum-speed: tells USB controllers we want to work up to a certain + speed. Valid arguments are "super-speed-plus", + "super-speed", "high-speed", "full-speed" and + "low-speed". In case this isn't passed via DT, USB + controllers should default to their maximum HW + capability. + - dr_mode: tells Dual-Role USB controllers that we want to work on a + particular mode. Valid arguments are "host", + "peripheral" and "otg". In case this attribute isn't + passed via DT, USB DRD controllers should default to + OTG. + - phy_type: tells USB controllers that we want to configure the core to support + a UTMI+ PHY with an 8- or 16-bit interface if UTMI+ is + selected. Valid arguments are "utmi" and "utmi_wide". + In case this isn't passed via DT, USB controllers should + default to HW capability. + +This is an attribute to a USB controller such as: + +dwc3@4a030000 { + compatible = "synopsys,dwc3"; + reg = <0x4a030000 0xcfff>; + interrupts = <0 92 4> + usb-phy = <&usb2_phy>, <&usb3,phy>; + maximum-speed = "super-speed"; + dr_mode = "otg"; + phy_type = "utmi_wide"; +}; diff --git a/roms/u-boot/doc/device-tree-bindings/usb/marvell.xhci-usb.txt b/roms/u-boot/doc/device-tree-bindings/usb/marvell.xhci-usb.txt new file mode 100644 index 000000000..e042d1b96 --- /dev/null +++ b/roms/u-boot/doc/device-tree-bindings/usb/marvell.xhci-usb.txt @@ -0,0 +1,28 @@ +Marvell SOC USB controllers + +This controller is integrated in Armada 3700/8K. +It uses the same properties as a generic XHCI host controller + +Required properties : + - compatible: should be one or more of: + - "marvell,armada3700-xhci", "generic-xhci" for Armada 37xx SoCs + - "marvell,armada-8k-xhci", "generic-xhci" for Armada A8K SoCs + - reg: should contain address and length of the standard XHCI + register set for the device. + - interrupts: one XHCI interrupt should be described here. + +Optional properties: + - clocks: phandle to system controller clock driving this unit + - vbus-supply : If present, specifies the fixed regulator to be turned on + for providing power to the USB VBUS rail. + +Example: + cpm_usb3_0: usb3@500000 { + compatible = "marvell,armada-8k-xhci", + "generic-xhci"; + reg = <0x500000 0x4000>; + interrupts = <GIC_SPI 62 IRQ_TYPE_LEVEL_HIGH>; + clocks = <&cpm_syscon0 1 22>; + vbus-supply = <®_usb3h0_vbus>; + status = "disabled"; + }; diff --git a/roms/u-boot/doc/device-tree-bindings/usb/mediatek,mtk-xhci.txt b/roms/u-boot/doc/device-tree-bindings/usb/mediatek,mtk-xhci.txt new file mode 100644 index 000000000..2a298f7b1 --- /dev/null +++ b/roms/u-boot/doc/device-tree-bindings/usb/mediatek,mtk-xhci.txt @@ -0,0 +1,44 @@ +MediaTek xHCI + +The device node for USB3 host controller on MediaTek SoCs. + +Required properties: + - compatible : should be "mediatek,mtk-xhci" + - reg : specifies physical base address and size of the registers + - reg-names: should be "mac" for xHCI MAC and "ippc" for IP port control + - power-domains : a phandle to USB power domain node to control USB's + MTCMOS + - vusb33-supply : regulator of USB avdd3.3v + + - clocks : a list of phandle + clock-specifier pairs, one for each + entry in clock-names + - clock-names : must contain + "sys_ck": controller clock used by normal mode, + the following ones are optional: + "ref_ck": reference clock used by low power mode etc, + "mcu_ck": mcu_bus clock for register access, + "dma_ck": dma_bus clock for data transfer by DMA, + "xhci_ck": controller clock + + - phys : list of all the USB PHYs on this HCD + - phy-names: name specifier for the USB PHY + +Optional properties: + - vbus-supply : reference to the VBUS regulator; + - mediatek,u3p-dis-msk : mask to disable u3ports, bit0 for u3port0, + bit1 for u3port1, ... etc; + - mediatek,u2p-dis-msk : mask to disable u2ports, bit0 for u2port0, + bit1 for u2port1, ... etc; + +Example: +xhci: usb@1a0c0000 { + compatible = "mediatek,mt7629-xhci", "mediatek,mtk-xhci"; + reg = <0x1a0c0000 0x1000>, <0x1a0c3e00 0x0100>; + reg-names = "mac", "ippc"; + power-domains = <&scpsys MT7629_POWER_DOMAIN_HIF1>; + clocks = <&ssusbsys CLK_SSUSB_SYS_EN>, <&ssusbsys CLK_SSUSB_REF_EN>, + <&ssusbsys CLK_SSUSB_MCU_EN>, <&ssusbsys CLK_SSUSB_DMA_EN>; + clock-names = "sys_ck", "ref_ck", "mcu_ck", "dma_ck"; + phys = <&u2port0 PHY_TYPE_USB2>, <&u3port0 PHY_TYPE_USB3>; + status = "disabled"; +}; diff --git a/roms/u-boot/doc/device-tree-bindings/usb/mediatek,mtu3.txt b/roms/u-boot/doc/device-tree-bindings/usb/mediatek,mtu3.txt new file mode 100644 index 000000000..ab877bfa8 --- /dev/null +++ b/roms/u-boot/doc/device-tree-bindings/usb/mediatek,mtu3.txt @@ -0,0 +1,79 @@ +The device node for Mediatek USB3 DRD controller + +Required properties: + - compatible : should be "mediatek,<soc-model>-mtu3", "mediatek,mtu3", + soc-model is the name of SoC, such as mt8512 etc, + when using "mediatek,mtu3" compatible string, you need SoC specific + ones in addition, one of: + - "mediatek,mt8512-mtu3" + - reg : specifies physical base address and size of the registers + - reg-names: should be + - "ippc" : IP Port Control + - power-domains : a phandle to USB power domain node to control USB's MTCMOS + - clocks : a list of phandle + clock-specifier pairs, one for each + entry in clock-names + - clock-names : must contain "sys_ck" for clock of controller, + the following clocks are optional: + "ref_ck", "mcu_ck", "dma_ck" and "xhci_ck"; + - phys : list of all the USB PHYs on this HCD + - #address-cells, #size-cells : used for sub-nodes with 'reg' property + - ranges : allows valid 1:1 translation between child's address space and + parent's address space + +Optional properties: + - vusb33-supply : regulator of USB AVDD3.3v + - vbus-supply : regulator of VBUS 5v, needed when supports host mode. + +Sub-nodes: +Required properties: + - compatible : should be "mediatek,ssusb" + - reg : specifies physical base address and size of the registers + - reg-names: should be + - "mac" : SSUSB MAC, include xHCI and device + - interrupts : interrupt used by xHCI or device + - dr_mode : should be one of "host" or "peripheral", + see : usb/generic.txt + +Optional properties: + - pinctrl-names : a pinctrl state named "default" is optional + - pinctrl-0 : pin control group + See: pinctrl/pinctrl-bindings.txt + + - device mode: + - maximum-speed : valid arguments are "full-speed", "high-speed", + "super-speed" and "super-speed-plus", + see: usb/generic.txt + - mediatek,force-vbus : force vbus as valid by SW + + - host mode (dr_mode is "host"): + - mediatek,u3p-dis-msk : mask to disable u3ports, bit0 for u3port0, + bit1 for u3port1, ... etc; + +Example: +usb3: usb@11213e00 { + compatible = "mediatek,mt8512-mtu3", "mediatek,mtu3"; + reg = <0x11213e00 0x0100>; + reg-names = "ippc"; + phys = <&u2port0 PHY_TYPE_USB2>, <&u2port1 PHY_TYPE_USB2>; + power-domains = <&scpsys MT8512_POWER_DOMAIN_USB>; + clocks = <&infracfg CLK_INFRA_USB_SYS>, + <&topckgen CLK_TOP_SSUSB_TOP_CK_EN>, + <&infracfg CLK_INFRA_ICUSB>; + clock-names = "sys_ck", "ref_ck", "mcu_ck"; + vusb33-supply = <reg_3p3v>; + vbus-supply = <&usb_p0_vbus>; + #address-cells = <1>; + #size-cells = <1>; + ranges; + status = "disabled"; + + ssusb: usb@11210000 { + compatible = "mediatek,ssusb"; + reg = <0x11210000 0x3e00>; + interrupts = <GIC_SPI 16 IRQ_TYPE_LEVEL_LOW>; + reg-names = "mac"; + dr_mode = "peripheral"; + maximum-speed = "high-speed"; + status = "disabled"; + }; +}; diff --git a/roms/u-boot/doc/device-tree-bindings/usb/tegra-usb.txt b/roms/u-boot/doc/device-tree-bindings/usb/tegra-usb.txt new file mode 100644 index 000000000..5282d44ac --- /dev/null +++ b/roms/u-boot/doc/device-tree-bindings/usb/tegra-usb.txt @@ -0,0 +1,25 @@ +Tegra SOC USB controllers + +The device node for a USB controller that is part of a Tegra +SOC is as described in the document "Open Firmware Recommended +Practice : Universal Serial Bus" with the following modifications +and additions : + +Required properties : + - compatible : Should be "nvidia,tegra20-ehci" for USB controllers + used in host mode. + - phy_type : Should be one of "ulpi" or "utmi". + - nvidia,vbus-gpio : If present, specifies a gpio that needs to be + activated for the bus to be powered. + +Optional properties: + - dr_mode : dual role mode. Indicates the working mode for + nvidia,tegra20-ehci compatible controllers. Can be "host", "peripheral", + or "otg". Default to "host" if not defined for backward compatibility. + host means this is a host controller + peripheral means it is device controller + otg means it can operate as either ("on the go") + - nvidia,has-legacy-mode : boolean indicates whether this controller can + operate in legacy mode (as APX 2500 / 2600). In legacy mode some + registers are accessed through the APB_MISC base address instead of + the USB controller. diff --git a/roms/u-boot/doc/device-tree-bindings/video/atmel-hlcdc.txt b/roms/u-boot/doc/device-tree-bindings/video/atmel-hlcdc.txt new file mode 100644 index 000000000..b378cbf9d --- /dev/null +++ b/roms/u-boot/doc/device-tree-bindings/video/atmel-hlcdc.txt @@ -0,0 +1,42 @@ +Atmel HLCDC Framebuffer +----------------------------------------------------- +Required properties: +- compatible : + "atmel,sama5d2-hlcdc", "atmel,at91sam9x5-hlcdc". +- reg: physical base address of the controller and length of memory mapped + region. +- clocks: phandles to input clocks. +- atmel,vl-bpix: Bits per pixel. +- atmel,output-mode: LCD Controller Output Mode, + The unit is bits per pixel, there are four values, + <12>, <16>, <18>, <24>, the default value is <24>. +- atmel,guard-time: lcd guard time (Delay in frame periods). +- display-timings: please refer the displaymode.txt. + +Example: +hlcdc: hlcdc@f0000000 { + u-boot,dm-pre-reloc; + compatible = "atmel,sama5d2-hlcdc"; + reg = <0xf0000000 0x2000>; + clocks = <&lcdc_clk>; + atmel,vl-bpix = <4>; + atmel,output-mode = <24>; + atmel,guard-time = <1>; + pinctrl-names = "default"; + pinctrl-0 = <&pinctrl_lcd_base &pinctrl_lcd_pwm &pinctrl_lcd_rgb666>; + status = "okay"; + + display-timings { + 480x272 { + clock-frequency = <9000000>; + hactive = <480>; + vactive = <272>; + hsync-len = <41>; + hfront-porch = <2>; + hback-porch = <2>; + vfront-porch = <2>; + vback-porch = <2>; + vsync-len = <11>; + }; + }; +}; diff --git a/roms/u-boot/doc/device-tree-bindings/video/bridge/ps8622.txt b/roms/u-boot/doc/device-tree-bindings/video/bridge/ps8622.txt new file mode 100644 index 000000000..66d5d07eb --- /dev/null +++ b/roms/u-boot/doc/device-tree-bindings/video/bridge/ps8622.txt @@ -0,0 +1,33 @@ +ps8622-bridge bindings + +Required properties: + - compatible: "parade,ps8622" or "parade,ps8625" + - reg: first i2c address of the bridge + - sleep-gpios: OF device-tree gpio specification for PD_ pin. + - reset-gpios: OF device-tree gpio specification for RST_ pin. + - parade,regs: List of 3-byte registers tuples to write: + <I2C chip address offset> <register> <value> + +Optional properties: + - lane-count: number of DP lanes to use + - use-external-pwm: backlight will be controlled by an external PWM + - video interfaces: Device node can contain video interface port + nodes for panel according to [1]. + +[1]: Documentation/devicetree/bindings/media/video-interfaces.txt + +Example: + lvds-bridge@48 { + compatible = "parade,ps8622"; + reg = <0x48>; + sleep-gpios = <&gpc3 6 1 0 0>; + reset-gpios = <&gpc3 1 1 0 0>; + lane-count = <1>; + ports { + port@0 { + bridge_out: endpoint { + remote-endpoint = <&panel_in>; + }; + }; + }; + }; diff --git a/roms/u-boot/doc/device-tree-bindings/video/display-timing.txt b/roms/u-boot/doc/device-tree-bindings/video/display-timing.txt new file mode 100644 index 000000000..e1d4a0b59 --- /dev/null +++ b/roms/u-boot/doc/device-tree-bindings/video/display-timing.txt @@ -0,0 +1,110 @@ +display-timing bindings +======================= + +display-timings node +-------------------- + +required properties: + - none + +optional properties: + - native-mode: The native mode for the display, in case multiple modes are + provided. When omitted, assume the first node is the native. + +timing subnode +-------------- + +required properties: + - hactive, vactive: display resolution + - hfront-porch, hback-porch, hsync-len: horizontal display timing parameters + in pixels + vfront-porch, vback-porch, vsync-len: vertical display timing parameters in + lines + - clock-frequency: display clock in Hz + +optional properties: + - hsync-active: hsync pulse is active low/high/ignored + - vsync-active: vsync pulse is active low/high/ignored + - de-active: data-enable pulse is active low/high/ignored + - pixelclk-active: with + - active high = drive pixel data on rising edge/ + sample data on falling edge + - active low = drive pixel data on falling edge/ + sample data on rising edge + - ignored = ignored + - interlaced (bool): boolean to enable interlaced mode + - doublescan (bool): boolean to enable doublescan mode + - doubleclk (bool): boolean to enable doubleclock mode + +All the optional properties that are not bool follow the following logic: + <1>: high active + <0>: low active + omitted: not used on hardware + +There are different ways of describing the capabilities of a display. The +devicetree representation corresponds to the one commonly found in datasheets +for displays. If a display supports multiple signal timings, the native-mode +can be specified. + +The parameters are defined as: + + +----------+-------------------------------------+----------+-------+ + | | ↑ | | | + | | |vback_porch | | | + | | ↓ | | | + +----------#######################################----------+-------+ + | # ↑ # | | + | # | # | | + | hback # | # hfront | hsync | + | porch # | hactive # porch | len | + |<-------->#<-------+--------------------------->#<-------->|<----->| + | # | # | | + | # |vactive # | | + | # | # | | + | # ↓ # | | + +----------#######################################----------+-------+ + | | ↑ | | | + | | |vfront_porch | | | + | | ↓ | | | + +----------+-------------------------------------+----------+-------+ + | | ↑ | | | + | | |vsync_len | | | + | | ↓ | | | + +----------+-------------------------------------+----------+-------+ + +Example: + + display-timings { + native-mode = <&timing0>; + timing0: 1080p24 { + /* 1920x1080p24 */ + clock-frequency = <52000000>; + hactive = <1920>; + vactive = <1080>; + hfront-porch = <25>; + hback-porch = <25>; + hsync-len = <25>; + vback-porch = <2>; + vfront-porch = <2>; + vsync-len = <2>; + hsync-active = <1>; + }; + }; + +Every required property also supports the use of ranges, so the commonly used +datasheet description with minimum, typical and maximum values can be used. + +Example: + + timing1: timing { + /* 1920x1080p24 */ + clock-frequency = <148500000>; + hactive = <1920>; + vactive = <1080>; + hsync-len = <0 44 60>; + hfront-porch = <80 88 95>; + hback-porch = <100 148 160>; + vfront-porch = <0 4 6>; + vback-porch = <0 36 50>; + vsync-len = <0 5 6>; + }; diff --git a/roms/u-boot/doc/device-tree-bindings/video/displaymode.txt b/roms/u-boot/doc/device-tree-bindings/video/displaymode.txt new file mode 100644 index 000000000..45ca42db5 --- /dev/null +++ b/roms/u-boot/doc/device-tree-bindings/video/displaymode.txt @@ -0,0 +1,42 @@ +videomode bindings +================== + +(from http://lists.freedesktop.org/archives/dri-devel/2012-July/024875.html) + +Required properties: + - xres, yres: Display resolution + - left-margin, right-margin, hsync-len: Horizontal Display timing + parameters in pixels + - upper-margin, lower-margin, vsync-len: Vertical display timing + parameters in lines + - clock: display clock in Hz + +Optional properties: + - width-mm, height-mm: Display dimensions in mm + - hsync-active-high (bool): Hsync pulse is active high + - vsync-active-high (bool): Vsync pulse is active high + - interlaced (bool): This is an interlaced mode + - doublescan (bool): This is a doublescan mode + +There are different ways of describing a display mode. The devicetree +representation corresponds to the one used by the Linux Framebuffer +framework described here in Documentation/fb/framebuffer.txt. This +representation has been chosen because it's the only format which does +not allow for inconsistent parameters. Unlike the Framebuffer framework +the devicetree has the clock in Hz instead of ps. + +Example: + + display@0 { + /* 1920x1080p24 */ + clock = <52000000>; + xres = <1920>; + yres = <1080>; + left-margin = <25>; + right-margin = <25>; + hsync-len = <25>; + lower-margin = <2>; + upper-margin = <2>; + vsync-len = <2>; + hsync-active-high; + }; diff --git a/roms/u-boot/doc/device-tree-bindings/video/exynos-dp.txt b/roms/u-boot/doc/device-tree-bindings/video/exynos-dp.txt new file mode 100644 index 000000000..464a85302 --- /dev/null +++ b/roms/u-boot/doc/device-tree-bindings/video/exynos-dp.txt @@ -0,0 +1,69 @@ +Exynos Display port controller +============================== + +Required properties: +SOC specific: + compatible: should be "samsung,exynos5-dp" + reg: Base address of DP IP + +Optional properties: + samsung,h-res: X resolution of the panel + samsung,h-sync-width: hsync value + samsung,h-back-porch: left margin + samsung,h-front-porch right margin + samsung,v-res: Y resolution of the panel + samsung,v-sync-width: vsync value + samsung,v-back-porch: upper margin + samsung,v-front-porch: lower margin + samsung,v-sync-rate: refresh rate + + samsung,lt-status: Link training status + 0(DP_LT_NONE), 1(DP_LT_START), 2(DP_LT_CR), 3(DP_LT_ET), + 4(DP_LT_FINISHED), 5(DP_LT_FAIL) + + samsung,master-mode: 1 if you want to run DP as master, else 0 + samsung,bist-mode: 1 to enable video bist mode, else 0 + samsung,bist-pattern: bist mode pattern type + 0(NO_PATTERN), 1(COLOR_RAMP), 2(BALCK_WHITE_V_LINES), + 3(COLOR_SQUARE), 4(INVALID_PATTERN), 5(COLORBAR_32), + 6(COLORBAR_64),7(WHITE_GRAY_BALCKBAR_32), + 8(WHITE_GRAY_BALCKBAR_64),9(MOBILE_WHITEBAR_32), + 10(MOBILE_WHITEBAR_64) + samsung,h-sync-polarity: Horizontal Sync polarity + CONFIG_SYS_LOW if defined, else CONFIG_SYS_HIGH + samsung,v-sync-polarity: Vertical Sync polarity + CONFIG_SYS_LOW if defined, else CONFIG_SYS_HIGH + samsung,interlaced: Progressive if 0, else Interlaced + samsung,color-space: input video data format + COLOR_RGB = 0, COLOR_YCBCR422 = 1, COLOR_YCBCR444 = 2 + samsung,dynamic-range: dynamic range for input video data + VESA = 0, CEA = 1 + samsung,ycbcr-coeff: YCbCr co-efficients for input video + COLOR_YCBCR601 = 0, COLOR_YCBCR709 = 1 + samsung,color-depth: number of bits per colour component + COLOR_6 = 0, COLOR_8 = 1, COLOR_10 = 2, COLOR_12 = 3 + +Example: +SOC specific part: + dp@145b0000 { + compatible = "samsung,exynos5-dp"; + reg = <0x145b0000 0x1000>; + #address-cells = <1>; + #size-cells = <1>; + }; + +Board(panel) specific part: + dp@145b0000 { + samsung,lt-status = <0>; + + samsung,master-mode = <0>; + samsung,bist-mode = <0>; + samsung,bist-pattern = <0>; + samsung,h-sync-polarity = <0>; + samsung,v-sync-polarity = <0>; + samsung,interlaced = <0>; + samsung,color-space = <0>; + samsung,dynamic-range = <0>; + samsung,ycbcr-coeff = <0>; + samsung,color-depth = <1>; + }; diff --git a/roms/u-boot/doc/device-tree-bindings/video/exynos-fb.txt b/roms/u-boot/doc/device-tree-bindings/video/exynos-fb.txt new file mode 100644 index 000000000..b022f6163 --- /dev/null +++ b/roms/u-boot/doc/device-tree-bindings/video/exynos-fb.txt @@ -0,0 +1,100 @@ +Exynos Display Controller +========================= +Required properties: +SOC specific: + compatible: should be "samsung,exynos-fimd" + reg: Base address of FIMD IP. + +Board(panel specific): + samsung,vl-col: X resolution of the panel + samsung,vl-row: Y resolution of the panel + samsung,vl-freq: Refresh rate + samsung,vl-bpix: Bits per pixel + samsung,vl-hspw: Hsync value + samsung,vl-hfpd: Right margin + samsung,vl-hbpd: Left margin + samsung,vl-vspw: Vsync value + samsung,vl-vfpd: Lower margin + samsung,vl-vbpd: Upper margin + +Optional properties: +Board(panel specific): + samsung,vl-width: width of display area in mm + samsung,vl-height: Height of display area in mm + + samsung,vl-clkp: Clock polarity + CONFIG_SYS_LOW if defined, else CONFIG_SYS_HIGH + samsung,vl-oep: Output Enable polarity + CONFIG_SYS_LOW if defined, else CONFIG_SYS_HIGH + samsung,vl-hsp: Horizontal Sync polarity + CONFIG_SYS_LOW if defined, else CONFIG_SYS_HIGH + samsung,vl-vsp: Vertical Sync polarity + CONFIG_SYS_LOW if defined, else CONFIG_SYS_HIGH + samsung,vl-dp: Data polarity + CONFIG_SYS_LOW if defined, else CONFIG_SYS_HIGH + + samsung,vl-cmd-allow-len: Wait end of frame + samsung,winid: Window number on which data is to be displayed + samsung,init-delay: Delay before LCD initialization starts + samsung,power-on-delay: Delay after LCD is powered on + samsung,reset-delay: Delay after LCD is reset + samsung,interface-mode: 1(FIMD_RGB_INTERFACE), 2(FIMD_CPU_INTERFACE) + samsung,mipi-enabled: 1 if you want to use MIPI, else 0 + samsung,dp-enabled: 1is you want to use DP, else 0 + samsung,cs-setup: cs_setup value in FIMD_CPU_INTERFACE mode. + samsung,wr-setup: wr_setup value in FIMD_CPU_INTERFACE mode. + samsung,wr-act: wr_act value in FIMD_CPU_INTERFACE mode. + samsung,wr-hold: wr_hold value in FIMD_CPU_INTERFACE mode. + samsung,logo-on: 1 if you want to use custom logo. + 0 if you want LCD console. + samsung,logo-width: pixel width of logo image. Valid if logo_on = 1 + samsung,logo-height: pixel height of logo image. Valid if logo_on = 1 + samsung,logo-addr: Address of logo image. Valid if logo_on = 1 + samsung,rgb-mode: 0(MODE_RGB_P), 1(MODE_BGR_P), + 2(MODE_RGB_S), 3(MODE_BGR_S) + samsung,pclk-name: parent clock identifier: 1(MPLL), 2(EPLL), 3(VPLL) + samsung,sclk-div: parent_clock/source_clock ratio + samsung,dual-lcd-enabled: 1 if you support two LCD, else 0 + samsung,disable-sysmmu: Define this if you want to disable FIMD sysmmu. + (needed for Exynos5420 and newer versions) + Add the required FIMD sysmmu nodes to be + disabled with compatible string + "samsung,sysmmu-v3.3", with a "reg" property + holding the register address of FIMD sysmmu. + samsung,pwm-out-gpio: PWM output GPIO. + samsung,bl-en-gpio: backlight enable GPIO. + +Example: +SOC specific part: + fimd@14400000 { + compatible = "samsung,exynos-fimd"; + reg = <0x14400000 0x10000>; + #address-cells = <1>; + #size-cells = <1>; + }; + +Board specific part: + fimd@14400000 { + samsung,vl-freq = <60>; + samsung,vl-col = <2560>; + samsung,vl-row = <1600>; + samsung,vl-width = <2560>; + samsung,vl-height = <1600>; + + samsung,vl-clkp; + samsung,vl-dp; + samsung,vl-bpix = <4>; + + samsung,vl-hspw = <32>; + samsung,vl-hbpd = <80>; + samsung,vl-hfpd = <48>; + samsung,vl-vspw = <6>; + samsung,vl-vbpd = <37>; + samsung,vl-vfpd = <3>; + samsung,vl-cmd-allow-len = <0xf>; + + samsung,winid = <3>; + samsung,interface-mode = <1>; + samsung,dp-enabled = <1>; + samsung,dual-lcd-enabled = <0>; + }; diff --git a/roms/u-boot/doc/device-tree-bindings/video/exynos_mipi_dsi.txt b/roms/u-boot/doc/device-tree-bindings/video/exynos_mipi_dsi.txt new file mode 100644 index 000000000..4938ea01e --- /dev/null +++ b/roms/u-boot/doc/device-tree-bindings/video/exynos_mipi_dsi.txt @@ -0,0 +1,82 @@ +Exynos MIPI-DSIM Controller +========================= + +Required properties: +SOC specific: + compatible: should be "samsung,exynos-mipi-dsi" + reg: Base address of MIPI-DSIM IP. + +Board specific: + samsung,dsim-config-e-interface: interface to be used (RGB interface + for main display or CPU interface for main or sub display). + samsung,dsim-config-e-virtual-ch: virtual channel number that main + or sub display uses. + samsung,dsim-config-e-pixel-format: pixel stream format for main + or sub display. + samsung,dsim-config-e-burst-mode: selects Burst mode in Video mode. + in Non-burst mode, RGB data area is filled with RGB data and + NULL packets, according to input bandwidth of RGB interface. + samsung,dsim-config-e-no-data-lane: data lane count used by Master. + samsung,dsim-config-e-byte-clk: select byte clock source. + It must be DSIM_PLL_OUT_DIV8. + DSIM_EXT_CLK_DIV8 and DSIM_EXT_CLK_BYPASSS are not supported. + samsung,dsim-config-hfp: HFP disable mode. + If set, DSI master ignores HFP area in VIDEO mode. + In command mode, this variable is ignored. + samsung,dsim-config-p: P value for PMS setting. + samsung,dsim-config-m: M value for PMS setting. + samsung,dsim-config-s: S value for PMS setting. + samsung,dsim-config-pll-stable-time: the PLL Timer for stability + of the ganerated clock. + samsung,dsim-config-esc-clk: escape clock frequency for getting + the escape clock prescaler value. + samsung,dsim-config-stop-holding-cnt: the interval value between + transmitting read packet (or write "set_tear_on" command) + and BTA request. After transmitting read packet or write + "set_tear_on" command, BTA requests to D-PHY automatically. + This counter value specifies the interval between them. + samsung,dsim-config-bta-timeout: the timer for BTA. This register + specifies time out from BTA request to change the direction + with respect to Tx escape clock. + samsung,dsim-config-rx-timeout: the timer for LP Rx mode timeout. + this register specifies time out on how long RxValid deasserts, + after RxLpdt asserts with respect to Tx escape clock. + - RxValid specifies Rx data valid indicator. + - RxLpdt specifies an indicator that D-PHY is under RxLpdt mode + - RxValid and RxLpdt specifies signal from D-PHY. + samsung,dsim-device-name: name of the device. + samsung,dsim-device-id: unique device id. + samsung,dsim-device-bus_id: bus id for identifing connected bus + and this bus id should be same as id of mipi_dsim_device. + +Optional properties: + samsung,dsim-device-reverse-panel: reverse panel. + +Example: + mipidsi@11c80000 { + compatible = "samsung,exynos-mipi-dsi"; + reg = <0x11c80000 0x5c>; + + samsung,dsim-config-e-interface = <1>; + samsung,dsim-config-e-virtual-ch = <0>; + samsung,dsim-config-e-pixel-format = <7>; + samsung,dsim-config-e-burst-mode = <1>; + samsung,dsim-config-e-no-data-lane = <3>; + samsung,dsim-config-e-byte-clk = <0>; + samsung,dsim-config-hfp = <1>; + + samsung,dsim-config-p = <3>; + samsung,dsim-config-m = <120>; + samsung,dsim-config-s = <1>; + + samsung,dsim-config-pll-stable-time = <500>; + samsung,dsim-config-esc-clk = <20000000>; + samsung,dsim-config-stop-holding-cnt = <0x7ff>; + samsung,dsim-config-bta-timeout = <0xff>; + samsung,dsim-config-rx-timeout = <0xffff>; + + samsung,dsim-device-id = <0xffffffff>; + samsung,dsim-device-bus-id = <0>; + + samsung,dsim-device-reverse-panel = <1>; + }; diff --git a/roms/u-boot/doc/device-tree-bindings/video/intel-gma.txt b/roms/u-boot/doc/device-tree-bindings/video/intel-gma.txt new file mode 100644 index 000000000..914be4fed --- /dev/null +++ b/roms/u-boot/doc/device-tree-bindings/video/intel-gma.txt @@ -0,0 +1,40 @@ +Intel GMA Bindings +================== + +This is the Intel Graphics Media Accelerator. This binding supports selection +of display parameters only. + + +Required properties: + - compatible : "intel,gma"; + +Optional properties: + - intel,dp-hotplug : values for digital port hotplug, one cell per value for + ports B, C and D + - intel,panel-port-select : output port to use: 0=LVDS 1=DP_B 2=DP_C 3=DP_D + - intel,panel-power-cycle-delay : T4 time sequence (6 = 500ms) + + The following delays are in units of 0.1ms: + - intel,panel-power-up-delay : T1+T2 time sequence + - intel,panel-power-down-delay : T3 time sequence + - intel,panel-power-backlight-on-delay : T5 time sequence + - intel,panel-power-backlight-off-delay : Tx time sequence + + - intel,cpu-backlight : Value for CPU Backlight PWM + - intel,pch-backlight : Value for PCH Backlight PWM + +Example +------- + +gma { + compatible = "intel,gma"; + intel,dp_hotplug = <0 0 0x06>; + intel,panel-port-select = <1>; + intel,panel-power-cycle-delay = <6>; + intel,panel-power-up-delay = <2000>; + intel,panel-power-down-delay = <500>; + intel,panel-power-backlight-on-delay = <2000>; + intel,panel-power-backlight-off-delay = <2000>; + intel,cpu-backlight = <0x00000200>; + intel,pch-backlight = <0x04000000>; +}; diff --git a/roms/u-boot/doc/device-tree-bindings/video/osd/gdsys,ihs_video_out.txt b/roms/u-boot/doc/device-tree-bindings/video/osd/gdsys,ihs_video_out.txt new file mode 100644 index 000000000..d7aacc827 --- /dev/null +++ b/roms/u-boot/doc/device-tree-bindings/video/osd/gdsys,ihs_video_out.txt @@ -0,0 +1,23 @@ +* Guntermann & Drunck Integrated Hardware Systems OSD + +Required properties: +- compatible: "gdsys,ihs_video_out" +- reg: A combination of three register spaces: + - Register base for the video registers + - Register base for the OSD registers + - Address of the OSD video memory +- mode: The initial resolution and frequency: "1024_768_60", "720_400_70", or + "640_480_70" +- clk_gen: phandle to the pixel clock generator +- dp_tx: phandle to the display associated with the OSD + +Example: + +fpga0_video0 { + compatible = "gdsys,ihs_video_out"; + reg = <0x100 0x40 + 0x180 0x20 + 0x1000 0x1000>; + dp_tx = <&fpga0_dp_video0>; + clk_gen = <&fpga0_video0_clkgen>; +}; diff --git a/roms/u-boot/doc/device-tree-bindings/video/rockchip-lvds.txt b/roms/u-boot/doc/device-tree-bindings/video/rockchip-lvds.txt new file mode 100644 index 000000000..7432e2216 --- /dev/null +++ b/roms/u-boot/doc/device-tree-bindings/video/rockchip-lvds.txt @@ -0,0 +1,77 @@ +Rockchip LVDS interface +------------------ + +Required properties: +- compatible: "rockchip,rk3288-lvds"; + +- reg: physical base address of the controller and length + of memory mapped region. +- clocks: must include clock specifiers corresponding to entries in the + clock-names property. +- clock-names: must contain "pclk_lvds" + +- rockchip,grf: phandle to the general register files syscon + +- rockchip,data-mapping: should be <LVDS_FORMAT_VESA> or <LVDS_FORMAT_JEIDA>, + This describes how the color bits are laid out in the + serialized LVDS signal. +- rockchip,data-width : should be <18> or <24>; +- rockchip,output: should be <LVDS_OUTPUT_RGB>, <LVDS_OUTPUT_SINGLE> or + <LVDS_OUTPUT_DUAL>, This describes the output face. + +- display-timings : described by + doc/device-tree-bindings/video/display-timing.txt. + +Example: + lvds: lvds@ff96c000 { + compatible = "rockchip,rk3288-lvds"; + reg = <0xff96c000 0x4000>; + clocks = <&cru PCLK_LVDS_PHY>; + clock-names = "pclk_lvds"; + pinctrl-names = "default"; + pinctrl-0 = <&lcdc0_ctl>; + rockchip,grf = <&grf>; + status = "disabled"; + ports { + #address-cells = <1>; + #size-cells = <0>; + + lvds_in: port@0 { + reg = <0>; + + #address-cells = <1>; + #size-cells = <0>; + + lvds_in_vopb: endpoint@0 { + reg = <0>; + remote-endpoint = <&vopb_out_lvds>; + }; + lvds_in_vopl: endpoint@1 { + reg = <1>; + remote-endpoint = <&vopl_out_lvds>; + }; + }; + }; + }; + + &lvds { + rockchip,data-mapping = <LVDS_FORMAT_VESA>; + rockchip,data-width = <24>; + rockchip,output = <LVDS_OUTPUT_DUAL>; + rockchip,panel = <&panel>; + status = "okay"; + + display-timings { + timing@0 { + clock-frequency = <40000000>; + hactive = <1920>; + vactive = <1080>; + hsync-len = <44>; + hfront-porch = <88>; + hback-porch = <148>; + vfront-porch = <4>; + vback-porch = <36>; + vsync-len = <5>; + }; + }; + }; diff --git a/roms/u-boot/doc/device-tree-bindings/video/sandbox-fb.txt b/roms/u-boot/doc/device-tree-bindings/video/sandbox-fb.txt new file mode 100644 index 000000000..230d25c23 --- /dev/null +++ b/roms/u-boot/doc/device-tree-bindings/video/sandbox-fb.txt @@ -0,0 +1,17 @@ +Sandbox LCD +=========== + +This uses the displaymode.txt binding except that only xres and yres are +required properties. Also an additional optional property is defined: + +log2-depth: Log base 2 of the U-Boot display buffer depth (4=16bpp, 5=32bpp). + If not provided, a value of 4 is used. + +Example: + + lcd { + compatible = "sandbox,lcd-sdl"; + xres = <800>; + yres = <600>; + log2-depth = <5>; + }; diff --git a/roms/u-boot/doc/device-tree-bindings/video/simple-framebuffer.txt b/roms/u-boot/doc/device-tree-bindings/video/simple-framebuffer.txt new file mode 100644 index 000000000..3ea460583 --- /dev/null +++ b/roms/u-boot/doc/device-tree-bindings/video/simple-framebuffer.txt @@ -0,0 +1,25 @@ +Simple Framebuffer + +A simple frame-buffer describes a raw memory region that may be rendered to, +with the assumption that the display hardware has already been set up to scan +out from that buffer. + +Required properties: +- compatible: "simple-framebuffer" +- reg: Should contain the location and size of the framebuffer memory. +- width: The width of the framebuffer in pixels. +- height: The height of the framebuffer in pixels. +- stride: The number of bytes in each line of the framebuffer. +- format: The format of the framebuffer surface. Valid values are: + - r5g6b5 (16-bit pixels, d[15:11]=r, d[10:5]=g, d[4:0]=b). + +Example: + + framebuffer { + compatible = "simple-framebuffer"; + reg = <0x1d385000 (1600 * 1200 * 2)>; + width = <1600>; + height = <1200>; + stride = <(1600 * 2)>; + format = "r5g6b5"; + }; diff --git a/roms/u-boot/doc/device-tree-bindings/video/syncoam,seps525.txt b/roms/u-boot/doc/device-tree-bindings/video/syncoam,seps525.txt new file mode 100644 index 000000000..e1e0db9d7 --- /dev/null +++ b/roms/u-boot/doc/device-tree-bindings/video/syncoam,seps525.txt @@ -0,0 +1,24 @@ +spi based seps525 framebuffer display driver + +Driver for seps525 display controller (in spi mode), This binding supports selection +of spi chipselect, spi max frequency, gpio to drive dc and reset pin of seps525 +controller and spi transaction bit length. + +Required properties: +- compatible: "syncoam,seps525" +- reg: Specifies the chip-select the seps525 is connected to on the spi bus +- reset-gpios: gpio connected to reset pin of seps525 controller. +- dc-gpios: gpio connected to dc pin of seps525 controller: +- buswidth: bitlength of each spi transaction + +Example: + displayspi@0 { + compatible = "syncoam,seps525"; + reg = <0>; + spi-max-frequency = <10000000>; + spi-cpol; + spi-cpha; + buswidth = <8>; + reset-gpios = <&gpio 0x1c GPIO_ACTIVE_LOW>; + dc-gpios = <&gpio 0x1b GPIO_ACTIVE_HIGH>; + }; diff --git a/roms/u-boot/doc/device-tree-bindings/video/tegra20-dc.txt b/roms/u-boot/doc/device-tree-bindings/video/tegra20-dc.txt new file mode 100644 index 000000000..4731c3fba --- /dev/null +++ b/roms/u-boot/doc/device-tree-bindings/video/tegra20-dc.txt @@ -0,0 +1,85 @@ +Display Controller +------------------ + +(there isn't yet a generic binding in Linux, so this describes what is in +U-Boot, and may change based on Linux activity) + +The device node for a display device is as described in the document +"Open Firmware Recommended Practice : Universal Serial Bus" with the +following modifications and additions : + +Required properties : + - compatible : Should be "nvidia,tegra20-dc" + +Required subnode 'rgb' is as follows: + +Required properties (rgb) : + - nvidia,panel : phandle of LCD panel information + + +The panel node describes the panel itself. This has the properties listed in +displaymode.txt as well as: + +Required properties (panel) : + - nvidia,bits-per-pixel: number of bits per pixel (depth) + - nvidia,pwm : pwm to use to set display contrast (see tegra20-pwm.txt) + - nvidia,panel-timings: 4 cells containing required timings in ms: + * delay before asserting panel_vdd + * delay between panel_vdd-rise and data-rise + * delay between data-rise and backlight_vdd-rise + * delay between backlight_vdd and pwm-rise + * delay between pwm-rise and backlight_en-rise + +Optional GPIO properies all have (phandle, GPIO number, flags): + - nvidia,backlight-enable-gpios: backlight enable GPIO + - nvidia,lvds-shutdown-gpios: LVDS power shutdown GPIO + - nvidia,backlight-vdd-gpios: backlight power GPIO + - nvidia,panel-vdd-gpios: panel power GPIO + +Example: + +host1x { + compatible = "nvidia,tegra20-host1x", "simple-bus"; + reg = <0x50000000 0x00024000>; + interrupts = <0 65 0x04 /* mpcore syncpt */ + 0 67 0x04>; /* mpcore general */ + + #address-cells = <1>; + #size-cells = <1>; + status = "okay"; + + ranges = <0x54000000 0x54000000 0x04000000>; + + dc@54200000 { + compatible = "nvidia,tegra20-dc"; + reg = <0x54200000 0x00040000>; + interrupts = <0 73 0x04>; + status = "okay"; + + rgb { + status = "okay"; + nvidia,panel = <&lcd_panel>; + }; + }; +}; + +lcd_panel: panel { + /* Seaboard has 1366x768 */ + clock = <70600000>; + xres = <1366>; + yres = <768>; + left-margin = <58>; + right-margin = <58>; + hsync-len = <58>; + lower-margin = <4>; + upper-margin = <4>; + vsync-len = <4>; + hsync-active-high; + nvidia,bits-per-pixel = <16>; + nvidia,pwm = <&pwm 2 0>; + nvidia,backlight-enable-gpios = <&gpio 28 0>; /* PD4 */ + nvidia,lvds-shutdown-gpios = <&gpio 10 0>; /* PB2 */ + nvidia,backlight-vdd-gpios = <&gpio 176 0>; /* PW0 */ + nvidia,panel-vdd-gpios = <&gpio 22 0>; /* PC6 */ + nvidia,panel-timings = <400 4 203 17 15>; +}; diff --git a/roms/u-boot/doc/device-tree-bindings/video/tilcdc/panel.txt b/roms/u-boot/doc/device-tree-bindings/video/tilcdc/panel.txt new file mode 100644 index 000000000..808216310 --- /dev/null +++ b/roms/u-boot/doc/device-tree-bindings/video/tilcdc/panel.txt @@ -0,0 +1,66 @@ +Device-Tree bindings for tilcdc DRM generic panel output driver + +Required properties: + - compatible: value should be "ti,tilcdc,panel". + - panel-info: configuration info to configure LCDC correctly for the panel + - ac-bias: AC Bias Pin Frequency + - ac-bias-intrpt: AC Bias Pin Transitions per Interrupt + - dma-burst-sz: DMA burst size + - bpp: Bits per pixel + - fdd: FIFO DMA Request Delay + - sync-edge: Horizontal and Vertical Sync Edge: 0=rising 1=falling + - sync-ctrl: Horizontal and Vertical Sync: Control: 0=ignore + - raster-order: Raster Data Order Select: 1=Most-to-least 0=Least-to-most + - fifo-th: DMA FIFO threshold + - display-timings: typical videomode of lcd panel. Multiple video modes + can be listed if the panel supports multiple timings, but the 'native-mode' + should be the preferred/default resolution. Refer to + Documentation/devicetree/bindings/display/panel/display-timing.txt for display + timing binding details. + +Optional properties: +- backlight: phandle of the backlight device attached to the panel +- enable-gpios: GPIO pin to enable or disable the panel + +Recommended properties: + - pinctrl-names, pinctrl-0: the pincontrol settings to configure + muxing properly for pins that connect to TFP410 device + +Example: + + /* Settings for CDTech_S035Q01 / LCD3 cape: */ + lcd3 { + compatible = "ti,tilcdc,panel"; + pinctrl-names = "default"; + pinctrl-0 = <&bone_lcd3_cape_lcd_pins>; + backlight = <&backlight>; + enable-gpios = <&gpio3 19 0>; + + panel-info { + ac-bias = <255>; + ac-bias-intrpt = <0>; + dma-burst-sz = <16>; + bpp = <16>; + fdd = <0x80>; + sync-edge = <0>; + sync-ctrl = <1>; + raster-order = <0>; + fifo-th = <0>; + }; + display-timings { + native-mode = <&timing0>; + timing0: 320x240 { + hactive = <320>; + vactive = <240>; + hback-porch = <21>; + hfront-porch = <58>; + hsync-len = <47>; + vback-porch = <11>; + vfront-porch = <23>; + vsync-len = <2>; + clock-frequency = <8000000>; + hsync-active = <0>; + vsync-active = <0>; + }; + }; + }; diff --git a/roms/u-boot/doc/device-tree-bindings/video/tilcdc/tilcdc.txt b/roms/u-boot/doc/device-tree-bindings/video/tilcdc/tilcdc.txt new file mode 100644 index 000000000..7bf1bb444 --- /dev/null +++ b/roms/u-boot/doc/device-tree-bindings/video/tilcdc/tilcdc.txt @@ -0,0 +1,82 @@ +Device-Tree bindings for tilcdc DRM driver + +Required properties: + - compatible: value should be one of the following: + - "ti,am33xx-tilcdc" for AM335x based boards + - "ti,da850-tilcdc" for DA850/AM18x/OMAP-L138 based boards + - interrupts: the interrupt number + - reg: base address and size of the LCDC device + +Recommended properties: + - ti,hwmods: Name of the hwmod associated to the LCDC + +Optional properties: + - max-bandwidth: The maximum pixels per second that the memory + interface / lcd controller combination can sustain + - max-width: The maximum horizontal pixel width supported by + the lcd controller. + - max-pixelclock: The maximum pixel clock that can be supported + by the lcd controller in KHz. + - blue-and-red-wiring: Recognized values "straight" or "crossed". + This property deals with the LCDC revision 2 (found on AM335x) + color errata [1]. + - "straight" indicates normal wiring that supports RGB565, + BGR888, and XBGR8888 color formats. + - "crossed" indicates wiring that has blue and red wires + crossed. This setup supports BGR565, RGB888 and XRGB8888 + formats. + - If the property is not present or its value is not recognized + the legacy mode is assumed. This configuration supports RGB565, + RGB888 and XRGB8888 formats. However, depending on wiring, the red + and blue colors are swapped in either 16 or 24-bit color modes. + +Optional nodes: + + - port/ports: to describe a connection to an external encoder. The + binding follows Documentation/devicetree/bindings/graph.txt and + supports a single port with a single endpoint. + + - See also Documentation/devicetree/bindings/display/tilcdc/panel.txt and + Documentation/devicetree/bindings/display/tilcdc/tfp410.txt for connecting + tfp410 DVI encoder or lcd panel to lcdc + +[1] There is an errata about AM335x color wiring. For 16-bit color mode + the wires work as they should (LCD_DATA[0:4] is for Blue[3:7]), + but for 24 bit color modes the wiring of blue and red components is + crossed and LCD_DATA[0:4] is for Red[3:7] and LCD_DATA[11:15] is + for Blue[3-7]. For more details see section 3.1.1 in AM335x + Silicon Errata: + http://www.ti.com/general/docs/lit/getliterature.tsp?baseLiteratureNumber=sprz360 + +Example: + + fb: fb@4830e000 { + compatible = "ti,am33xx-tilcdc", "ti,da850-tilcdc"; + reg = <0x4830e000 0x1000>; + interrupt-parent = <&intc>; + interrupts = <36>; + ti,hwmods = "lcdc"; + + blue-and-red-wiring = "crossed"; + + port { + lcdc_0: endpoint@0 { + remote-endpoint = <&hdmi_0>; + }; + }; + }; + + tda19988: tda19988 { + compatible = "nxp,tda998x"; + reg = <0x70>; + + pinctrl-names = "default", "off"; + pinctrl-0 = <&nxp_hdmi_bonelt_pins>; + pinctrl-1 = <&nxp_hdmi_bonelt_off_pins>; + + port { + hdmi_0: endpoint@0 { + remote-endpoint = <&lcdc_0>; + }; + }; + }; diff --git a/roms/u-boot/doc/device-tree-bindings/w1-eeprom/ds24xxx.txt b/roms/u-boot/doc/device-tree-bindings/w1-eeprom/ds24xxx.txt new file mode 100644 index 000000000..2e91be93b --- /dev/null +++ b/roms/u-boot/doc/device-tree-bindings/w1-eeprom/ds24xxx.txt @@ -0,0 +1,37 @@ +Maxim DS24 families driver device binding - one wire protocol EEPROMS from Maxim +======================= + +This memory needs to be connected to a onewire bus, as a child node. +The bus will read the device serial number and match this node with a found +device on the bus +Also check doc/device-tree-bindings/w1 for onewire bus drivers + +Driver: +- drivers/w1-eeprom/ds24xxx.c + +Software ds24xxx device-tree node properties: +Required: +* compatible = "maxim,ds24b33" +or +* compatible = "maxim,ds2431" +Further memories can be added. + +Optional: +* none + +Example: + eeprom1: eeprom@0 { + compatible = "maxim,ds24xxx"; + } + +Example with parent bus: + +onewire_tm: onewire { + compatible = "w1-gpio"; + gpios = <&pioA 32 0>; + + eeprom1: eeprom@0 { + compatible = "maxim,ds24xxx"; + } +}; + diff --git a/roms/u-boot/doc/device-tree-bindings/w1-eeprom/ds2502.txt b/roms/u-boot/doc/device-tree-bindings/w1-eeprom/ds2502.txt new file mode 100644 index 000000000..7f05fc432 --- /dev/null +++ b/roms/u-boot/doc/device-tree-bindings/w1-eeprom/ds2502.txt @@ -0,0 +1,33 @@ +Maxim DS2502 driver device binding - one wire protocol add only memory from Maxim +======================= + +This memory needs to be connected to a onewire bus, as a child node. +The bus will read the device serial number and match this node with a found +device on the bus +Also check doc/device-tree-bindings/w1 for onewire bus drivers + +Driver: +- drivers/w1-eeprom/ds2502.c + +Ds2502 device-tree node properties: +Required: +* compatible = "maxim,ds2502" + +Optional: +* none + +Example: + eeprom1: eeprom@0 { + compatible = "maxim,ds2502"; + }; + +Example with parent bus: + onewire { + compatible = "fsl,imx53-owire"; + reg = <0x63fa4000 0x4000>; + + eeprom1: eeprom@0 { + compatible = "maxim,ds2502"; + }; + }; + diff --git a/roms/u-boot/doc/device-tree-bindings/w1-eeprom/eep_sandbox.txt b/roms/u-boot/doc/device-tree-bindings/w1-eeprom/eep_sandbox.txt new file mode 100644 index 000000000..82bb5899a --- /dev/null +++ b/roms/u-boot/doc/device-tree-bindings/w1-eeprom/eep_sandbox.txt @@ -0,0 +1,34 @@ +Onewire EEPROM sandbox driver device binding - one wire protocol sandbox EEPROM +======================= + +This memory needs to be connected to a onewire bus, as a child node. +The bus will read the device serial number and match this node with a found +device on the bus +Also check doc/device-tree-bindings/w1 for onewire bus drivers + +Driver: +- drivers/w1-eeprom/eep_sandbox.c + +Software ds24xxx device-tree node properties: +Required: +* compatible = "sandbox,w1-eeprom" + +Optional: +* none + +Example: + eeprom1: eeprom@0 { + compatible = "sandbox,w1-eeprom"; + } + +Example with parent bus: + +onewire_tm: onewire { + compatible = "w1-gpio"; + gpios = <&gpio_a 8>; + + eeprom1: eeprom@0 { + compatible = "sandbox,w1-eeprom"; + } +}; + diff --git a/roms/u-boot/doc/device-tree-bindings/w1/mxc-w1.txt b/roms/u-boot/doc/device-tree-bindings/w1/mxc-w1.txt new file mode 100644 index 000000000..1fb49cc11 --- /dev/null +++ b/roms/u-boot/doc/device-tree-bindings/w1/mxc-w1.txt @@ -0,0 +1,37 @@ +NXP i.MX (MXC) One wire bus master controller +======================= + +Child nodes are required in device tree. The driver will detect +the devices serial number and then search in the child nodes in the device tree +for the proper node and try to match it with the device. + +Also check doc/device-tree-bindings/w1-eeprom for possible child nodes drivers + +Driver: +- drivers/w1/mxc_w1.c + +Required properties: +- compatible : should be one of + "fsl,imx21-owire", "fsl,imx27-owire", "fsl,imx31-owire", "fsl,imx25-owire" + "fsl,imx25-owire", "fsl,imx35-owire", "fsl,imx50-owire", "fsl,imx53-owire" + +- reg : Address and length of the register set for the device + +Optional: +* none + +Example: + onewire { + compatible = "fsl,imx53-owire"; + reg = <0x63fa4000 0x4000>; + }; + +Example with child: + onewire { + compatible = "fsl,imx53-owire"; + reg = <0x63fa4000 0x4000>; + + eeprom1: eeprom@0 { + compatible = "maxim,ds24xxx"; + }; + }; diff --git a/roms/u-boot/doc/device-tree-bindings/w1/w1-gpio.txt b/roms/u-boot/doc/device-tree-bindings/w1/w1-gpio.txt new file mode 100644 index 000000000..5a582448e --- /dev/null +++ b/roms/u-boot/doc/device-tree-bindings/w1/w1-gpio.txt @@ -0,0 +1,40 @@ +W1 gpio device binding - one wire protocol over bitbanged gpio +======================= + + +Child nodes are required in device tree. The driver will detect +the devices serial number and then search in the child nodes in the device tree +for the proper node and try to match it with the device. + +Also check doc/device-tree-bindings/w1-eeprom for possible child nodes drivers + +Driver: +- drivers/w1/w1-gpio.c + +Software w1 device-tree node properties: +Required: +* compatible = "w1-gpio"; +* gpios = <...>; + This is the gpio used for one wire protocol, using bitbanging + +Optional: +* none + +Example: + +onewire_tm: onewire { + compatible = "w1-gpio"; + gpios = <&pioA 32 0>; +}; + +Example with child: + +onewire_tm: onewire { + compatible = "w1-gpio"; + gpios = <&pioA 32 0>; + + eeprom1: eeprom@0 { + compatible = "maxim,ds24xxx"; + } +}; + diff --git a/roms/u-boot/doc/feature-removal-schedule.txt b/roms/u-boot/doc/feature-removal-schedule.txt new file mode 100644 index 000000000..546d2da17 --- /dev/null +++ b/roms/u-boot/doc/feature-removal-schedule.txt @@ -0,0 +1,31 @@ +The following is a list of files and features that are going to be +removed from the U-Boot source tree. Every entry should contain what +exactly is going away, when it will be gone, why it is being removed, +and who is going to be doing the work. When the feature is removed +from U-Boot, its corresponding entry should also be removed from this +file. + +--------------------------- + +What: Users of the legacy miiphy_* code +When: undetermined + +Why: We now have a PHY library, which allows everyone to share PHY + drivers. All new drivers should use this infrastructure, and + all old drivers should get converted to use it. + +Who: Andy Fleming <afleming@gmail.com> and driver maintainers + +--------------------------- + +What: GPL cleanup +When: August 2009 +Why: Over time, a couple of files have sneaked in into the U-Boot + source code that are either missing a valid GPL license + header or that carry a license that is incompatible with the + GPL. + Such files shall be removed from the U-Boot source tree. + See http://www.denx.de/wiki/pub/U-Boot/TaskGplCleanup/u-boot-1.1.2-files + for an old and probably incomplete list of such files. + +Who: Wolfgang Denk <wd@denx.de> and board maintainers diff --git a/roms/u-boot/doc/git-mailrc b/roms/u-boot/doc/git-mailrc new file mode 100644 index 000000000..dc7b39b32 --- /dev/null +++ b/roms/u-boot/doc/git-mailrc @@ -0,0 +1,134 @@ +# To use this file, run in your u-boot tree: +# git config sendemail.aliasesfile doc/git-mailrc +# git config sendemail.aliasfiletype mutt +# +# Then when sending patches, you can use: +# git send-email --to u-boot --cc i2c ... + +alias uboot u-boot@lists.denx.de +alias u-boot uboot + +# Maintainer aliases. Use the same alias here as patchwork to keep +# things simple and easy to look up/coordinate. +alias abiessmann Andreas Bießmann <andreas@biessmann.org> +alias abrodkin Alexey Brodkin <alexey.brodkin@synopsys.com> +alias afleming Andy Fleming <afleming@gmail.com> +alias ag Anatolij Gustschin <agust@denx.de> +alias agraf Alexander Graf <agraf@csgraf.de> +alias alexnemirovsky Alex Nemirovsky <alex.nemirovsky@cortina-access.com> +alias alisonwang Alison Wang <alison.wang@nxp.com> +alias angelo_ts Angelo Dureghello <angelo@sysam.it> +alias apritzel Andre Przywara <andre.przywara@arm.com> +alias bmeng Bin Meng <bmeng.cn@gmail.com> +alias danielschwierzeck Daniel Schwierzeck <daniel.schwierzeck@gmail.com> +alias dinh Dinh Nguyen <dinguyen@kernel.org> +alias hs Heiko Schocher <hs@denx.de> +alias freenix Peng Fan <peng.fan@nxp.com> +alias iwamatsu Nobuhiro Iwamatsu <iwamatsu@nigauri.org> +alias jaehoon Jaehoon Chung <jh80.chung@samsung.com> +alias jagan Jagan Teki <jagan@amarulasolutions.com> +alias jhersh Joe Hershberger <joe.hershberger@ni.com> +alias kevery Kever Yang <kever.yang@rock-chips.com> +alias leyfoon Ley Foon Tan <lftan.linux@gmail.com> +alias lokeshvutla Lokesh Vutla <lokeshvutla@ti.com> +alias lukma Lukasz Majewski <lukma@denx.de> +alias macpaul Macpaul Lin <macpaul@andestech.com> +alias marex Marek Vasut <marex@denx.de> +alias mariosix Mario Six <mario.six@gdsys.cc> +alias masahiro Masahiro Yamada <yamada.masahiro@socionext.com> +alias mateusz Mateusz Kulikowski <mateusz.kulikowski@gmail.com> +alias mbrugger Matthias Brugger <mbrugger@suse.com> +alias monstr Michal Simek <monstr@monstr.eu> +alias prom Minkyu Kang <mk7.kang@samsung.com> +alias ptomsich Philipp Tomsich <philipp.tomsich@theobroma-systems.com> +alias sbabic Stefano Babic <sbabic@denx.de> +alias simongoldschmidt Simon Goldschmidt <simon.k.r.goldschmidt@gmail.com> +alias sjg Simon Glass <sjg@chromium.org> +alias smcnutt Scott McNutt <smcnutt@psyent.com> +alias stroese Stefan Roese <sr@denx.de> +alias trini Tom Rini <trini@konsulko.com> +alias wd Wolfgang Denk <wd@denx.de> +alias priyankajain Priyanka Jain <priyanka.jain@nxp.com> + +# Architecture aliases +alias arch arc, arm, m68k, microblaze, mips, nds32, nios2, powerpc, sandbox, superh, x86 +alias arches arch + +alias arc uboot, abrodkin + +alias arm uboot, trini +alias at91 uboot, abiessmann +alias cortina uboot, alexnemirovsky +alias davinci ti +alias imx uboot, sbabic +alias kirkwood uboot, stroese +alias omap ti +alias pxa uboot, marex +alias rmobile uboot, iwamatsu +alias s3c samsung +alias s5pc samsung +alias samsung uboot, prom +alias snapdragon uboot, mateusz +alias socfpga uboot, marex, dinh, simongoldschmidt, leyfoon +alias sunxi uboot, jagan, apritzel +alias tegra uboot, sjg, Tom Warren <twarren@nvidia.com>, Stephen Warren <swarren@nvidia.com> +alias tegra2 tegra +alias ti uboot, lokeshvutla +alias uniphier uboot, masahiro +alias zynq uboot, monstr +alias rockchip uboot, sjg, kevery, ptomsich + +alias bcm283x uboot, mbrugger +alias rpi uboot, mbrugger + +alias m68k uboot, alisonwang, angelo_ts +alias coldfire m68k + +alias microblaze uboot, monstr +alias mb microblaze + +alias mips uboot, danielschwierzeck + +alias nds32 uboot, macpaul + +alias nios uboot, Thomas Chou <thomas@wytron.com.tw>, smcnutt +alias nios2 nios + +alias powerpc uboot, afleming, stroese, wd, priyankajain, mariosix +alias ppc powerpc +alias mpc8xx uboot, wd, Christophe Leroy <christophe.leroy@c-s.fr> +alias mpc83xx uboot, mariosix +alias mpc85xx uboot, afleming, priyankajain +alias mpc86xx uboot, afleming, priyankajain + +alias sandbox sjg +alias sb sandbox + +alias superh uboot, iwamatsu, marex +alias sh superh + +alias x86 uboot, sjg, bmeng + +# Subsystem aliases +alias dm uboot, sjg +alias cfi uboot, stroese +alias dfu uboot, lukma +alias efi uboot, agraf +alias eth uboot, jhersh +alias kerneldoc uboot, marex +alias fdt uboot, sjg +alias i2c uboot, hs +alias kconfig uboot, masahiro +alias mmc uboot, freenix, jaehoon +alias nand uboot +alias net uboot, jhersh +alias phy uboot, jhersh +alias spi uboot, jagan +alias spmi uboot, mateusz +alias ubi uboot, hs +alias usb uboot, marex +alias xhci uboot, bmeng +alias video uboot, ag +alias patman uboot, sjg +alias buildman uboot, sjg +alias pmic uboot, jaehoon diff --git a/roms/u-boot/doc/imx/ahab/csf_examples/csf_enc_boot_image.txt b/roms/u-boot/doc/imx/ahab/csf_examples/csf_enc_boot_image.txt new file mode 100644 index 000000000..6c70db657 --- /dev/null +++ b/roms/u-boot/doc/imx/ahab/csf_examples/csf_enc_boot_image.txt @@ -0,0 +1,27 @@ +[Header] +Target = AHAB +Version = 1.0 + +[Install SRK] +# SRK table generated by srktool +File = "./release/crts/SRK_1_2_3_4_table.bin" +# Public key certificate in PEM format +Source = "./release/crts/SRK1_sha384_secp384r1_v3_usr_crt.pem" +# Index of the public key certificate within the SRK table (0 .. 3) +Source index = 0 +# Type of SRK set (NXP or OEM) +Source set = OEM +# bitmask of the revoked SRKs +Revocations = 0x0 + +[Authenticate Data] +# Binary to be signed generated by mkimage +File = "flash.bin" +# Offsets = Container header Signature block (printed out by mkimage) +Offsets = 0x400 0x590 + +[Install Secret Key] +Key = "dek.bin" +Key Length = 128 +#Key Identifier = 0x1234CAFE +Image Indexes = 0xFFFFFFFE diff --git a/roms/u-boot/doc/imx/ahab/guides/mx8_mx8x_encrypted_boot.txt b/roms/u-boot/doc/imx/ahab/guides/mx8_mx8x_encrypted_boot.txt new file mode 100644 index 000000000..dfea4c827 --- /dev/null +++ b/roms/u-boot/doc/imx/ahab/guides/mx8_mx8x_encrypted_boot.txt @@ -0,0 +1,293 @@ + +=========================================================+ + + i.MX 8, i.MX 8X Encrypted Boot guide using AHAB + + +=========================================================+ + +1. AHAB Encrypted Boot process +------------------------------- + +This document describes a step-by-step procedure on how to encrypt and sign a +bootloader image for i.MX8/8x family devices. It is assumed that the reader +is familiar with basic AHAB concepts and has already closed the device, +step-by-step procedure can be found in mx8_mx8x_secure_boot.txt and +mx8_mx8x_spl_secure_boot.txt guides. + +The steps described in this document were based in i.MX8QM device, the same +concept can be applied to others processors in i.MX8/8X family devices. + +1.1 Understanding the encrypted image signature block +------------------------------------------------------ + +As described in mx8_mx8x_secure_boot.txt guide a single binary is used to boot +the device. The imx-mkimage tool combines all the input images in a container +structure, generating a flash.bin binary. + +AHAB is able to decrypt image containers by calling SECO authentication +functions, the image must be encrypted by CST and the resulting DEK (Data +Encryption Key) must be encapsulated and included into the container signature +block: + + +----------------------------+ + | | ^ + | | | + | Container header | | + | | | + | | | + +---+------------------------+ | + | S | Signature block header | | Signed + | i +------------------------+ | + | g | | | + | n | | | + | a | SRK table | | + | t | | | + | u | | v + | r +------------------------+ + | e | Signature | + | +------------------------+ + | B | | + | l | SGK Key | + | o | Certificate (optional) | + | c | | + | k +------------------------+ + | | DEK Blob | + +---+------------------------+ + +1.1.1 Understanding and generating the DEK blob +------------------------------------------------ + +The encrypted boot image requires a DEK blob on each time AHAB is used to +decrypt an image. The DEK blob is used as a security layer to wrap and store +the DEK off-chip using the OTPMK which is unique per device. + +On i.MX8/8x devices the DEK blob is generated using the SECO API, the following +funtion is available in U-Boot and can be executed through dek_blob command: + +- sc_seco_gen_key_blob(sc_ipc_t ipc, uint32_t id, sc_faddr_t load_addr, + sc_faddr_t export_addr, uint16_t max_size) + +Details in API usage can be found in SCFW API guide [1]. + +1.2 Enabling the encrypted boot support in U-Boot +-------------------------------------------------- + +For deploying an encrypted boot image additional U-Boot tools are needed, +please be sure to have the following features enabled, this can be achieved +by following one of the methods below: + +- Defconfig: + + CONFIG_AHAB_BOOT=y + CONFIG_CMD_DEKBLOB=y + CONFIG_IMX_SECO_DEK_ENCAP=y + CONFIG_FAT_WRITE=y + +- Kconfig: + + ARM architecture -> Support i.MX8 AHAB features + ARM architecture -> Support the 'dek_blob' command + File systems -> Enable FAT filesystem support-> Enable FAT filesystem + write support + +1.3 Enabling the encrypted boot support in CST +----------------------------------------------- + +The encryption feature is not enabled by default in Code Signing tools (CST). +The CST backend must be recompiled, execute the following commands to enable +encryption support in CST: + + $ sudo apt-get install libssl-dev openssl + $ cd <CST install directory>/code/back_end/src + $ gcc -o cst_encrypted -I ../hdr -L ../../../linux64/lib *.c + -lfrontend -lcrypto + $ cp cst_encrypted ../../../linux64/bin/ + +1.4 Preparing the image container +---------------------------------- + +The container generation is explained in and mx8_mx8x_secure_boot.txt and +mx8_mx8x_spl_secure_boot.txt guides. This document is based in imx-mkimage +flash target (2 containers in flash.bin). + +- Assembly flash.bin binary: + + $ make SOC=<SoC Name> flash + +The mkimage log is used during the encrypted boot procedure to create the +Command Sequence File (CSF): + + CST: CONTAINER 0 offset: 0x400 + CST: CONTAINER 0: Signature Block: offset is at 0x590 + DONE. + Note: Please copy image to offset: IVT_OFFSET + IMAGE_OFFSET + +1.6 Creating the CSF description to encrypt the 2nd container +-------------------------------------------------------------- + +The csf_enc_boot_image.txt available under ahab/csf_examples/ can be used as +example for encrypting the flash.bin binary, the main change is the Install +Secret Key command that must be added after Authenticate Data command. + + [Install Secret Key] + Key = "dek.bin" + Key Length = 128 + #Key Identifier = 0x1234CAFE + Image Indexes = 0xFFFFFFFE + +By default all images are encrypted and image indexes parameter can be used +to mask the images indexes that must be encrypted, on this example only the +2nd container will be encrypted. + +Optionally users can provide a key identifier that must match the value +provided during the blob generation, by default its value is zero. + +1.7 Encrypting the 2nd container +--------------------------------- + +The image is encrypted using the Code Signing Tool. The tool generates the +encrypted image and a random dek.bin file. + +- Encrypt flash.bin binary: + + $ ./cst_encrypted -i csf_enc_boot_image.txt -o enc_flash.bin + The DEK BLOB must be inserted at offset 0x7c0 (its expected size is 72 bytes) + CSF Processed successfully and signed image available in enc_boot_image.bin + +The output log will be used in a later step to insert the DEK blob into the +signature block. + +1.8 Generating the DEK Blob +---------------------------- + +The DEK must be encapsulated into a CAAM blob so it can be included into the +final encrypted binary. The U-Boot provides a tool called dek_blob which is +calling the SECO blob encapsulation API. + +Copy the dek.bin in SDCard FAT partition and run the following commands from +U-Boot prompt: + + => mmc list + FSL_SDHC: 1 (SD) + FSL_SDHC: 2 + => fatload mmc 1:1 0x80280000 dek.bin + => dek_blob 0x80280000 0x80280100 128 + => fatwrite mmc 1:1 0x80280100 dek_blob.bin 0x48 + +In host PC copy the generated dek_blob.bin to the CST directory. + +1.9 Assembling the encrypted image +----------------------------------- + +The DEK blob generated in the step above have to be inserted into the container +signature block. + +The CSF log is used to determine the DEK Blob offset: + + The DEK BLOB must be inserted at offset 0x7c0 (its expected size is 72 bytes) + CSF Processed successfully and signed image available in enc_boot_image.bin + +- Insert DEK Blob into container signature block: + + $ dd if=dek_blob.bin of=enc_flash.bin bs=1 seek=$((0x7c0)) conv=notrunc + +1.10 Flashing the encrypted boot image +--------------------------------------- + +The same offset is used for encrypted boot images, in case booting from +eMMC/SDCard the offset is 32K. + +- Flash encrypted image in SDCard: + + $ sudo dd if=enc_flash.bin of=/dev/sd<x> bs=1K seek=32 && sync + +2.0 Encrypting a standalone container +-------------------------------------- + +CST is also able to encrypt additional images containers, the steps documented +in this section are based in OS container but can be also applied to SPL +targets and 3rd containers. + +2.1 Creating the OS container +------------------------------ + +As explained in mx8_mx8x_secure_boot.txt guide the imx-mkimage tool is used to +generate an image container for OS images, the mkimage log is used during the +encrypted boot procedure to create the Command Sequence File (CSF). + +- Creating OS container: + + $ make SOC=<SoC Name> flash_kernel + ... + CST: CONTAINER 0 offset: 0x0 + CST: CONTAINER 0: Signature Block: offset is at 0x110 + +2.2 Creating the CSF description file for standalone container +--------------------------------------------------------------- + +The Image Indexes parameter is used to mask the images that are encrypted by +CST, as a single container is used for OS images the Image Indexes command can +be commented or set to 0xFFFFFFFF. + + [Install Secret Key] + Key = "dek_os.bin" + Key Length = 128 + #Key Identifier = 0x1234CAFE + Image Indexes = 0xFFFFFFFF + +2.3 Encrypting the standalone container +---------------------------------------- + +As explained in section 1.7 the CST generates the encrypted image and a random +dek.bin file. + +- Encrypt the standalone container: + + $ ./cst_encrypted -i csf_linux_img.txt -o enc_flash_os.bin + The DEK BLOB must be inserted at offset 0x340 (its expected size is 72 bytes) + CSF Processed successfully and signed image available in enc_flash_os.bin + +The output log will be used in a later step to insert the DEK blob into the +signature block. + +2.4 Generating the DEK Blob for standalone container +---------------------------------------------------- + +Similar to section 1.8 the DEK must be encapsulated into a CAAM blob so it can +be included into the final encrypted binary. + +Copy the dek_os.bin in SDCard FAT partition and run the following commands from +U-Boot prompt: + + => mmc list + FSL_SDHC: 1 (SD) + FSL_SDHC: 2 + => fatload mmc 1:1 0x80280000 dek_os.bin + => dek_blob 0x80280000 0x80280100 128 + => fatwrite mmc 1:1 0x80280100 dek_blob_os.bin 0x48 + +In host PC copy the generated dek_blob_os.bin to the CST directory. + +2.5 Assembling the encrypted image +----------------------------------- + +The DEK blob generated in the step above have to be inserted into the container +signature block. + +The CSF log is used to determine the DEK Blob offset: + + The DEK BLOB must be inserted at offset 0x340 (its expected size is 72 bytes) + CSF Processed successfully and signed image available in enc_flash_os.bin + +- Insert DEK Blob into container signature block: + + $ dd if=dek_blob_os.bin of=enc_flash_os.bin bs=1 seek=$((0x340)) conv=notrunc + +2.6 Copy encrypted image to SDCard +----------------------------------- + +The encrypted container can be copied to SDCard FAT partition, please note +that U-Boot requires signed and encrypted containers to be named as +os_cntr_signed.bin. + + $ sudo cp enc_flash_os.bin /media/UserID/Boot\ imx8/os_cntr_signed.bin + +References: +[1] SCFW API guide: "System Controller Firmware API Reference Guide - Rev 1.5" diff --git a/roms/u-boot/doc/imx/clk/ccf.txt b/roms/u-boot/doc/imx/clk/ccf.txt new file mode 100644 index 000000000..f47ca8832 --- /dev/null +++ b/roms/u-boot/doc/imx/clk/ccf.txt @@ -0,0 +1,102 @@ +Introduction: +============= + +This documentation entry describes the Common Clock Framework [CCF] port from +Linux kernel (v5.1.12) to U-Boot. + +This code is supposed to bring CCF to IMX based devices (imx6q, imx7 imx8). +Moreover, it also provides some common clock code, which would allow easy +porting of CCF Linux code to other platforms. + +Design decisions: +================= + +* U-Boot's driver model [DM] for clk differs from Linux CCF. The most notably + difference is the lack of support for hierarchical clocks and "clock as a + manager driver" (single clock DTS node acts as a starting point for all other + clocks). + +* The clk_get_rate() caches the previously read data if CLK_GET_RATE_NOCACHE is + not set (no need for recursive access). + +* On purpose the "manager" clk driver (clk-imx6q.c) is not using large table to + store pointers to clocks - e.g. clk[IMX6QDL_CLK_USDHC2_SEL] = .... Instead we + use udevice's linked list for the same class (UCLASS_CLK). + + Rationale: + ---------- + When porting the code as is from Linux, one would need ~1KiB of RAM to store + it. This is way too much if we do plan to use this driver in SPL. + +* The "central" structure of this patch series is struct udevice and its + uclass_priv field contains the struct clk pointer (to the originally created + one). + +* To keep things simple the struct udevice's uclass_priv pointer is used to + store back pointer to corresponding struct clk. However, it is possible to + modify clk-uclass.c file and add there struct uc_clk_priv, which would have + clock related members (like pointer to clk). As of this writing there is no + such need, so to avoid extra allocations (as it can be auto allocated by + setting .per_device_auto = sizeof(struct uc_clk_priv)) the + uclass_priv stores the pointer to struct clk. + +* Non-CCF clocks do not have a pointer to a clock in clk->dev->priv. In the case + of composite clocks, clk->dev->priv may not match clk. Drivers should always + use the struct clk which is passed to them, and not clk->dev->priv. + +* It is advised to add common clock code (like already added rate and flags) to + the struct clk, which is a top level description of the clock. + +* U-Boot's driver model already provides the facility to automatically allocate + (via private_alloc_size) device private data (accessible via dev->priv). It + may look appealing to use this feature to allocate private structures for CCF + clk devices e.g. divider (struct clk_divider *divider) for IMX6Q clock. + + The above feature had not been used for following reasons: + - The original CCF Linux kernel driver is the "manager" for clocks - it + decides when clock is instantiated (and when memory for it is allocated). + + - Using it would change the original structure of the CCF code. + + - To bind (via clk_register()) the clock device with U-Boot driver model we + first need udevice for it (the "chicken and egg problem"). + +* I've added the clk_get_parent(), which reads parent's dev->uclass_priv to + provide parent's struct clk pointer. This seems the easiest way to get + child/parent relationship for struct clk in U-Boot's udevice based clocks. In + the future arbitrary parents may be supported by adding a get_parent function + to clk_ops. + +* Linux's CCF 'struct clk_core' corresponds to U-Boot's udevice in 'struct clk'. + Clock IP block agnostic flags from 'struct clk_core' (e.g. NOCACHE) have been + moved from this struct one level up to 'struct clk'. Many flags are + unimplemented at the moment. + +* For tests the new ./test/dm/clk_ccf.c and ./drivers/clk/clk_sandbox_ccf.c + files have been introduced. The latter setups the CCF clock structure for + sandbox by reusing, if possible, generic clock primitives - like divier and + mux. The former file provides code to tests this setup. + + For sandbox new CONFIG_SANDBOX_CLK_CCF Kconfig define has been introduced. + All new primitives added for new architectures must have corresponding test in + the two aforementioned files. + +Testing (sandbox): +================== + +make mrproper; make sandbox_defconfig; make -j4 +./u-boot -i -d arch/sandbox/dts/test.dtb +=> ut dm clk + +or in a more "scriptable" way (with -v to print debug output): +./u-boot --fdt arch/sandbox/dts/test.dtb --command "ut dm clk_ccf" -v + +To do: +------ + +* Use of OF_PLATDATA in the SPL setup for CCF - as it is now - the SPL grows + considerably and using CCF in boards with tiny resources (OCRAM) is + problematic. + +* On demand port other parts of CCF to U-Boot - as now only features _really_ + needed by DM/DTS converted drivers are used. diff --git a/roms/u-boot/doc/imx/common/imx25.txt b/roms/u-boot/doc/imx/common/imx25.txt new file mode 100644 index 000000000..0ca21b6df --- /dev/null +++ b/roms/u-boot/doc/imx/common/imx25.txt @@ -0,0 +1,10 @@ +U-Boot for Freescale i.MX25 + +This file contains information for the port of U-Boot to the Freescale i.MX25 +SoC. + +1. CONVENTIONS FOR FUSE ASSIGNMENTS +----------------------------------- + +1.1 MAC Address: It is stored in the words 26 to 31 of fuse bank 0, using the + natural MAC byte order (i.e. MSB first). diff --git a/roms/u-boot/doc/imx/common/imx27.txt b/roms/u-boot/doc/imx/common/imx27.txt new file mode 100644 index 000000000..6f92cb47c --- /dev/null +++ b/roms/u-boot/doc/imx/common/imx27.txt @@ -0,0 +1,10 @@ +U-Boot for Freescale i.MX27 + +This file contains information for the port of U-Boot to the Freescale i.MX27 +SoC. + +1. CONVENTIONS FOR FUSE ASSIGNMENTS +----------------------------------- + +1.1 MAC Address: It is stored in the words 4 to 9 of fuse bank 0, using the + reversed MAC byte order (i.e. LSB first). diff --git a/roms/u-boot/doc/imx/common/imx5.txt b/roms/u-boot/doc/imx/common/imx5.txt new file mode 100644 index 000000000..ea0e144ce --- /dev/null +++ b/roms/u-boot/doc/imx/common/imx5.txt @@ -0,0 +1,40 @@ +U-Boot for Freescale i.MX5x + +This file contains information for the port of U-Boot to the Freescale +i.MX5x SoCs. + +1. CONFIGURATION OPTIONS/SETTINGS +--------------------------------- + +1.1 CONFIG_MX51_PLL_ERRATA: Workaround for i.MX51 PLL errata. + This option should be enabled by all boards using the i.MX51 silicon + version up until (including) 3.0 running at 800MHz. + The PLL's in the i.MX51 processor can go out of lock due to a metastable + condition in an analog flip-flop when used at high frequencies. + This workaround implements an undocumented feature in the PLL (dither + mode), which causes the effect of this failure to be much lower (in terms + of frequency deviation), avoiding system failure, or at least decreasing + the likelihood of system failure. + +1.2 CONFIG_SYS_MAIN_PWR_ON: Trigger MAIN_PWR_ON upon startup. + This option should be enabled for boards having a SYS_ON_OFF_CTL signal + connected to GPIO1[23] and triggering the MAIN_PWR_ON signal like in the + reference designs. + +2. CONVENTIONS FOR FUSE ASSIGNMENTS +----------------------------------- + +2.1 MAC Address: It is stored in the words 9 to 14 of fuse bank 1, using the + natural MAC byte order (i.e. MSB first). + + This is an example how to program an example MAC address 01:23:45:67:89:ab + into the eFuses. Assure that the programming voltage is available and then + execute: + + => fuse prog -y 1 9 01 23 45 67 89 ab + + After programming a MAC address, consider locking the MAC fuses. This is + done by programming the MAC_ADDR_LOCK fuse, which is bit 4 of word 0 in + bank 1: + + => fuse prog -y 1 0 10 diff --git a/roms/u-boot/doc/imx/common/imx6.txt b/roms/u-boot/doc/imx/common/imx6.txt new file mode 100644 index 000000000..0b5061128 --- /dev/null +++ b/roms/u-boot/doc/imx/common/imx6.txt @@ -0,0 +1,164 @@ +U-Boot for Freescale i.MX6 + +This file contains information for the port of U-Boot to the Freescale i.MX6 +SoC. + +1. CONVENTIONS FOR FUSE ASSIGNMENTS +----------------------------------- + +1.1 MAC Address: It is stored in fuse bank 4, with the 32 lsbs in word 2 and the + 16 msbs in word 3[15:0]. + For i.MX6SX and i.MX6UL, they have two MAC addresses. The second MAC address + is stored in fuse bank 4, with the 16 lsb in word 3[31:16] and the 32 msbs in + word 4. + +Example: + +For reading the MAC address fuses on a MX6Q: + +- The MAC address is stored in two fuse addresses (the fuse addresses are +described in the Fusemap Descriptions table from the mx6q Reference Manual): + +0x620[31:0] - MAC_ADDR[31:0] +0x630[15:0] - MAC_ADDR[47:32] + +In order to use the fuse API, we need to pass the bank and word values, which +are calculated as below: + +Fuse address for the lower MAC address: 0x620 +Base address for the fuses: 0x400 + +(0x620 - 0x400)/0x10 = 0x22 = 34 decimal + +As the fuses are arranged in banks of 8 words: + +34 / 8 = 4 and the remainder is 2, so in this case: + +bank = 4 +word = 2 + +And the U-Boot command would be: + +=> fuse read 4 2 +Reading bank 4: + +Word 0x00000002: 9f027772 + +Doing the same for the upper MAC address: + +Fuse address for the upper MAC address: 0x630 +Base address for the fuses: 0x400 + +(0x630 - 0x400)/0x10 = 0x23 = 35 decimal + +As the fuses are arranged in banks of 8 words: + +35 / 8 = 4 and the remainder is 3, so in this case: + +bank = 4 +word = 3 + +And the U-Boot command would be: + +=> fuse read 4 3 +Reading bank 4: + +Word 0x00000003: 00000004 + +,which matches the ethaddr value: +=> echo ${ethaddr} +00:04:9f:02:77:72 + +Some other useful hints: + +- The 'bank' and 'word' numbers can be easily obtained from the mx6 Reference +Manual. For the mx6quad case, please check the "46.5 OCOTP Memory Map/Register +Definition" from the "i.MX 6Dual/6Quad Applications Processor Reference Manual, +Rev. 1, 04/2013" document. For example, for the MAC fuses we have: + +Address: +21B_C620 Value of OTP Bank4 Word2 (MAC Address)(OCOTP_MAC0) + +21B_C630 Value of OTP Bank4 Word3 (MAC Address)(OCOTP_MAC1) + +- The command '=> fuse read 4 2 2' reads the whole MAC addresses at once: + +=> fuse read 4 2 2 +Reading bank 4: + +Word 0x00000002: 9f027772 00000004 + +NAND Boot on i.MX6 with SPL support +-------------------------------------- + +Writing/updating boot image in nand device is not straight forward in +i.MX6 platform and it requires boot control block(BCB) to be configured. + +BCB contains two data structures, Firmware Configuration Block(FCB) and +Discovered Bad Block Table(DBBT). FCB has nand timings, DBBT search area, +and firmware. See IMX6DQRM Section 8.5.2.2 +for more information. + +We can't use 'nand write' command to write SPL/firmware image directly +like other platforms does. So we need special setup to write BCB block +as per IMX6QDL reference manual 'nandbcb update' command do that job. + +for nand boot, up on reset bootrom look for FCB structure in +first block's if FCB found the nand timings are loaded for +further reads. once FCB read done, DTTB will be loaded and +finally firmware will be loaded which is boot image. + +cmd_nandbcb will create FCB these structures +by taking mtd partition as an example. +- initial code will erase entire partition +- followed by FCB setup, like first 2 blocks for FCB/DBBT write, + and next block for FW1/SPL +- write firmware at FW1 block and +- finally write fcb/dttb in first 2 block. + +Typical NAND BCB layout: +======================= + + no.of blocks = partition size / erasesize + no.of fcb/dbbt blocks = 2 + FW1 offset = no.of fcb/dbbt + +block 0 1 2 + ------------------------------- + |FCB/DBBT 0|FCB/DBBT 1| FW 1 | + -------------------------------- + +On summary, nandbcb update will +- erase the entire partition +- create BCB by creating 2 FCB/BDDT block followed by + 1 FW blocks based on partition size and erasesize. +- fill FCB/DBBT structures +- write FW/SPL in FW1 +- write FCB/DBBT in first 2 blocks + +step-1: write SPL + +icorem6qdl> ext4load mmc 0:1 $loadaddr SPL +39936 bytes read in 10 ms (3.8 MiB/s) + +icorem6qdl> nandbcb update $loadaddr spl $filesize +device 0 offset 0x0, size 0x9c00 +Erasing at 0x1c0000 -- 100% complete. +NAND fw write: 0x80000 offset, 0xb000 bytes written: OK + +step-2: write u-boot-dtb.img + +icorem6qdl> nand erase.part uboot + +NAND erase.part: device 0 offset 0x200000, size 0x200000 +Erasing at 0x3c0000 -- 100% complete. +OK + +icorem6qdl> ext4load mmc 0:1 $loadaddr u-boot-dtb.img +589094 bytes read in 37 ms (15.2 MiB/s) + +icorem6qdl> nand write ${loadaddr} uboot ${filesize} + +NAND write: device 0 offset 0x200000, size 0x8fd26 + 589094 bytes written: OK +icorem6qdl> diff --git a/roms/u-boot/doc/imx/common/mxs.txt b/roms/u-boot/doc/imx/common/mxs.txt new file mode 100644 index 000000000..372062c0e --- /dev/null +++ b/roms/u-boot/doc/imx/common/mxs.txt @@ -0,0 +1,290 @@ +Booting U-Boot on a MXS processor +================================= + +This document describes the MXS U-Boot port. This document mostly covers topics +related to making the module/board bootable. + +Terminology +----------- + +The term "MXS" refers to a family of Freescale SoCs that is composed by MX23 +and MX28. + +The dollar symbol ($) introduces a snipped of shell code. This shall be typed +into the unix command prompt in U-Boot source code root directory. + +The (=>) introduces a snipped of code that should by typed into U-Boot command +prompt + +Contents +-------- + +1) Prerequisites +2) Compiling U-Boot for a MXS based board +3) Installation of U-Boot for a MXS based board to SD card +4) Installation of U-Boot into NAND flash on a MX28 based board +5) Installation of U-Boot into SPI NOR flash on a MX28 based board + +1) Prerequisites +---------------- + +To make a MXS based board bootable, some tools are necessary. The only +mandatory tool is the "mxsboot" tool found in U-Boot source tree. The +tool is built automatically when compiling U-Boot for i.MX23 or i.MX28. + +The production of BootStream image is handled via "mkimage", which is +also part of the U-Boot source tree. The "mkimage" requires OpenSSL +development libraries to be installed. In case of Debian and derivates, +this is installed by running: + + $ sudo apt-get install libssl-dev + +NOTE: The "elftosb" tool distributed by Freescale Semiconductor is no + longer necessary for general use of U-Boot on i.MX23 and i.MX28. + The mkimage supports generation of BootStream images encrypted + with a zero key, which is the vast majority of use-cases. In + case you do need to produce image encrypted with non-zero key + or other special features, please use the "elftosb" tool, + otherwise continue to section 2). The installation procedure of + the "elftosb" is outlined below: + +Firstly, obtain the elftosb archive from the following location: + + ftp://ftp.denx.de/pub/tools/elftosb-10.12.01.tar.gz + +We use a $VER variable here to denote the current version. At the time of +writing of this document, that is "10.12.01". To obtain the file from command +line, use: + + $ VER="10.12.01" + $ wget http://repository.timesys.com/buildsources/e/elftosb/elftosb-10.12.01/elftosb-${VER}.tar.gz + +Extract the file: + + $ tar xzf elftosb-${VER}.tar.gz + +Compile the file. We need to manually tell the linker to use also libm: + + $ cd elftosb-${VER}/ + $ make LIBS="-lstdc++ -lm" elftosb + +Optionally, remove debugging symbols from elftosb: + + $ strip bld/linux/elftosb + +Finally, install the "elftosb" binary. The "install" target is missing, so just +copy the binary by hand: + + $ sudo cp bld/linux/elftosb /usr/local/bin/ + +Make sure the "elftosb" binary can be found in your $PATH, in this case this +means "/usr/local/bin/" has to be in your $PATH. + +2) Compiling U-Boot for a MXS based board +------------------------------------------- + +Compiling the U-Boot for a MXS board is straightforward and done as compiling +U-Boot for any other ARM device. For cross-compiler setup, please refer to +ELDK5.0 documentation. First, clean up the source code: + + $ make mrproper + +Next, configure U-Boot for a MXS based board + + $ make <mxs_based_board_name>_config + +Examples: + +1. For building U-Boot for Aries M28EVK board: + + $ make m28evk_config + +2. For building U-Boot for Freescale MX28EVK board: + + $ make mx28evk_config + +3. For building U-Boot for Freescale MX23EVK board: + + $ make mx23evk_config + +4. For building U-Boot for Olimex MX23 Olinuxino board: + + $ make mx23_olinuxino_config + +Lastly, compile U-Boot and prepare a "BootStream". The "BootStream" is a special +type of file, which MXS CPUs can boot. This is handled by the following +command: + + $ make u-boot.sb + +HINT: To speed-up the build process, you can add -j<N>, where N is number of + compiler instances that'll run in parallel. + +The code produces "u-boot.sb" file. This file needs to be augmented with a +proper header to allow successful boot from SD or NAND. Adding the header is +discussed in the following chapters. + +NOTE: The process that produces u-boot.sb uses the mkimage to generate the + BootStream. The BootStream is encrypted with zero key. In case you need + some special features of the BootStream and plan on using the "elftosb" + tool instead, the invocation to produce a compatible BootStream with the + one produced by mkimage is outlined below. For further details, refer to + the documentation bundled with the "elftosb" package. + + $ elftosb -zf imx23 -c arch/arm/cpu/arm926ejs/mxs/u-boot-imx23.bd \ + -o u-boot.sb + $ elftosb -zf imx28 -c arch/arm/cpu/arm926ejs/mxs/u-boot-imx28.bd \ + -o u-boot.sb + +3) Installation of U-Boot for a MXS based board to SD card +---------------------------------------------------------- + +To boot a MXS based board from SD, set the boot mode DIP switches according to +to MX28 manual, section 12.2.1 (Table 12-2) or MX23 manual, section 35.1.2 +(Table 35-3). + +The SD card used to boot U-Boot must contain a DOS partition table, which in +turn carries a partition of special type and which contains a special header. +The rest of partitions in the DOS partition table can be used by the user. + +To prepare such partition, use your favourite partitioning tool. The partition +must have the following parameters: + + * Start sector .......... sector 2048 + * Partition size ........ at least 1024 kb + * Partition type ........ 0x53 (sometimes "OnTrack DM6 Aux3") + +For example in Linux fdisk, the sequence for a clear card follows. Be sure to +run fdisk with the option "-u=sectors" to set units to sectors: + + * o ..................... create a clear partition table + * n ..................... create new partition + * p ............. primary partition + * 1 ............. first partition + * 2048 .......... first sector is 2048 + * +1M ........... make the partition 1Mb big + * t 1 ................... change first partition ID + * 53 ............ change the ID to 0x53 (OnTrack DM6 Aux3) + * <create other partitions> + * w ..................... write partition table to disk + +The partition layout is ready, next the special partition must be filled with +proper contents. The contents is generated by running the following command +(see chapter 2)): + + $ ./tools/mxsboot sd u-boot.sb u-boot.sd + +The resulting file, "u-boot.sd", shall then be written to the partition. In this +case, we assume the first partition of the SD card is /dev/mmcblk0p1: + + $ dd if=u-boot.sd of=/dev/mmcblk0p1 + +Last step is to insert the card into the MXS based board and boot. + +NOTE: If the user needs to adjust the start sector, the "mxsboot" tool contains + a "-p" switch for that purpose. The "-p" switch takes the sector number as + an argument. + +4) Installation of U-Boot into NAND flash on a MX28 based board +--------------------------------------------------------------- + +To boot a MX28 based board from NAND, set the boot mode DIP switches according +to MX28 manual section 12.2.1 (Table 12-2), PORT=GPMI, NAND 1.8 V. + +There are two possibilities when preparing an image writable to NAND flash. + + I) The NAND wasn't written at all yet or the BCB is broken + ---------------------------------------------------------- + In this case, both BCB (FCB and DBBT) and firmware needs to be + written to NAND. To generate NAND image containing all these, + there is a tool called "mxsboot" in the "tools/" directory. The tool + is invoked on "u-boot.sb" file from chapter 2): + + $ ./tools/mxsboot nand u-boot.sb u-boot.nand + + NOTE: The above invokation works for NAND flash with geometry of + 2048b per page, 64b OOB data, 128kb erase size. If your chip + has a different geometry, please use: + + -w <size> change page size (default 2048 b) + -o <size> change oob size (default 64 b) + -e <size> change erase size (default 131072 b) + + The geometry information can be obtained from running U-Boot + on the MX28 board by issuing the "nand info" command. + + The resulting file, "u-boot.nand" can be written directly to NAND + from the U-Boot prompt. To simplify the process, the U-Boot default + environment contains script "update_nand_full" to update the system. + + This script expects a working TFTP server containing the file + "u-boot.nand" in it's root directory. This can be changed by + adjusting the "update_nand_full_filename" variable. + + To update the system, run the following in U-Boot prompt: + + => run update_nand_full + + In case you would only need to update the bootloader in future, + see II) below. + + II) The NAND was already written with a good BCB + ------------------------------------------------ + This part applies after the part I) above was done at least once. + + If part I) above was done correctly already, there is no need to + write the FCB and DBBT parts of NAND again. It's possible to upgrade + only the bootloader image. + + To simplify the process of firmware update, the U-Boot default + environment contains script "update_nand_firmware" to update only + the firmware, without rewriting FCB and DBBT. + + This script expects a working TFTP server containing the file + "u-boot.sb" in it's root directory. This can be changed by + adjusting the "update_nand_firmware_filename" variable. + + To update the system, run the following in U-Boot prompt: + + => run update_nand_firmware + + III) Special settings for the update scripts + -------------------------------------------- + There is a slight possibility of the user wanting to adjust the + STRIDE and COUNT options of the NAND boot. For description of these, + see MX28 manual section 12.12.1.2 and 12.12.1.3. + + The update scripts take this possibility into account. In case the + user changes STRIDE by blowing fuses, the user also has to change + "update_nand_stride" variable. In case the user changes COUNT by + blowing fuses, the user also has to change "update_nand_count" + variable for the update scripts to work correctly. + + In case the user needs to boot a firmware image bigger than 1Mb, the + user has to adjust the "update_nand_firmware_maxsz" variable for the + update scripts to work properly. + +5) Installation of U-Boot into SPI NOR flash on a MX28 based board +------------------------------------------------------------------ + +The u-boot.sb file can be directly written to SPI NOR from U-Boot prompt. + +Load u-boot.sb into RAM, this can be done in several ways and one way is to use +tftp: + => tftp u-boot.sb 0x42000000 + +Probe the SPI NOR flash: + => sf probe + +(SPI NOR should be succesfully detected in this step) + +Erase the blocks where U-Boot binary will be written to: + => sf erase 0x0 0x80000 + +Write u-boot.sb to SPI NOR: + => sf write 0x42000000 0 0x80000 + +Power off the board and set the boot mode DIP switches to boot from the SPI NOR +according to MX28 manual section 12.2.1 (Table 12-2) + +Last step is to power up the board and U-Boot should start from SPI NOR. diff --git a/roms/u-boot/doc/imx/habv4/csf_examples/additional_images/csf_additional_images.txt b/roms/u-boot/doc/imx/habv4/csf_examples/additional_images/csf_additional_images.txt new file mode 100644 index 000000000..bbe489714 --- /dev/null +++ b/roms/u-boot/doc/imx/habv4/csf_examples/additional_images/csf_additional_images.txt @@ -0,0 +1,34 @@ +[Header] + Version = 4.2 + Hash Algorithm = sha256 + Engine Configuration = 0 + Certificate Format = X509 + Signature Format = CMS + Engine = CAAM + +[Install SRK] + # Index of the key location in the SRK table to be installed + File = "../crts/SRK_1_2_3_4_table.bin" + Source index = 0 + +[Install CSFK] + # Key used to authenticate the CSF data + File = "../crts/CSF1_1_sha256_2048_65537_v3_usr_crt.pem" + +[Authenticate CSF] + +[Install Key] + # Key slot index used to authenticate the key to be installed + Verification index = 0 + # Target key slot in HAB key store where key will be installed + Target Index = 2 + # Key to install + File= "../crts/IMG1_1_sha256_2048_65537_v3_usr_crt.pem" + +[Authenticate Data] + # Key slot index used to authenticate the image data + Verification index = 2 + # Authenticate Start Address, Offset, Length and file + Blocks = 0x80800000 0x00000000 0x80EEA020 "zImage", \ + 0x83800000 0x00000000 0x8380B927 "imx7d-sdb.dtb", \ + 0x84000000 0x00000000 0x840425B8 "uTee-7dsdb" diff --git a/roms/u-boot/doc/imx/habv4/csf_examples/mx6_mx7/csf_uboot.txt b/roms/u-boot/doc/imx/habv4/csf_examples/mx6_mx7/csf_uboot.txt new file mode 100644 index 000000000..39986243e --- /dev/null +++ b/roms/u-boot/doc/imx/habv4/csf_examples/mx6_mx7/csf_uboot.txt @@ -0,0 +1,32 @@ +[Header] + Version = 4.2 + Hash Algorithm = sha256 + Engine Configuration = 0 + Certificate Format = X509 + Signature Format = CMS + Engine = CAAM + +[Install SRK] + # Index of the key location in the SRK table to be installed + File = "../crts/SRK_1_2_3_4_table.bin" + Source index = 0 + +[Install CSFK] + # Key used to authenticate the CSF data + File = "../crts/CSF1_1_sha256_2048_65537_v3_usr_crt.pem" + +[Authenticate CSF] + +[Install Key] + # Key slot index used to authenticate the key to be installed + Verification index = 0 + # Target key slot in HAB key store where key will be installed + Target Index = 2 + # Key to install + File= "../crts/IMG1_1_sha256_2048_65537_v3_usr_crt.pem" + +[Authenticate Data] + # Key slot index used to authenticate the image data + Verification index = 2 + # Authenticate Start Address, Offset, Length and file + Blocks = 0x877ff400 0x00000000 0x0009ec00 "u-boot-dtb.imx" diff --git a/roms/u-boot/doc/imx/habv4/csf_examples/mx6_mx7/csf_uboot_fast_authentication.txt b/roms/u-boot/doc/imx/habv4/csf_examples/mx6_mx7/csf_uboot_fast_authentication.txt new file mode 100644 index 000000000..cdb34bcf7 --- /dev/null +++ b/roms/u-boot/doc/imx/habv4/csf_examples/mx6_mx7/csf_uboot_fast_authentication.txt @@ -0,0 +1,23 @@ +[Header] + Version = 4.2 + Hash Algorithm = sha256 + Engine Configuration = 0 + Certificate Format = X509 + Signature Format = CMS + Engine = CAAM + +[Install SRK] + # Index of the key location in the SRK table to be installed + File = "../crts/SRK_1_2_3_4_table.bin" + Source index = 0 + +[Install NOCAK] + File = "../crts/SRK1_sha256_2048_65537_v3_usr_crt.pem" + +[Authenticate CSF] + +[Authenticate Data] + # Key slot index 0 used to authenticate the image data + Verification index = 0 + # Authenticate Start Address, Offset, Length and file + Blocks = 0x877ff400 0x00000000 0x0009ec00 "u-boot-dtb.imx" diff --git a/roms/u-boot/doc/imx/habv4/guides/encrypted_boot.txt b/roms/u-boot/doc/imx/habv4/guides/encrypted_boot.txt new file mode 100644 index 000000000..e2b435749 --- /dev/null +++ b/roms/u-boot/doc/imx/habv4/guides/encrypted_boot.txt @@ -0,0 +1,43 @@ +1. Setup U-Boot Image for Encrypted Boot +---------------------------------------- +An authenticated U-Boot image is used as starting point for +Encrypted Boot. The image is encrypted by i.MX Code Signing +Tool (CST). The CST replaces only the image data of +u-boot-dtb.imx with the encrypted data. The Initial Vector Table, +DCD, and Boot data, remains in plaintext. + +The image data is encrypted with a Encryption Key (DEK). +Therefore, this key is needed to decrypt the data during the +booting process. The DEK is protected by wrapping it in a Blob, +which needs to be appended to the U-Boot image and specified in +the CSF file. + +The DEK blob is generated by an authenticated U-Boot image with +the dek_blob cmd enabled. The image used for DEK blob generation +needs to have the following configurations enabled in Kconfig: + +CONFIG_IMX_HAB=y +CONFIG_CMD_DEKBLOB=y + +Note: The encrypted boot feature is only supported by HABv4 or +greater. + +The dek_blob command then can be used to generate the DEK blob of +a DEK previously loaded in memory. The command is used as follows: + +dek_blob <DEK address> <Output Address> <Key Size in Bits> +example: dek_blob 0x10800000 0x10801000 192 + +The resulting DEK blob then is used to construct the encrypted +U-Boot image. Note that the blob needs to be transferred back +to the host.Then the following commands are used to construct +the final image. + +cat u-boot-dtb.imx csf-u-boot.bin > u-boot-signed.imx +objcopy -I binary -O binary --pad-to <blob_dst> --gap-fill=0x00 \ + u-boot-signed.imx u-boot-signed-pad.bin +cat u-boot-signed-pad.imx DEK_blob.bin > u-boot-encrypted.imx + + NOTE: u-boot-signed.bin needs to be padded to the value + equivalent to the address in which the DEK blob is specified + in the CSF. diff --git a/roms/u-boot/doc/imx/habv4/guides/mx6_mx7_secure_boot.txt b/roms/u-boot/doc/imx/habv4/guides/mx6_mx7_secure_boot.txt new file mode 100644 index 000000000..53f71fbc3 --- /dev/null +++ b/roms/u-boot/doc/imx/habv4/guides/mx6_mx7_secure_boot.txt @@ -0,0 +1,427 @@ + +=======================================================+ + + i.MX6, i.MX7 U-Boot Secure Boot guide using HABv4 + + +=======================================================+ + +1. HABv4 secure boot process +----------------------------- + +This document describes a step-by-step procedure on how to sign and securely +boot an U-Boot image for non-SPL targets. It is assumed that the reader is +familiar with basic HAB concepts and with the PKI tree generation. + +Details about HAB can be found in the application note AN4581[1] and in the +introduction_habv4.txt document. + +1.1 Building a u-boot-dtb.imx image supporting secure boot +----------------------------------------------------------- + +The U-Boot provides support to secure boot configuration and also provide +access to the HAB APIs exposed by the ROM vector table, the support is +enabled by selecting the CONFIG_IMX_HAB option. + +When built with this configuration, the U-Boot provides extra functions for +HAB, such as the HAB status logs retrievement through the hab_status command +and support for extending the root of trust. + +The U-Boot also correctly pads the final image by aligning to the next 0xC00 +address, so the CSF signature data generated by CST can be concatenated to +image. + +The diagram below illustrate a signed u-boot-dtb.imx image layout: + + ------- +-----------------------------+ <-- *start + ^ | Image Vector Table | + | +-----------------------------+ <-- *boot_data + | | Boot Data | + | +-----------------------------+ <-- *dcd + | | DCD Table | + | +-----------------------------+ + Signed | | Padding | + Data | +-----------------------------+ <-- *entry + | | | + | | | + | | u-boot-dtb.bin | + | | | + | | | + | +-----------------------------+ + v | Padding | + ------- +-----------------------------+ <-- *csf + | | + | Command Sequence File (CSF) | + | | + +-----------------------------+ + | Padding (optional) | + +-----------------------------+ + +1.2 Enabling the secure boot support +------------------------------------- + +The first step is to generate an U-Boot image supporting the HAB features +mentioned above, this can be achieved by adding CONFIG_IMX_HAB to the +build configuration: + +- Defconfig: + + CONFIG_IMX_HAB=y + +- Kconfig: + + ARM architecture -> Support i.MX HAB features + +1.3 Creating the CSF description file +-------------------------------------- + +The CSF contains all the commands that the HAB executes during the secure +boot. These commands instruct the HAB on which memory areas of the image +to authenticate, which keys to install, use and etc. + +CSF examples are available under doc/imx/habv4/csf_examples/ directory. + +A build log containing the "Authenticate Data" parameters is available after +the U-Boot build, the example below is a log for mx7dsabresd_defconfig target: + +- mkimage build log: + + $ cat u-boot-dtb.imx.log + + Image Type: Freescale IMX Boot Image + Image Ver: 2 (i.MX53/6/7 compatible) + Mode: DCD + Data Size: 667648 Bytes = 652.00 KiB = 0.64 MiB + Load Address: 877ff420 + Entry Point: 87800000 + HAB Blocks: 0x877ff400 0x00000000 0x0009ec00 + ^^^^^^^^^^ ^^^^^^^^^^ ^^^^^^^^^^ + | | | + | | ------- (1) + | | + | ------------------ (2) + | + ----------------------------- (3) + + (1) Size of area in file u-boot-dtb.imx to sign. + This area should include the IVT, the Boot Data the DCD + and the U-Boot itself. + (2) Start of area in u-boot-dtb.imx to sign. + (3) Start of area in RAM to authenticate. + +- In "Authenticate Data" CSF command users can copy and past the output + addresses: + + Block = 0x877ff400 0x00000000 0x0009ec00 "u-boot-dtb.imx" + +1.4 Signing the U-Boot binary +------------------------------ + +The CST tool is used for singing the U-Boot binary and generating a CSF binary, +users should input the CSF description file created in the step above and +should receive a CSF binary, which contains the CSF commands, SRK table, +signatures and certificates. + +- Create CSF binary file: + + $ ./cst -i csf_uboot.txt -o csf_uboot.bin + +- Append CSF signature to the end of U-Boot image: + + $ cat u-boot-dtb.imx csf_uboot.bin > u-boot-signed.imx + +The u-boot-signed.imx is the signed binary and should be flashed into the boot +media. + +- Flash signed U-Boot binary: + + $ sudo dd if=u-boot-signed.imx of=/dev/sd<x> bs=1K seek=1 && sync + +1.5 Programming SRK Hash +------------------------- + +As explained in AN4581[1] and in introduction_habv4.txt document the SRK Hash +fuse values are generated by the srktool and should be programmed in the +SoC SRK_HASH[255:0] fuses. + +Be careful when programming these values, as this data is the basis for the +root of trust. An error in SRK Hash results in a part that does not boot. + +The U-Boot fuse tool can be used for programming eFuses on i.MX SoCs. + +- Dump SRK Hash fuses values in host machine: + + $ hexdump -e '/4 "0x"' -e '/4 "%X""\n"' SRK_1_2_3_4_fuse.bin + 0x20593752 + 0x6ACE6962 + 0x26E0D06C + 0xFC600661 + 0x1240E88F + 0x1209F144 + 0x831C8117 + 0x1190FD4D + +- Program SRK_HASH[255:0] fuses, using i.MX6 series as example: + + => fuse prog 3 0 0x20593752 + => fuse prog 3 1 0x6ACE6962 + => fuse prog 3 2 0x26E0D06C + => fuse prog 3 3 0xFC600661 + => fuse prog 3 4 0x1240E88F + => fuse prog 3 5 0x1209F144 + => fuse prog 3 6 0x831C8117 + => fuse prog 3 7 0x1190FD4D + +The table below lists the SRK_HASH bank and word according to the i.MX device: + + +-------------------+---------------+---------------+---------------+ + | | i.MX6 Series | i.MX7D/S | i.MX7ULP | + +-------------------+---------------+---------------+---------------+ + | SRK_HASH[31:00] | bank 3 word 0 | bank 6 word 0 | bank 5 word 0 | + +-------------------+---------------+---------------+---------------+ + | SRK_HASH[63:32] | bank 3 word 1 | bank 6 word 1 | bank 5 word 1 | + +-------------------+---------------+---------------+---------------+ + | SRK_HASH[95:64] | bank 3 word 2 | bank 6 word 2 | bank 5 word 2 | + +-------------------+---------------+---------------+---------------+ + | SRK_HASH[127:96] | bank 3 word 3 | bank 6 word 3 | bank 5 word 3 | + +-------------------+---------------+---------------+---------------+ + | SRK_HASH[159:128] | bank 3 word 4 | bank 7 word 0 | bank 5 word 4 | + +-------------------+---------------+---------------+---------------+ + | SRK_HASH[191:160] | bank 3 word 5 | bank 7 word 1 | bank 5 word 5 | + +-------------------+---------------+---------------+---------------+ + | SRK_HASH[223:192] | bank 3 word 6 | bank 7 word 2 | bank 5 word 6 | + +-------------------+---------------+---------------+---------------+ + | SRK_HASH[255:224] | bank 3 word 7 | bank 7 word 3 | bank 5 word 7 | + +-------------------+---------------+---------------+---------------+ + +1.6 Verifying HAB events +------------------------- + +The next step is to verify that the signature attached to U-Boot is +successfully processed without errors. HAB generates events when processing +the commands if it encounters issues. + +The hab_status U-Boot command call the hab_report_event() and hab_status() +HAB API functions to verify the processor security configuration and status. +This command displays any events that were generated during the process. + +Prior to closing the device users should ensure no HAB events were found, as +the example below: + +- Verify HAB events: + + => hab_status + + Secure boot disabled + + HAB Configuration: 0xf0, HAB State: 0x66 + No HAB Events Found! + +1.6.1 Verifying HAB events in i.MX7ULP +--------------------------------------- + +When booting i.MX7ULP in low power or dual boot modes the M4 binary is +authenticated by an independent HAB in M4 ROM code using a +different SRK key set. + +The U-Boot provides a M4 option in hab_status command so users can retrieve +M4 HAB failure and warning events. + +- Verify HAB M4 events: + + => hab_status m4 + + Secure boot disabled + + HAB Configuration: 0xf0, HAB State: 0x66 + No HAB Events Found! + +As HAB M4 API cannot be called from A7 core the command is parsing the M4 HAB +persistent memory region, M4 software should not modify this reserved region. + +Details about HAB persistent memory region can be found in AN12263[2]. + +1.7 Closing the device +----------------------- + +After the device successfully boots a signed image without generating any HAB +events, it is safe to close the device. This is the last step in the HAB +process, and is achieved by programming the SEC_CONFIG[1] fuse bit. + +Once the fuse is programmed, the chip does not load an image that has not been +signed using the correct PKI tree. + +- Program SEC_CONFIG[1] fuse, using i.MX6 series as example: + + => fuse prog 0 6 0x00000002 + +The table below list the SEC_CONFIG[1] bank and word according to the i.MX +device: + + +--------------+-----------------+------------+ + | Device | Bank and Word | Value | + +--------------+-----------------+------------+ + | i.MX6 Series | bank 0 word 6 | 0x00000002 | + +--------------+-----------------+------------+ + | i.MX7D/S | bank 1 word 3 | 0x02000000 | + +--------------+-----------------+------------+ + | i.MX7ULP | bank 29 word 6 | 0x80000000 | + +--------------+-----------------+------------+ + +1.8 Completely secure the device +--------------------------------- + +Additional fuses can be programmed for completely secure the device, more +details about these fuses and their possible impact can be found at AN4581[1]. + +- Program SRK_LOCK, using i.MX6 series as example: + + => fuse prog 0 0 0x4000 + +- Program DIR_BT_DIS, using i.MX6 series as example: + + => fuse prog 0 6 0x8 + +- Program SJC_DISABLE, using i.MX6 series as example: + + => fuse prog 0 6 0x100000 + +- JTAG_SMODE, using i.MX6 series as example: + + => fuse prog 0 6 0xC00000 + +The table below list the SRK_LOCK, DIR_BT_DIS, SJC_DISABLE, and JTAG_SMODE bank +and word according to the i.MX device: + + +--------------+---------------+------------+ + | Device | Bank and Word | Value | + +--------------+---------------+------------+ + | SRK_LOCK | + +-------------------------------------------+ + | i.MX6 Series | bank 0 word 0 | 0x00004000 | + +--------------+---------------+------------+ + | i.MX7D/S | bank 0 word 0 | 0x00000200 | + +--------------+---------------+------------+ + | i.MX7ULP | bank 1 word 1 | 0x00000080 | + +--------------+---------------+------------+ + | DIR_BT_DIS | + +-------------------------------------------+ + | i.MX6 Series | bank 0 word 6 | 0x00000008 | + +--------------+---------------+------------+ + | i.MX7D/S | bank 1 word 3 | 0x08000000 | + +--------------+---------------+------------+ + | i.MX7ULP | bank 1 word 1 | 0x00002000 | + +--------------+---------------+------------+ + | SJC_DISABLE | + +-------------------------------------------+ + | i.MX6 Series | bank 0 word 6 | 0x00100000 | + +--------------+---------------+------------+ + | i.MX7D/S | bank 1 word 3 | 0x00200000 | + +--------------+---------------+------------+ + | i.MX7ULP | bank 1 word 1 | 0x00000020 | + +--------------+---------------+------------+ + | JTAG_SMODE | + +-------------------------------------------+ + | i.MX6 Series | bank 0 word 6 | 0x00C00000 | + +--------------+---------------+------------+ + | i.MX7D/S | bank 1 word 3 | 0x00C00000 | + +--------------+---------------+------------+ + | i.MX7ULP | bank 1 word 1 | 0x000000C0 | + +--------------+---------------+------------+ + +2. Extending the root of trust +------------------------------- + +The High Assurance Boot (HAB) code located in the on-chip ROM provides an +Application Programming Interface (API) making it possible to call back +into the HAB code for authenticating additional boot images. + +The U-Boot supports this feature and can be used to authenticate the Linux +Kernel Image. + +The process of signing an additional image is similar to the U-Boot. +The diagram below illustrate the zImage layout: + + ------- +-----------------------------+ <-- *load_address + ^ | | + | | | + | | | + | | | + | | zImage | + Signed | | | + Data | | | + | | | + | +-----------------------------+ + | | Padding Next Boundary | + | +-----------------------------+ <-- *ivt + v | Image Vector Table | + ------- +-----------------------------+ <-- *csf + | | + | Command Sequence File (CSF) | + | | + +-----------------------------+ + | Padding (optional) | + +-----------------------------+ + +2.1 Padding the image +---------------------- + +The zImage must be padded to the next boundary address (0x1000), for instance +if the image size is 0x649920 it must be padded to 0x64A000. + +The tool objcopy can be used for padding the image. + +- Pad the zImage: + + $ objcopy -I binary -O binary --pad-to 0x64A000 --gap-fill=0x00 \ + zImage zImage_pad.bin + +2.2 Generating Image Vector Table +---------------------------------- + +The HAB code requires an Image Vector Table (IVT) for determining the image +length and the CSF location. Since zImage does not include an IVT this has +to be manually created and appended to the end of the padded zImage, the +script genIVT.pl in script_examples directory can be used as reference. + +- Generate IVT: + + $ genIVT.pl + +Note: The load Address may change depending on the device. + +- Append the ivt.bin at the end of the padded zImage: + + $ cat zImage_pad.bin ivt.bin > zImage_pad_ivt.bin + +2.3 Signing the image +---------------------- + +A CSF file has to be created to sign the image. HAB does not allow to change +the SRK once the first image is authenticated, so the same SRK key used in +U-Boot must be used when extending the root of trust. + +CSF examples are available in ../csf_examples/additional_images/ +directory. + +- Create CSF binary file: + + $ ./cst --i csf_additional_images.txt --o csf_zImage.bin + +- Attach the CSF binary to the end of the image: + + $ cat zImage_pad_ivt.bin csf_zImage.bin > zImage_signed.bin + +2.4 Verifying HAB events +------------------------- + +The U-Boot includes the hab_auth_img command which can be used for +authenticating and troubleshooting the signed image, zImage must be +loaded at the load address specified in the IVT. + +- Authenticate additional image: + + => hab_auth_img <Load Address> <Image Size> <IVT Offset> + +If no HAB events were found the zImage is successfully signed. + +References: +[1] AN4581: "Secure Boot on i.MX 50, i.MX 53, i.MX 6 and i.MX 7 Series using + HABv4" - Rev 2. +[2] AN12263: "HABv4 RVT Guidelines and Recommendations" - Rev 0. diff --git a/roms/u-boot/doc/imx/habv4/guides/mx6_mx7_spl_secure_boot.txt b/roms/u-boot/doc/imx/habv4/guides/mx6_mx7_spl_secure_boot.txt new file mode 100644 index 000000000..fde0f27ef --- /dev/null +++ b/roms/u-boot/doc/imx/habv4/guides/mx6_mx7_spl_secure_boot.txt @@ -0,0 +1,181 @@ + +===============================================================+ + + i.MX6, i.MX7 U-Boot HABv4 Secure Boot guide for SPL targets + + +===============================================================+ + +1. HABv4 secure boot process +----------------------------- + +This document is an addendum of mx6_mx7_secure_boot.txt guide describing a +step-by-step procedure on how to sign and securely boot an U-Boot image for +SPL targets. + +Details about HAB can be found in the application note AN4581[1] and in the +introduction_habv4.txt document. + +1.1 Building a SPL target supporting secure boot +------------------------------------------------- + +The U-Boot provides Second Program Loader (SPL) support which generates two +final images, SPL and U-Boot proper. The HABv4 can be used to authenticate +both binaries. + +Out of reset the ROM code authenticates the SPL which is responsible for +initializing essential features such as DDR, UART, PMIC and clock +enablement. Once the DDR is available, the SPL code loads the U-Boot proper +image to its specific execution address and call the HAB APIs to extend the +root of trust. + +The U-Boot provides support to secure boot configuration and also provide +access to the HAB APIs exposed by the ROM vector table, the support is +enabled by selecting the CONFIG_IMX_HAB option. + +When built with this configuration the U-Boot correctly pads the final SPL +image by aligning to the next 0xC00 address, so the CSF signature data +generated by CST can be concatenated to the image. + +The U-Boot also append an Image Vector Table (IVT) in the final U-Boot proper +binary (u-boot-ivt.img) so it can be used by HAB API in a post ROM stage. + +The diagram below illustrate a signed SPL image layout: + + ------- +-----------------------------+ <-- *start + ^ | Image Vector Table | + | +-----------------------------+ <-- *boot_data + | | Boot Data | + | +-----------------------------+ + Signed | | Padding | + Data | +-----------------------------+ <-- *entry + | | | + | | SPL | + | | | + | +-----------------------------+ + v | Padding | + ------- +-----------------------------+ <-- *csf + | | + | Command Sequence File (CSF) | + | | + +-----------------------------+ + | Padding (optional) | + +-----------------------------+ + +The diagram below illustrate a signed u-boot-ivt.img image layout: + + ------- +-----------------------------+ <-- *load_address + ^ | | + | | | + | | u-boot.img | + Signed | | | + Data | | | + | +-----------------------------+ + | | Padding Next Boundary | + | +-----------------------------+ <-- *ivt + v | Image Vector Table | + ------- +-----------------------------+ <-- *csf + | | + | Command Sequence File (CSF) | + | | + +-----------------------------+ + | Padding (optional) | + +-----------------------------+ + +1.2 Enabling the secure boot support +------------------------------------- + +The first step is to generate an U-Boot image supporting the HAB features +mentioned above, this can be achieved by adding CONFIG_IMX_HAB to the +build configuration: + +- Defconfig: + + CONFIG_IMX_HAB=y + +- Kconfig: + + ARM architecture -> Support i.MX HAB features + +1.3 Creating the CSF description file +-------------------------------------- + +The CSF contains all the commands that the HAB executes during the secure +boot. These commands instruct the HAB code on which memory areas of the image +to authenticate, which keys to install, use and etc. + +CSF examples are available under doc/imx/habv4/csf_examples/ directory. + +Build logs containing the "Authenticate Data" parameters are available after +the U-Boot build, the example below is a log for mx6sabresd_defconfig target: + +- SPL build log: + + $ cat SPL.log + Image Type: Freescale IMX Boot Image + Image Ver: 2 (i.MX53/6/7 compatible) + Mode: DCD + Data Size: 69632 Bytes = 68.00 KiB = 0.07 MiB + Load Address: 00907420 + Entry Point: 00908000 + HAB Blocks: 0x00907400 0x00000000 0x0000ec00 + +- u-boot-ivt.img build log: + + $ cat u-boot-ivt.img.log + Image Name: U-Boot 2019.01-00003-g78ee492eb3 + Created: Mon Jan 14 17:58:10 2019 + Image Type: ARM U-Boot Firmware with HABv4 IVT (uncompressed) + Data Size: 458688 Bytes = 447.94 KiB = 0.44 MiB + Load Address: 17800000 + Entry Point: 00000000 + HAB Blocks: 0x177fffc0 0x0000 0x0006e020 + +As explained in section above the SPL is first authenticated by the ROM code +and the root of trust is extended to the U-Boot image, hence two CSF files are +necessary to completely sign a bootloader image. + +In "Authenticate Data" CSF command users can copy and past the output +addresses, the csf_uboot.txt can be used as example: + +- In csf_SPL.txt: + + Block = 0x00907400 0x00000000 0x0000ec00 "SPL" + +- In csf_uboot-ivt.txt: + + Block = 0x177fffc0 0x0000 0x0006e020 "u-boot-ivt.img" + +1.4 Signing the images +----------------------- + +The CST tool is used for singing the U-Boot binary and generating a CSF binary, +users should input the CSF description file created in the step above and +receive a CSF binary, which contains the CSF commands, SRK table, signatures +and certificates. + +- Create SPL CSF binary file: + + $ ./cst -i csf_SPL.txt -o csf_SPL.bin + +- Append CSF signature to the end of SPL image: + + $ cat SPL csf_SPL.bin > SPL-signed + +- Create U-Boot proper CSF binary file: + + $ ./cst -i csf_uboot-ivt.txt -o csf_uboot-ivt.bin + +- Append CSF signature to the end of U-Boot proper image: + + $ cat u-boot-ivt.img csf_uboot-ivt.bin > u-boot-signed.img + +The bootloader is signed and can be flashed into the boot media. + +1.5 Closing the device +----------------------- + +The procedure for closing the device is similar as in Non-SPL targets, for a +complete procedure please refer to section "1.5 Programming SRK Hash" in +mx6_mx7_secure_boot.txt document available under doc/imx/habv4/guides/ +directory. + +References: +[1] AN4581: "Secure Boot on i.MX 50, i.MX 53, i.MX 6 and i.MX 7 Series using + HABv4" - Rev 2. diff --git a/roms/u-boot/doc/imx/habv4/introduction_habv4.txt b/roms/u-boot/doc/imx/habv4/introduction_habv4.txt new file mode 100644 index 000000000..25711bbe9 --- /dev/null +++ b/roms/u-boot/doc/imx/habv4/introduction_habv4.txt @@ -0,0 +1,262 @@ + +=======================================================+ + + i.MX Secure and Encrypted Boot using HABv4 + + +=======================================================+ + +1. Introduction +---------------- + +The i.MX family of applications processors provides the High Assurance Boot +(HAB) feature in the on-chip ROM. The ROM is responsible for loading the +initial program image (U-Boot) from the boot media and HAB enables the ROM +to authenticate and/or decrypt the program image by using cryptography +operations. + +This feature is supported in i.MX 50, i.MX 53, i.MX 6, i.MX 7 series and + i.MX 8M, i.MX 8MM devices. + +Step-by-step guides are available under doc/imx/habv4/guides/ directory, +users familiar with HAB and CST PKI tree generation should refer to these +documents instead. + +1.1 The HABv4 Secure Boot Architecture +--------------------------------------- + +The HABv4 secure boot feature uses digital signatures to prevent unauthorized +software execution during the device boot sequence. In case a malware takes +control of the boot sequence, sensitive data, services and network can be +impacted. + +The HAB authentication is based on public key cryptography using the RSA +algorithm in which image data is signed offline using a series of private +keys. The resulting signed image data is then verified on the i.MX processor +using the corresponding public keys. The public keys are included in the CSF +binary and the SRK Hash is programmed in the SoC fuses for establishing the +root of trust. + +The diagram below illustrate the secure boot process overview: + + Host PC + CST i.MX + HAB + +----------+ +----------+ + ---> | U-Boot | | Compare | + | +----------+ +----------+ + | | ^ ^ + | v Reference / \ Generated + | +----------+ Hash / \ Hash + | | Hash | Private / \ + | +----------+ Key / \ + | | | +----------+ +----------+ + | v | | Verify | | Hash | + | +----------+ | +----------+ +----------+ + | | Sign | <--- SRK ^ ^ + | +----------+ HASH \ / + | | | CSF \ / U-Boot + | v v \ / + | +----------+ +----------+ +----------+ + | | U-Boot | | | | U-Boot | + ---> | + | -----> | i.MX | -----> | + | + | CSF | | | | CSF | + +----------+ +----------+ +----------+ + +The U-Boot image to be programmed into the boot media needs to be properly +constructed i.e. it must contain a proper Command Sequence File (CSF). + +The CSF is a binary data structure interpreted by the HAB to guide +authentication process, this is generated by the Code Signing Tool[1]. +The CSF structure contains the commands, SRK table, signatures and +certificates. + +Details about the Secure Boot and Code Signing Tool (CST) can be found in +the application note AN4581[2] and in the secure boot guides. + +1.2 The HABv4 Encrypted Boot Architecture +------------------------------------------ + +The HAB Encrypted Boot feature available in CAAM supported devices adds an +extra security operation to the bootloading sequence. It uses cryptographic +techniques (AES-CCM) to obscure the U-Boot data, so it cannot be seen or used +by unauthorized users. This mechanism protects the U-Boot code residing on +flash or external memory and also ensures that the final image is unique +per device. + +The process can be divided into two protection mechanisms. The first mechanism +is the bootloader code encryption which provides data confidentiality and the +second mechanism is the digital signature, which authenticates the encrypted +image. + +Keep in mind that the encrypted boot makes use of both mechanisms whatever the +order is (sign and then encrypt, or encrypt and then sign), both operations +can be applied on the same region with exception of the U-Boot Header (IVT, +boot data and DCD) which can only be signed, not encrypted. + +The diagram below illustrate the encrypted boot process overview: + + Host PC + CST i.MX + HAB + +------------+ +--------------+ + | U-Boot | | U-Boot | + +------------+ +--------------+ + | ^ + | | + v DEK +--------------+ + +------------+ | ----> | Decrypt | + | Encrypt | <--- | +--------------+ + +------------+ DEK | ^ + | | | + | Private | | + v Key +------+ +--------------+ + +------------+ | | CAAM | | Authenticate | + | Sign | <--- +------+ +--------------+ + +------------+ DEK ^ ^ + | + OTPMK DEK \ / U-Boot + | | Blob \ / + CSF + v v \ / + +------------+ +----------+ +------------+ + | Enc U-Boot | | | | Enc U-Boot | + | + CSF | ----> | i.MX | -------> | + CSF | + | + DEK Blob | | | | + DEK Blob | + +------------+ +----------+ +------------+ + ^ | + | | + --------------------- + DEK Blob + (CAAM) + +The Code Signing Tool automatically generates a random AES Data Encryption Key +(DEK) when encrypting an image. This key is used in both encrypt and decrypt +operations and should be present in the final image structure encapsulated +by a CAAM blob. + +The OTP Master Key (OTPMK) is used to encrypt and wrap the DEK in a blob +structure. The OTPMK is unique per device and can be accessed by CAAM only. +To further add to the security of the DEK, the blob is decapsulated and +decrypted inside a secure memory partition that can only be accessed by CAAM. + +During the design of encrypted boot using DEK blob, it is necessary to inhibit +any modification or replacement of DEK blob with a counterfeit one allowing +execution of malicious code. The PRIBLOB setting in CAAM allows secure boot +software to have its own private blobs that cannot be decapsulated or +encapsulated by any other user code, including any software running in trusted +mode. + +Details about DEK Blob generation and PRIBLOB setting can be found in the +encrypted boot guide and application note AN12056[3] . + +2. Generating a PKI tree +------------------------- + +The first step is to generate the private keys and public keys certificates. +The HAB architecture is based in a Public Key Infrastructure (PKI) tree. + +The Code Signing Tools package contains an OpenSSL based key generation script +under keys/ directory. The hab4_pki_tree.sh script is able to generate a PKI +tree containing up to 4 Super Root Keys (SRK) as well as their subordinated +IMG and CSF keys. + +A new PKI tree can be generated by following the example below: + +- Generating 2048-bit PKI tree on CST v3.1.0: + + $ ./hab4_pki_tree.sh + ... + Do you want to use an existing CA key (y/n)?: n + Do you want to use Elliptic Curve Cryptography (y/n)?: n + Enter key length in bits for PKI tree: 2048 + Enter PKI tree duration (years): 5 + How many Super Root Keys should be generated? 4 + Do you want the SRK certificates to have the CA flag set? (y/n)?: y + +The diagram below illustrate the PKI tree: + + +---------+ + | CA | + +---------+ + | + | + --------------------------------------------------- + | | | | + | | | | + v v v v + +--------+ +--------+ +--------+ +--------+ + | SRK1 | | SRK2 | | SRK3 | | SRK4 | + +--------+ +--------+ +--------+ +--------+ + / \ / \ / \ / \ + v v v v v v v v + +----+ +----+ +----+ +----+ +----+ +----+ +----+ +----+ + |CSF1| |IMG1| |CSF2| |IMG2| |CSF3| |IMG3| |CSF4| |IMG4| + +----+ +----+ +----+ +----+ +----+ +----+ +----+ +----+ + +After running the script users can check the private keys under keys/ directory +and their respective X.509v3 public key certificates under crts/ directory. +Those files will be used during the signing and authentication process. + +2.1 Generating a fast authentication PKI tree +---------------------------------------------- + +Starting in HAB v4.1.2 users can use a single SRK key to authenticate the both +CSF and IMG contents. This reduces the number of key pair authentications that +must occur during the ROM/HAB boot stage, thus providing a faster boot process. + +The script hab4_pki_tree.sh is also able to generate a Public Key Infrastructure +(PKI) tree which only contains SRK Keys, users should not set the CA flag when +generating the SRK certificates. + +- Generating 2048-bit fast authentication PKI tree on CST v3.1.0: + + $ ./hab4_pki_tree.sh + ... + Do you want to use an existing CA key (y/n)?: n + Do you want to use Elliptic Curve Cryptography (y/n)?: n + Enter key length in bits for PKI tree: 2048 + Enter PKI tree duration (years): 5 + How many Super Root Keys should be generated? 4 + Do you want the SRK certificates to have the CA flag set? (y/n)?: n + +The diagram below illustrate the PKI tree generated: + + +---------+ + | CA | + +---------+ + | + | + --------------------------------------------------- + | | | | + | | | | + v v v v + +--------+ +--------+ +--------+ +--------+ + | SRK1 | | SRK2 | | SRK3 | | SRK4 | + +--------+ +--------+ +--------+ +--------+ + +2.2 Generating a SRK Table and SRK Hash +---------------------------------------- + +The next step is to generated the SRK Table and its respective SRK Table Hash +from the SRK public key certificates created in one of the steps above. + +In the HAB architecture, the SRK Table is included in the CSF binary and the +SRK Hash is programmed in the SoC SRK_HASH[255:0] fuses. + +On the target device during the authentication process the HAB code verify the +SRK Table against the SoC SRK_HASH fuses, in case the verification success the +root of trust is established and the HAB code can progress with the image +authentication. + +The srktool can be used for generating the SRK Table and its respective SRK +Table Hash. + +- Generating SRK Table and SRK Hash in Linux 64-bit machines: + + $ ../linux64/bin/srktool -h 4 -t SRK_1_2_3_4_table.bin -e \ + SRK_1_2_3_4_fuse.bin -d sha256 -c \ + SRK1_sha256_2048_65537_v3_ca_crt.pem,\ + SRK2_sha256_2048_65537_v3_ca_crt.pem,\ + SRK3_sha256_2048_65537_v3_ca_crt.pem,\ + SRK4_sha256_2048_65537_v3_ca_crt.pem + +The SRK_1_2_3_4_table.bin and SRK_1_2_3_4_fuse.bin files can be used in further +steps as explained in HAB guides available under doc/imx/habv4/guides/ +directory. + +References: +[1] CST: i.MX High Assurance Boot Reference Code Signing Tool. +[2] AN4581: "Secure Boot on i.MX 50, i.MX 53, i.MX 6 and i.MX 7 Series using + HABv4" - Rev 2. +[3] AN12056: "Encrypted Boot on HABv4 and CAAM Enabled Devices" - Rev. 1 diff --git a/roms/u-boot/doc/imx/habv4/script_examples/genIVT.pl b/roms/u-boot/doc/imx/habv4/script_examples/genIVT.pl new file mode 100644 index 000000000..84a4fcb16 --- /dev/null +++ b/roms/u-boot/doc/imx/habv4/script_examples/genIVT.pl @@ -0,0 +1,12 @@ +#! /usr/bin/perl -w +use strict; +open(my $out, '>:raw', 'ivt.bin') or die "Unable to open: $!"; +print $out pack("V", 0x412000D1); # Signature +print $out pack("V", 0x80800000); # Load Address (*load_address) +print $out pack("V", 0x0); # Reserved +print $out pack("V", 0x0); # DCD pointer +print $out pack("V", 0x0); # Boot Data +print $out pack("V", 0x80EEA000); # Self Pointer (*ivt) +print $out pack("V", 0x80EEA020); # CSF Pointer (*csf) +print $out pack("V", 0x0); # Reserved +close($out); diff --git a/roms/u-boot/doc/imx/index.rst b/roms/u-boot/doc/imx/index.rst new file mode 100644 index 000000000..b225b1d18 --- /dev/null +++ b/roms/u-boot/doc/imx/index.rst @@ -0,0 +1,9 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +NXP i.MX Machine-specific doc +============================= + +.. toctree:: + :maxdepth: 2 + + misc/index diff --git a/roms/u-boot/doc/imx/misc/index.rst b/roms/u-boot/doc/imx/misc/index.rst new file mode 100644 index 000000000..85fbdb658 --- /dev/null +++ b/roms/u-boot/doc/imx/misc/index.rst @@ -0,0 +1,9 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +Miscellaneous +============= + +.. toctree:: + :maxdepth: 2 + + psb diff --git a/roms/u-boot/doc/imx/misc/psb.rst b/roms/u-boot/doc/imx/misc/psb.rst new file mode 100644 index 000000000..71ac09fac --- /dev/null +++ b/roms/u-boot/doc/imx/misc/psb.rst @@ -0,0 +1,174 @@ +i.MX7D/i.MX8MM SRC_GPR10 PERSIST_SECONDARY_BOOT for bootloader A/B switching +============================================================================ + +Introduction +------------ +Since at least iMX53 until iMX8MM, it is possible to have two copies of +bootloader in SD/eMMC and switch between them. The switch is triggered +either by the BootROM in case the bootloader image is faulty OR can be +enforced by the user. + +Operation +--------- + #. Upon Power-On Reset (POR) + + - SRC_GPR10 bit PERSIST_SECONDARY_BOOT is set to 0 + - BootROM attempts to start bootloader A-copy + + - if A-copy valid + + - BootROM starts A-copy + - END + + - if A-copy NOT valid + + - BootROM sets SRC_GPR10 bit PERSIST_SECONDARY_BOOT to 1 + - BootROM triggers WARM reset, GOTO 1) + - END + + #. Upon COLD Reset + + - GOTO 1) + - END + + #. Upon WARM Reset + + - SRC_GPR10 bit PERSIST_SECONDARY_BOOT is retained + + - if SRC_GPR10 bit PERSIST_SECONDARY_BOOT is 0 + + - BootROM attempts to start bootloader A-copy + + - if A-copy valid + + - BootROM starts A-copy + - END + + - if A-copy NOT valid + + - BootROM sets SRC_GPR10 bit PERSIST_SECONDARY_BOOT to 1 + - BootROM triggers WARM reset. GOTO 1.3) + - END + + - if SRC_GPR10 bit PERSIST_SECONDARY_BOOT is 1 + + - BootROM attempts to start bootloader B-copy + + - if B-copy valid + + - BootROM starts B-copy + - END + + - if B-copy NOT valid + - System hangs + - END + +Setup +----- +The bootloader A-copy must be placed at predetermined offset in SD/eMMC. The +bootloader B-copy area offset is determined by an offset stored in Secondary +Image Table (SIT). The SIT must be placed at predetermined offset in SD/eMMC. + +The following table contains offset of SIT, bootloader A-copy and recommended +bootloader B-copy offset. The offsets are in 512 Byte sector units (that is +offset 0x1 means 512 Bytes from the start of SD/eMMC card data partition). +For details on the addition of two numbers in recommended B-copy offset, see +SIT format below. + ++----------+--------------------+-----------------------+-----------------------------+ +| SoC | SIT offset (fixed) | A-copy offset (fixed) | B-copy offset (recommended) | ++----------+--------------------+-----------------------+-----------------------------+ +| iMX7D | 0x1 | 0x2 | 0x800+0x2 | ++----------+--------------------+-----------------------+-----------------------------+ +| iMX8MM | 0x41 | 0x42 | 0x1000+0x42 | ++----------+--------------------+-----------------------+-----------------------------+ + +SIT format +~~~~~~~~~~ +SIT is a 20 byte long structure containing of 5 32-bit words. Those encode +bootloader B-copy area offset (called "firstSectorNumber"), magic value +(called "tag") that is always 0x00112233, and three unused words set to 0. +SIT is documented in [1]_ and [2]_. Example SIT are below:: + + $ hexdump -vC sit-mx7d.bin + 00000000 00 00 00 00 + 00000004 00 00 00 00 + 00000008 33 22 11 00 <--- This is the "tag" + 0000000c 00 08 00 00 <--- This is the "firstSectorNumber" + 00000010 00 00 00 00 + + $ hexdump -vC sit-mx8mm.bin + 00000000 00 00 00 00 + 00000004 00 00 00 00 + 00000008 33 22 11 00 <--- This is the "tag" + 0000000c 00 10 00 00 <--- This is the "firstSectorNumber" + 00000010 00 00 00 00 + +B-copy area offset ("firstSectorNumber") is offset, in units of 512 Byte +sectors, that is added to the start of boot media when switching between +A-copy and B-copy. For A-copy, this offset is 0x0. For B-copy, this offset +is determined by SIT (e.g. if firstSectorNumber is 0x1000 as it is above +in sit-mx8mm.bin, then the B-copy offset is 0x1000 sectors = 2 MiB). + +Bootloader A-copy (e.g. u-boot.imx or flash.bin) is placed at fixed offset +from A-copy area offset (e.g. 0x2 sectors from sector 0x0 for iMX7D, which +means u-boot.imx A-copy must be written to sector 0x2). + +The same applies to bootloader B-copy, which is placed at fixed offset from +B-copy area offset determined by SIT (e.g. 0x2 sectors from sector 0x800 [see +sit-mx7d.bin example above, this can be changed in SIT firstSectorNumber] for +iMX7D, which means u-boot.imx B-copy must be written to sector 0x802) + +**WARNING:** +B-copy area offset ("firstSectorNumber") is NOT equal to bootloader +(image, which is u-boot.imx or flash.bin) B-copy offset. + +To generate SIT, use for example the following bourne shell printf command:: + +$ printf '\x0\x0\x0\x0\x0\x0\x0\x0\x33\x22\x11\x00\x00\x08\x00\x00\x0\x0\x0\x0' > sit-mx7d.bin +$ printf '\x0\x0\x0\x0\x0\x0\x0\x0\x33\x22\x11\x00\x00\x10\x00\x00\x0\x0\x0\x0' > sit-mx8mm.bin + +Write bootloader A/B copy and SIT to SD/eMMC +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Examples of writing SIT and two copies of bootloader to SD or eMMC: + +- iMX8MM, SD card at /dev/sdX, Linux command line + :: + + $ dd if=sit-mx8mm.bin of=/dev/sdX bs=512 seek=65 + $ dd if=flash.bin of=/dev/sdX bs=512 seek=66 + $ dd if=flash.bin of=/dev/sdX bs=512 seek=4162 + +- iMX8MM, eMMC 1 data partition, U-Boot command line + :: + + => mmc partconf 1 0 0 0 + + => dhcp ${loadaddr} sit-mx8mm.bin + => mmc dev 1 + => mmc write ${loadaddr} 0x41 0x1 + + => dhcp ${loadaddr} flash.bin + => setexpr blkcnt ${filesize} + 0x1ff && setexpr blkcnt ${blkcnt} / 0x200 + => mmc dev 1 + => mmc write ${loadaddr} 0x42 ${blkcnt} + => mmc write ${loadaddr} 0x1042 ${blkcnt} + +WARM reset into B-copy using WDT +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +To perform a reboot into B-copy, the PERSIST_SECONDARY_BOOT must be set +in SRC_GPR0 register. Example on iMX8MM:: + + => mw 0x30390098 0x40000000 + +A WARM reset can be triggered using WDT as follows:: + + => mw.w 0x30280000 0x25 + +References +---------- + +.. [1] i.MX 7Dual Applications Processor Reference Manual, Rev. 1, 01/2018 ; section 6.6.5.3.5 Redundant boot support for expansion device +.. [2] i.MX 8M Mini Applications Processor Reference Manual, Rev. 3, 11/2020 ; section 6.1.5.4.5 Redundant boot support for expansion device diff --git a/roms/u-boot/doc/imx/misc/sdp.txt b/roms/u-boot/doc/imx/misc/sdp.txt new file mode 100644 index 000000000..49b281234 --- /dev/null +++ b/roms/u-boot/doc/imx/misc/sdp.txt @@ -0,0 +1,118 @@ +------------- +SDP in U-Boot +------------- + +SDP stands for serial download protocol. It is the protocol used in NXP's +i.MX SoCs ROM Serial Downloader and provides means to download a program +image to the chip over USB and UART serial connection. + +The implementation in U-Boot uses the USB Downloader Gadget (g_dnl) to +provide a SDP implementation over USB. This allows to download program +images to the target in SPL/U-Boot using the same protocol/tooling the +SoC's recovery mechanism is using. + +The SDP protocol over USB is a USB HID class protocol. USB HID class +protocols allow to access a USB device without OS specific drivers. The +U-Boot implementation has primarly been tested using the open source +imx_loader utility (https://github.com/boundarydevices/imx_usb_loader). + +imx_usb_loader is a very nice tool by Boundary Devices that allow to +install U-Boot without a JTAG debugger, using the USB boot mode as +described in the manual. It is a replacement for Freescale's +MFGTOOLS. + +The host side utilities are typically capable to interpret the i.MX +specific image header (see doc/imx/mkimage/imximage.txt). There are extensions +for imx_loader's imx_usb utility which allow to interpret the U-Boot +specific legacy image format (see mkimage(1)). Also the U-Boot side +support beside the i.MX specific header the U-Boot legacy header. + +1. Using imx_usb_loader for first install with SPL +-------------------------------------------------- + +This implementation can be started in U-Boot using the sdp command +(CONFIG_CMD_USB_SDP) or in SPL if Serial Downloader boot mode has been +detected (CONFIG_SPL_USB_SDP_SUPPORT). + +A typical use case is downloading full U-Boot after SPL has been +downloaded through the boot ROM's Serial Downloader. Using boot mode +detection the SPL will run the SDP implementation automatically in +this case: + + # imx_usb SPL + +Targets Serial Console: + + Trying to boot from USB SDP + SDP: initialize... + SDP: handle requests... + +At this point the SPL reenumerated as a new HID device and emulating +the boot ROM's SDP protocol. The USB VID/PID will depend on standard +U-Boot configurations CONFIG_G_DNL_(VENDOR|PRODUCT)_NUM. Make sure +imx_usb is aware of the USB VID/PID for your device by adding a +configuration entry in imx_usb.conf: + + 0x1b67:0x4fff, mx6_usb_sdp_spl.conf + +And the device specific configuration file mx6_usb_sdp_spl.conf: + + mx6_spl_sdp + hid,uboot_header,1024,0x910000,0x10000000,1G,0x00900000,0x40000 + +This allows to download the regular U-Boot with legacy image headers +(u-boot.img) using a second invocation of imx_usb: + + # imx_usb u-boot.img + +Furthermore, when U-Boot is running the sdp command can be used to +download and run scripts: + + # imx_usb script.scr + +imx_usb configuration files can be also used to download multiple +files and of arbitrary types, e.g. + + mx6_usb_sdp_uboot + hid,1024,0x10000000,1G,0x00907000,0x31000 + full.itb:load 0x12100000 + boot.scr:load 0x12000000,jump 0x12000000 + +There is also a batch mode which allows imx_usb to handle multiple +consecutive reenumerations by adding multiple VID/PID specifications +in imx_usb.conf: + + 0x15a2:0x0061, mx6_usb_rom.conf, 0x1b67:0x4fff, mx6_usb_sdp_spl.conf + +In this mode the file to download (imx_usb job) needs to be specified +in the configuration files. + +mx6_usb_rom.conf: + + mx6_qsb + hid,1024,0x910000,0x10000000,1G,0x00900000,0x40000 + SPL:jump header2 + +mx6_usb_sdp_spl.conf: + + mx6_spl_sdp + hid,uboot_header,1024,0x10000000,1G,0x00907000,0x31000 + u-boot.img:jump header2 + +With that SPL and U-Boot can be downloaded with a single invocation +of imx_usb without arguments: + + # imx_usb + +2. Using imx_usb_loader non-SPL images +--------------------------------------- + +Booting in USB mode, the i.MX6 announces itself to the Linux Host as: + +Bus 001 Device 111: ID 15a2:0061 Freescale Semiconductor, Inc. + +imx_usb_loader is able to download a single file (u-boot.imx) +to the board. For boards without SPL support, it is enough to +issue the command: + + sudo ../imx_usb_loader/imx_usb -v u-boot.imx diff --git a/roms/u-boot/doc/imx/mkimage/imx8image.txt b/roms/u-boot/doc/imx/mkimage/imx8image.txt new file mode 100644 index 000000000..76664a86f --- /dev/null +++ b/roms/u-boot/doc/imx/mkimage/imx8image.txt @@ -0,0 +1,45 @@ +Introduction: +============= + +This documentation entry describes the i.MX8 container format and how +to use. + +A Boot image consists of: + - Primary Boot Container Set + - Optional Secondary Boot Container Set + +The imx8image only support the Primary Boot Container Set. + +The Primary Boot Container Set contains two containers. The 1st container +only contain the SECO firmware image, the 2nd container can contain +multiple images and typically have: + - SCF FW image + - M4 FW image + - AP FW image + +For more details, refer i.MX8 Reference Mannual Chapter 5 +"System Boot and section", "5.9 (Boot image) of the processor's manual" + +Configuration file: +================== +BOOT_FROM [sd|emmc_fastboot|fspi|nand_4k|nand_8k|nand_16k] [sector_size] + - indicates the boot media +SOC_TYPE [IMX8QM|IMX8QX] + - indicates the soc +APPEND [ahab container image] + - indicates the ahah image that will be put in the 1st container + When creating container image will be loaded by SPL, this entry + should not this included +CONTAINER + - indicates to create the 2nd container +IMAGE [SCU|M40|M41|A35|A53|A72] [image file] [load address] + - indicates images will be put in the 2nd container + +Example: +======= +BOOT_FROM SD 0x400 +SOC_TYPE IMX8QM +APPEND mx8qm-ahab-container.img +CONTAINER +IMAGE SCU mx8qm-mek-scfw-tcm.bin +IMAGE A35 spl/u-boot-spl.bin 0x00100000 diff --git a/roms/u-boot/doc/imx/mkimage/imximage.txt b/roms/u-boot/doc/imx/mkimage/imximage.txt new file mode 100644 index 000000000..f2cf23c5d --- /dev/null +++ b/roms/u-boot/doc/imx/mkimage/imximage.txt @@ -0,0 +1,239 @@ +--------------------------------------------- +Imximage Boot Image generation using mkimage +--------------------------------------------- + +This document describes how to set up a U-Boot image that can be booted +by Freescale MX25, MX35, MX51, MX53 and MX6 processors via internal boot +mode. + +These processors can boot directly from NAND, SPI flash and SD card flash +using its internal boot ROM support. MX6 processors additionally support +boot from NOR flash and SATA disks. All processors can boot from an internal +UART, if booting from device media fails. +Booting from NOR flash does not require to use this image type. + +For more details refer Chapter 2 - System Boot and section 2.14 +(flash header description) of the processor's manual. + +Command syntax: +-------------- +./tools/mkimage -l <mx u-boot_file> + to list the imx image file details + +./tools/mkimage -T imximage \ + -n <board specific configuration file> \ + -e <execution address> -d <u-boot binary> <output image file> + +For example, for the mx51evk board: +./tools/mkimage -n ./board/freescale/mx51evk/imximage.cfg \ + -T imximage -e 0x97800000 \ + -d u-boot.bin u-boot.imx + +You can generate directly the image when you compile u-boot with: + +$ make u-boot.imx + +The output image can be flashed on the board SPI flash or on a SD card. +In both cases, you have to copy the image at the offset required for the +chosen media devices (0x400 for both SPI flash or SD card). + +Please check Freescale documentation for further details. + +Board specific configuration file specifications: +------------------------------------------------- +1. This file must present in the $(BOARDDIR) and the name should be + imximage.cfg (since this is used in Makefile). +2. This file can have empty lines and lines starting with "#" as first + character to put comments. +3. This file can have configuration command lines as mentioned below, + any other information in this file is treated as invalid. + +Configuration command line syntax: +--------------------------------- +1. Each command line is must have two strings, first one command or address + and second one data string +2. Following are the valid command strings and associated data strings:- + Command string data string + -------------- ----------- + IMXIMAGE_VERSION 1/2 + 1 is for mx25/mx35/mx51 compatible, + 2 is for mx53/mx6 compatible, + others is invalid and error is generated. + This command need appear the fist before + other valid commands in configuration file. + + BOOT_OFFSET value + + This command is parallel to BOOT_FROM and + is preferred over BOOT_FROM. + + value: Offset of the image header, this + value shall be set to one of the + values found in the file: + arch/arm/include/asm/\ + mach-imx/imximage.cfg + Example: + BOOT_OFFSET FLASH_OFFSET_STANDARD + + BOOT_FROM nand/spi/sd/onenand/nor/sata + + This command is parallel to BOOT_OFFSET and + is to be deprecated in favor of BOOT_OFFSET. + + Example: + BOOT_FROM spi + + CSF value + + Total size of CSF (Command Sequence File) + used for Secure Boot/ High Assurance Boot + (HAB). + + Using this command will populate the IVT + (Initial Vector Table) CSF pointer and adjust + the length fields only. The CSF itself needs + to be generated with Freescale tools and + 'manually' appended to the u-boot.imx file. + + The CSF is then simply concatenated + to the u-boot image, making a signed bootloader, + that the processor can verify + if the fuses for the keys are burned. + + Further infos how to configure the SOC to verify + the bootloader can be found in the "High + Assurance Boot Version Application Programming + Interface Reference Manual" as part of the + Freescale Code Signing Tool, available on the + manufacturer's website. + + Example: + CSF 0x2000 + + DATA type address value + + type: word=4, halfword=2, byte=1 + address: physycal register address + value: value to be set in register + All values are in in hexadecimal. + Example (write to IOMUXC): + DATA 4 0x73FA88a0 0x200 + +The processor support up to 60 register programming commands for IMXIMAGE_VERSION 1 +and 220 register programming commands for IMXIMAGE_VERSION 2. +An error is generated if more commands are found in the configuration file. + +3. All commands are optional to program. + +Setup a SD Card for booting +-------------------------------- + +The following example prepare a SD card with u-boot and a FAT partition +to be used to stored the kernel to be booted. +I will set the SD in the most compatible mode, setting it with +255 heads and 63 sectors, as suggested from several documentation and +howto on line (I took as reference the preparation of a SD Card for the +Beagleboard, running u-boot as bootloader). + +You should start clearing the partitions table on the SD card. Because +the u-boot image must be stored at the offset 0x400, it must be assured +that there is no partition at that address. A new SD card is already +formatted with FAT filesystem and the partition starts from the first +cylinder, so we need to change it. + +You can do all steps with fdisk. If the device for the SD card is +/dev/mmcblk0, the following commands make the job: + +1. Start the fdisk utility (as superuser) + fdisk /dev/mmcblk0 + +2. Clear the actual partition + +Command (m for help): o + +3. Print card info: + +Command (m for help): p +Disk /dev/mmcblk0: 1981 MB, 1981284352 bytes + +In my case, I have a 2 GB card. I need the size to set later the correct value +for the cylinders. + +4. Go to expert mode: + +Command (m for help): x + +5. Set card geometry + +Expert command (m for help): h +Number of heads (1-256, default 4): 255 + +Expert command (m for help): s +Number of sectors (1-63, default 16): 63 +Warning: setting sector offset for DOS compatiblity + +We have set 255 heads, 63 sector. We have to set the cylinder. +The value to be set can be calculated with: + + cylinder = <total size> / <heads> / <sectors> / <blocksize> + +in this example, + 1981284352 / 255 / 63 / 512 = 239.x = 239 + + +Expert command (m for help): c +Number of cylinders (1-1048576, default 60032): 239 + +6. Leave the expert mode +Expert command (m for help): r + +7. Set up a partition + +Now set a partition table to store the kernel or whatever you want. Of course, +you can set additional partitions to store rootfs, data, etc. +In my example I want to set a single partition. I must take care +to not overwrite the space where I will put u-boot. + +Command (m for help): n +Command action + e extended + p primary partition (1-4) +p +Partition number (1-4): 1 +First cylinder (1-239, default 1): 3 +Last cylinder, +cylinders or +size{K,M,G} (3-239, default 239): +100M + +Command (m for help): p + +Disk /dev/mmcblk0: 1967 MB, 1967128576 bytes +255 heads, 63 sectors/track, 239 cylinders +Units = cylinders of 16065 * 512 = 8225280 bytes +Disk identifier: 0xb712a870 + + Device Boot Start End Blocks Id System +/dev/mmcblk0p1 3 16 112455 83 Linux + +I have set 100MB, leaving the first 2 sectors free. I will copy u-boot +there. + +8. Write the partition table and exit. + +Command (m for help): w +The partition table has been altered! + +Calling ioctl() to re-read partition table. + +9. Copy u-boot.imx on the SD card + +I use dd: + +dd if=u-boot.imx of=/dev/mmcblk0 bs=512 seek=2 + +This command copies the u-boot image at the address 0x400, as required +by the processor. + +Now remove your card from the PC and go to the target. If evrything went right, +the u-boot prompt should come after power on. + +------------------------------------------------ +Author: Stefano babic <sbabic@denx.de> diff --git a/roms/u-boot/doc/imx/mkimage/mxsimage.txt b/roms/u-boot/doc/imx/mkimage/mxsimage.txt new file mode 100644 index 000000000..9159f93a9 --- /dev/null +++ b/roms/u-boot/doc/imx/mkimage/mxsimage.txt @@ -0,0 +1,170 @@ +Freescale i.MX233/i.MX28 SB image generator via mkimage +======================================================= + +This tool allows user to produce SB BootStream encrypted with a zero key. +Such a BootStream is then bootable on i.MX23/i.MX28. + +Usage -- producing image: +========================= +The mxsimage tool is targeted to be a simple replacement for the elftosb2 . +To generate an image, write an image configuration file and run: + + mkimage -A arm -O u-boot -T mxsimage -n <path to configuration file> \ + <output bootstream file> + +The output bootstream file is usually using the .sb file extension. Note +that the example configuration files for producing bootable BootStream with +the U-Boot bootloader can be found under arch/arm/boot/cpu/arm926ejs/mxs/ +directory. See the following files: + + mxsimage.mx23.cfg -- This is an example configuration for i.MX23 + mxsimage.mx28.cfg -- This is an example configuration for i.MX28 + +Each configuration file uses very simple instruction semantics and a few +additional rules have to be followed so that a useful image can be produced. +These semantics and rules will be outlined now. + +- Each line of the configuration file contains exactly one instruction. +- Every numeric value must be encoded in hexadecimal and in format 0xabcdef12 . +- The configuration file is a concatenation of blocks called "sections" and + optionally "DCD blocks" (see below), and optional flags lines. + - Each "section" is started by the "SECTION" instruction. + - The "SECTION" instruction has the following semantics: + + SECTION u32_section_number [BOOTABLE] + - u32_section_number :: User-selected ID of the section + - BOOTABLE :: Sets the section as bootable + + - A bootable section is one from which the BootROM starts executing + subsequent instructions or code. Exactly one section must be selected + as bootable, usually the one containing the instructions and data to + load the bootloader. + + - A "SECTION" must be immediatelly followed by a "TAG" instruction. + - The "TAG" instruction has the following semantics: + + TAG [LAST] + - LAST :: Flag denoting the last section in the file + + - After a "TAG" instruction, any of the following instructions may follow + in any order and any quantity: + + NOOP + - This instruction does nothing + + LOAD u32_address string_filename + - Instructs the BootROM to load file pointed by "string_filename" onto + address "u32_address". + + LOAD IVT u32_address u32_IVT_entry_point + - Crafts and loads IVT onto address "u32_address" with the entry point + of u32_IVT_entry_point. + - i.MX28-specific instruction! + + LOAD DCD u32_address u32_DCD_block_ID + - Loads the DCD block with ID "u32_DCD_block_ID" onto address + "u32_address" and executes the contents of this DCD block + - i.MX28-specific instruction! + + FILL u32_address u32_pattern u32_length + - Starts to write memory from addres "u32_address" with a pattern + specified by "u32_pattern". Writes exactly "u32_length" bytes of the + pattern. + + JUMP [HAB] u32_address [u32_r0_arg] + - Jumps onto memory address specified by "u32_address" by setting this + address in PT. The BootROM will pass the "u32_r0_arg" value in ARM + register "r0" to the executed code if this option is specified. + Otherwise, ARM register "r0" will default to value 0x00000000. The + optional "HAB" flag is i.MX28-specific flag turning on the HAB boot. + + CALL [HAB] u32_address [u32_r0_arg] + - See JUMP instruction above, as the operation is exactly the same with + one difference. The CALL instruction does allow returning into the + BootROM from the executed code. U-Boot makes use of this in it's SPL + code. + + MODE string_mode + - Restart the CPU and start booting from device specified by the + "string_mode" argument. The "string_mode" differs for each CPU + and can be: + i.MX23, string_mode = USB/I2C/SPI1_FLASH/SPI2_FLASH/NAND_BCH + JTAG/SPI3_EEPROM/SD_SSP0/SD_SSP1 + i.MX28, string_mode = USB/I2C/SPI2_FLASH/SPI3_FLASH/NAND_BCH + JTAG/SPI2_EEPROM/SD_SSP0/SD_SSP1 + + - An optional "DCD" blocks can be added at the begining of the configuration + file. Note that the DCD is only supported on i.MX28. + - The DCD blocks must be inserted before the first "section" in the + configuration file. + - The DCD block has the following semantics: + + DCD u32_DCD_block_ID + - u32_DCD_block_ID :: The ID number of the DCD block, must match + the ID number used by "LOAD DCD" instruction. + + - The DCD block must be followed by one of the following instructions. All + of the instructions operate either on 1, 2 or 4 bytes. This is selected by + the 'n' suffix of the instruction: + + WRITE.n u32_address u32_value + - Write the "u32_value" to the "u32_address" address. + + ORR.n u32_address u32_value + - Read the "u32_address", perform a bitwise-OR with the "u32_value" and + write the result back to "u32_address". + + ANDC.n u32_address u32_value + - Read the "u32_address", perform a bitwise-AND with the complement of + "u32_value" and write the result back to "u32_address". + + EQZ.n u32_address u32_count + - Read the "u32_address" at most "u32_count" times and test if the value + read is zero. If it is, break the loop earlier. + + NEZ.n u32_address u32_count + - Read the "u32_address" at most "u32_count" times and test if the value + read is non-zero. If it is, break the loop earlier. + + EQ.n u32_address u32_mask + - Read the "u32_address" in a loop and test if the result masked with + "u32_mask" equals the "u32_mask". If the values are equal, break the + reading loop. + + NEQ.n u32_address u32_mask + - Read the "u32_address" in a loop and test if the result masked with + "u32_mask" does not equal the "u32_mask". If the values are not equal, + break the reading loop. + + NOOP + - This instruction does nothing. + + - An optional flags lines can be one of the following: + + DISPLAYPROGRESS + - Enable boot progress output from the BootROM. + +- If the boot progress output from the BootROM is enabled, the BootROM will + produce a letter on the Debug UART for each instruction it started processing. + Here is a mapping between the above instructions and the BootROM output: + + H -- SB Image header loaded + T -- TAG instruction + N -- NOOP instruction + L -- LOAD instruction + F -- FILL instruction + J -- JUMP instruction + C -- CALL instruction + M -- MODE instruction + +Usage -- verifying image: +========================= + +The mxsimage can also verify and dump contents of an image. Use the following +syntax to verify and dump contents of an image: + + mkimage -l <input bootstream file> + +This will output all the information from the SB image header and all the +instructions contained in the SB image. It will also check if the various +checksums in the SB image are correct. diff --git a/roms/u-boot/doc/index.rst b/roms/u-boot/doc/index.rst new file mode 100644 index 000000000..8066fcbfc --- /dev/null +++ b/roms/u-boot/doc/index.rst @@ -0,0 +1,112 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +.. _u-boot_doc: + +The U-Boot Documentation +======================== + +This is the top level of the U-Boot's documentation tree. U-Boot +documentation, like the U-Boot itself, is very much a work in progress; +that is especially true as we work to integrate our many scattered +documents into a coherent whole. Please note that improvements to the +documentation are welcome; join the U-Boot list at http://lists.denx.de +if you want to help out. + +.. toctree:: + :maxdepth: 2 + +User-oriented documentation +--------------------------- + +The following manuals are written for *users* of the U-Boot - those who are +trying to get it to work optimally on a given system. + +.. toctree:: + :maxdepth: 2 + + build/index + usage/index + +Developer-oriented documentation +-------------------------------- + +The following manuals are written for *developers* of the U-Boot - those who +want to contribute to U-Boot. + +.. toctree:: + :maxdepth: 2 + + develop/index + + +U-Boot API documentation +------------------------ + +These books get into the details of how specific U-Boot subsystems work +from the point of view of a U-Boot developer. Much of the information here +is taken directly from the U-Boot source, with supplemental material added +as needed (or at least as we managed to add it - probably *not* all that is +needed). + +.. toctree:: + :maxdepth: 2 + + api/index + +Architecture-specific doc +------------------------- + +These books provide programming details about architecture-specific +implementation. + +.. toctree:: + :maxdepth: 2 + + arch/index + +Machine-specific doc +-------------------- + +These books provide programming details about machine-specific +implementation. + +.. toctree:: + :maxdepth: 2 + + imx/index + +Board-specific doc +------------------ + +These books provide details about board-specific information. They are +organized in a vendor subdirectory. + +.. toctree:: + :maxdepth: 2 + + board/index + +Android-specific doc +-------------------- + +These books provide information about booting the Android OS from U-Boot, +manipulating Android images from U-Boot shell and discusses other +Android-specific features available in U-Boot. + +.. toctree:: + :maxdepth: 2 + + android/index + +Chromium OS-specific doc +------------------------ + +.. toctree:: + :maxdepth: 2 + + chromium/index + +Indices and tables +================== + +* :ref:`genindex` diff --git a/roms/u-boot/doc/kwboot.1 b/roms/u-boot/doc/kwboot.1 new file mode 100644 index 000000000..1e9ca268f --- /dev/null +++ b/roms/u-boot/doc/kwboot.1 @@ -0,0 +1,84 @@ +.TH KWBOOT 1 "2012-05-19" + +.SH NAME +kwboot \- Boot Marvell Kirkwood SoCs over a serial link. +.SH SYNOPSIS +.B kwboot +.RB [ "-b \fIimage\fP" ] +.RB [ "-p" ] +.RB [ "-t" ] +.RB [ "-B \fIbaudrate\fP" ] +.RB \fITTY\fP +.SH "DESCRIPTION" + +The \fBmkimage\fP program boots boards based on Marvell's Kirkwood +platform over their integrated UART. Boot image files will typically +contain a second stage boot loader, such as U-Boot. The image file +must conform to Marvell's BootROM firmware image format +(\fIkwbimage\fP), created using a tool such as \fBmkimage\fP. + +Following power-up or a system reset, system BootROM code polls the +UART for a brief period of time, sensing a handshake message which +initiates an image upload. This program sends this boot message until +it receives a positive acknowledgement. The image is transferred using +Xmodem. + +Additionally, this program implements a minimal terminal mode, which +can be used either standalone, or entered immediately following boot +image transfer completion. This is often useful to catch early boot +messages, or to manually interrupt a default boot procedure performed +by the second-stage loader. + +.SH "OPTIONS" + +.TP +.BI "\-b \fIimage\fP" +Handshake; then upload file \fIimage\fP over \fITTY\fP. + +Note that for the encapsulated boot code to be executed, \fIimage\fP +must be of type "UART boot" (0x69). Boot images of different types, +such as backup images of vendor firmware downloaded from flash memory +(type 0x8B), will not work (or not as expected). See \fB-p\fP for a +workaround. + +This mode writes handshake status and upload progress indication to +stdout. + +.TP +.BI "\-p" +In combination with \fB-b\fP, patches the header in \fIimage\fP prior +to upload, to "UART boot" type. + +This option attempts on-the-fly conversion of some none-UART image +types, such as images which were originally formatted to be stored in +flash memory. + +Conversion is performed in memory. The contents of \fIimage\fP will +not be altered. + +.TP +.BI "\-t" +Run a terminal program, connecting standard input and output to +.RB \fITTY\fP. + +If used in combination with \fB-b\fP, terminal mode is entered +immediately following a successful image upload. + +If standard I/O streams connect to a console, this mode will terminate +after receiving 'ctrl-\\' followed by 'c' from console input. + +.TP +.BI "\-B \fIbaudrate\fP" +Adjust the baud rate on \fITTY\fP. Default rate is 115200. + +.SH "SEE ALSO" +.PP +\fBmkimage\fP(1) + +.SH "AUTHORS" + +Daniel Stodden <daniel.stodden@gmail.com> +.br +Luka Perkov <luka@openwrt.org> +.br +David Purdy <david.c.purdy@gmail.com> diff --git a/roms/u-boot/doc/media/Makefile b/roms/u-boot/doc/media/Makefile new file mode 100644 index 000000000..b9b43a34c --- /dev/null +++ b/roms/u-boot/doc/media/Makefile @@ -0,0 +1,38 @@ +# Rules to convert a .h file to inline RST documentation + +SRC_DIR=$(srctree)/doc/media +PARSER = $(srctree)/doc/sphinx/parse-headers.pl +API = $(srctree)/include + +FILES = linker_lists.h.rst + +TARGETS := $(addprefix $(BUILDDIR)/, $(FILES)) + +gen_rst = \ + echo ${PARSER} $< $@ $(SRC_DIR)/$(notdir $@).exceptions; \ + ${PARSER} $< $@ $(SRC_DIR)/$(notdir $@).exceptions + +quiet_gen_rst = echo ' PARSE $(patsubst $(srctree)/%,%,$<)'; \ + ${PARSER} $< $@ $(SRC_DIR)/$(notdir $@).exceptions + +silent_gen_rst = ${gen_rst} + +$(BUILDDIR)/linker_lists.h.rst: ${API}/linker_lists.h ${PARSER} $(SRC_DIR)/linker_lists.h.rst.exceptions + @$($(quiet)gen_rst) + +# Media build rules + +.PHONY: all html epub xml latex + +all: $(IMGDOT) $(BUILDDIR) ${TARGETS} +html: all +epub: all +xml: all +latex: $(IMGPDF) all +linkcheck: + +clean: + -rm -f $(DOTTGT) $(IMGTGT) ${TARGETS} 2>/dev/null + +$(BUILDDIR): + $(Q)mkdir -p $@ diff --git a/roms/u-boot/doc/media/linker_lists.h.rst.exceptions b/roms/u-boot/doc/media/linker_lists.h.rst.exceptions new file mode 100644 index 000000000..e69de29bb --- /dev/null +++ b/roms/u-boot/doc/media/linker_lists.h.rst.exceptions diff --git a/roms/u-boot/doc/mkimage.1 b/roms/u-boot/doc/mkimage.1 new file mode 100644 index 000000000..fea528878 --- /dev/null +++ b/roms/u-boot/doc/mkimage.1 @@ -0,0 +1,242 @@ +.TH MKIMAGE 1 "2010-05-16" + +.SH NAME +mkimage \- Generate image for U-Boot +.SH SYNOPSIS +.B mkimage +.RB "\-l [" "uimage file name" "]" + +.B mkimage +.RB [\fIoptions\fP] " \-f [" "image tree source file" "]" " [" "uimage file name" "]" + +.B mkimage +.RB [\fIoptions\fP] " \-F [" "uimage file name" "]" + +.B mkimage +.RB [\fIoptions\fP] " (legacy mode)" + +.SH "DESCRIPTION" +The +.B mkimage +command is used to create images for use with the U-Boot boot loader. +These images can contain the linux kernel, device tree blob, root file +system image, firmware images etc., either separate or combined. + +.B mkimage +supports two different formats: + +The old +.I legacy image +format concatenates the individual parts (for example, kernel image, +device tree blob and ramdisk image) and adds a 64 bytes header +containing information about target architecture, operating system, +image type, compression method, entry points, time stamp, checksums, +etc. + +The new +.I FIT (Flattened Image Tree) format +allows for more flexibility in handling images of various types and also +enhances integrity protection of images with stronger checksums. It also +supports verified boot. + +.SH "OPTIONS" + +.B List image information: + +.TP +.BI "\-l [" "uimage file name" "]" +mkimage lists the information contained in the header of an existing U-Boot image. + +.P +.B Create old legacy image: + +.TP +.BI "\-A [" "architecture" "]" +Set architecture. Pass \-h as the architecture to see the list of supported architectures. + +.TP +.BI "\-O [" "os" "]" +Set operating system. bootm command of u-boot changes boot method by os type. +Pass \-h as the OS to see the list of supported OS. + +.TP +.BI "\-T [" "image type" "]" +Set image type. +Pass \-h as the image to see the list of supported image type. + +.TP +.BI "\-C [" "compression type" "]" +Set compression type. +Pass \-h as the compression to see the list of supported compression type. + +.TP +.BI "\-a [" "load address" "]" +Set load address with a hex number. + +.TP +.BI "\-e [" "entry point" "]" +Set entry point with a hex number. + +.TP +.BI "\-l" +List the contents of an image. + +.TP +.BI "\-n [" "image name" "]" +Set image name to 'image name'. + +.TP +.BI "\-d [" "image data file" "]" +Use image data from 'image data file'. + +.TP +.BI "\-x" +Set XIP (execute in place) flag. + +.P +.B Create FIT image: + +.TP +.BI "\-b [" "device tree file" "] +Appends the device tree binary file (.dtb) to the FIT. + +.TP +.BI "\-c [" "comment" "]" +Specifies a comment to be added when signing. This is typically a useful +message which describes how the image was signed or some other useful +information. + +.TP +.BI "\-D [" "dtc options" "]" +Provide special options to the device tree compiler that is used to +create the image. + +.TP +.BI "\-E +After processing, move the image data outside the FIT and store a data offset +in the FIT. Images will be placed one after the other immediately after the +FIT, with each one aligned to a 4-byte boundary. The existing 'data' property +in each image will be replaced with 'data-offset' and 'data-size' properties. +A 'data-offset' of 0 indicates that it starts in the first (4-byte aligned) +byte after the FIT. + +.TP +.BI "\-f [" "image tree source file" " | " "auto" "]" +Image tree source file that describes the structure and contents of the +FIT image. + +This can be automatically generated for some simple cases. +Use "-f auto" for this. In that case the arguments -d, -A, -O, -T, -C, -a +and -e are used to specify the image to include in the FIT and its attributes. +No .its file is required. + +.TP +.BI "\-F" +Indicates that an existing FIT image should be modified. No dtc +compilation is performed and the \-f flag should not be given. +This can be used to sign images with additional keys after initial image +creation. + +.TP +.BI "\-i [" "ramdisk_file" "]" +Appends the ramdisk file to the FIT. + +.TP +.BI "\-k [" "key_directory" "]" +Specifies the directory containing keys to use for signing. This directory +should contain a private key file <name>.key for use with signing and a +certificate <name>.crt (containing the public key) for use with verification. + +.TP +.BI "\-K [" "key_destination" "]" +Specifies a compiled device tree binary file (typically .dtb) to write +public key information into. When a private key is used to sign an image, +the corresponding public key is written into this file for for run-time +verification. Typically the file here is the device tree binary used by +CONFIG_OF_CONTROL in U-Boot. + +.TP +.BI "\-p [" "external position" "]" +Place external data at a static external position. See \-E. Instead of writing +a 'data-offset' property defining the offset from the end of the FIT, \-p will +use 'data-position' as the absolute position from the base of the FIT. + +.TP +.BI "\-r +Specifies that keys used to sign the FIT are required. This means that they +must be verified for the image to boot. Without this option, the verification +will be optional (useful for testing but not for release). + +.TP +.BI "\-t +Update the timestamp in the FIT. + +Normally the FIT timestamp is created the first time mkimage is run on a FIT, +when converting the source .its to the binary .fit file. This corresponds to +using the -f flag. But if the original input to mkimage is a binary file +(already compiled) then the timestamp is assumed to have been set previously. + +.SH EXAMPLES + +List image information: +.nf +.B mkimage -l uImage +.fi +.P +Create legacy image with compressed PowerPC Linux kernel: +.nf +.B mkimage -A powerpc -O linux -T kernel -C gzip \\\\ +.br +.B -a 0 -e 0 -n Linux -d vmlinux.gz uImage +.fi +.P +Create FIT image with compressed PowerPC Linux kernel: +.nf +.B mkimage -f kernel.its kernel.itb +.fi +.P +Create FIT image with compressed kernel and sign it with keys in the +/public/signing-keys directory. Add corresponding public keys into u-boot.dtb, +skipping those for which keys cannot be found. Also add a comment. +.nf +.B mkimage -f kernel.its -k /public/signing-keys -K u-boot.dtb \\\\ +.br +.B -c """Kernel 3.8 image for production devices""" kernel.itb +.fi + +.P +Update an existing FIT image, signing it with additional keys. +Add corresponding public keys into u-boot.dtb. This will resign all images +with keys that are available in the new directory. Images that request signing +with unavailable keys are skipped. +.nf +.B mkimage -F -k /secret/signing-keys -K u-boot.dtb \\\\ +.br +.B -c """Kernel 3.8 image for production devices""" kernel.itb +.fi + +.P +Create a FIT image containing a kernel, using automatic mode. No .its file +is required. +.nf +.B mkimage -f auto -A arm -O linux -T kernel -C none -a 43e00000 -e 0 \\\\ +.br +.B -c """Kernel 4.4 image for production devices""" -d vmlinuz kernel.itb +.fi +.P +Create a FIT image containing a kernel and some device tree files, using +automatic mode. No .its file is required. +.nf +.B mkimage -f auto -A arm -O linux -T kernel -C none -a 43e00000 -e 0 \\\\ +.br +.B -c """Kernel 4.4 image for production devices""" -d vmlinuz \\\\ +.B -b /path/to/rk3288-firefly.dtb -b /path/to/rk3288-jerry.dtb kernel.itb +.fi + +.SH HOMEPAGE +http://www.denx.de/wiki/U-Boot/WebHome +.PP +.SH AUTHOR +This manual page was written by Nobuhiro Iwamatsu <iwamatsu@nigauri.org> +and Wolfgang Denk <wd@denx.de>. It was updated for image signing by +Simon Glass <sjg@chromium.org>. diff --git a/roms/u-boot/doc/mvebu/armada-8k-memory.txt b/roms/u-boot/doc/mvebu/armada-8k-memory.txt new file mode 100644 index 000000000..064518eb5 --- /dev/null +++ b/roms/u-boot/doc/mvebu/armada-8k-memory.txt @@ -0,0 +1,56 @@ + Memory Layout on Armada-8k SoC's + ================================ + +The below desribes the physical memory layout for Marvell's Armada-8k SoC's. + +This assumes that the SoC includes Dual CP configuration, in case the flavor is using +a single CP configuration, then all secondary-CP mappings are invalid. + +All "Reserved" areas below, are kept for future usage. + +Start End Use +-------------------------------------------------------------------------- +0x00000000 0xEFFFFFFF DRAM + +0xF0000000 0xF0FFFFFF AP Internal registers space + +0xF1000000 0xF1FFFFFF Reserved. + +0xF2000000 0xF3FFFFFF CP-0 Internal (configuration) registers + space. + +0xF4000000 0xF5FFFFFF CP-1 Internal (configuration) registers + space. + +0xF6000000 0xF6FFFFFF CP-0 / PCIe#0 Memory space. + +0xF7000000 0xF7FFFFFF CP-0 / PCIe#1 Memory space. + +0xF8000000 0xF8FFFFFF CP-0 / PCIe#2 Memory space. + +0xF9000000 0xF900FFFF CP-0 / PCIe#0 IO space. + +0xF9010000 0xF901FFFF CP-0 / PCIe#1 IO space. + +0xF9020000 0xF902FFFF CP-0 / PCIe#2 IO space. + +0xF9030000 0xF9FFFFFF Reserved. + +0xFA000000 0xFAFFFFFF CP-1 / PCIe#0 Memory space. + +0xFB000000 0xFBFFFFFF CP-1 / PCIe#1 Memory space. + +0xFC000000 0xFCFFFFFF CP-1 / PCIe#2 Memory space. + +0xFD000000 0xFD00FFFF CP-1 / PCIe#0 IO space. + +0xFD010000 0xFD01FFFF CP-1 / PCIe#1 IO space. + +0xFD020000 0xFD02FFFF CP-1 / PCIe#2 IO space. + +0xFD030000 0xFFEFFFFF Reserved. + +0xFFF00000 0xFFFFFFFF Bootrom + +0x100000000 <DRAM Size>-1 DRAM + diff --git a/roms/u-boot/doc/mvebu/cmd/bubt.txt b/roms/u-boot/doc/mvebu/cmd/bubt.txt new file mode 100644 index 000000000..a539c15bc --- /dev/null +++ b/roms/u-boot/doc/mvebu/cmd/bubt.txt @@ -0,0 +1,55 @@ +BUBT (Burn ATF) command +-------------------------- +Bubt command is used to burn a new ATF image to flash device. + +The bubt command gets the following parameters: ATF file name, destination device and source device. +bubt [file-name] [destination [source]] + - file-name Image file name to burn. default = flash-image.bin + - destination Flash to burn to [spi, nand, mmc]. default = active flash + - source Source to load image from [tftp, usb]. default = tftp + +Examples: + bubt - Burn flash-image.bin from tftp to active flash + bubt latest-spi.bin nand - Burn latest-spi.bin from tftp to NAND flash + +Notes: +- For the TFTP interface set serverip and ipaddr. +- To burn image to SD/eMMC device, the target is defined + by parameters CONFIG_SYS_MMC_ENV_DEV and CONFIG_SYS_MMC_ENV_PART. + +Bubt command details (burn image step by-step) +---------------------------------------------- +This section describes bubt command flow: + +1. Fetch the requested ATF image from an available interface (USB/SD/SATA/XDB, etc.) + into the DRAM, and place it at <load_address> + Example: when using the FAT file system on USB flash device: + # usb reset + # fatls usb 0 (see files in device) + # fatload usb 0 <load_address> <file_name> + +2. Erase the target device: + - NAND: # nand erase 0 100000 + - SPI: # sf probe 0 + # sf erase 0 100000 + - SD/eMMC: # mmc dev <dev_id> <boot_partition> + +Notes: +- The eMMC has 2 boot partitions (BOOT0 and BOOT1) and a user data partition (DATA). + The boot partitions are numbered as partition 1 and 2 in MMC driver. + Number 0 is used for user data partition and should not be utilized for storing + boot images and U-Boot environment in RAW mode since it will break file system + structures usually located here. + The default boot partition is BOOT0. It is selected by the following parameter: + CONFIG_SYS_MMC_ENV_PART=1 + Valid values for this parameter are 1 for BOOT0 and 2 for BOOT1. + Please never use partition number 0 here! +- The partition number is ignored if the target device is SD card. +- The boot image offset starts at block 0 for eMMC and block 1 for SD devices. + The block 0 on SD devices is left for MBR storage. + +3. Write the ATF image: + - NAND: # nand write <load_address> 0 <ATF Size> + - SPI: # sf write <load_address> 0 <ATF Size> + - SD/eMMC: # mmc write <load_address> [0|1] <ATF Size>/<block_size> + diff --git a/roms/u-boot/doc/sphinx-static/theme_overrides.css b/roms/u-boot/doc/sphinx-static/theme_overrides.css new file mode 100644 index 000000000..522b6d4c4 --- /dev/null +++ b/roms/u-boot/doc/sphinx-static/theme_overrides.css @@ -0,0 +1,89 @@ +/* -*- coding: utf-8; mode: css -*- + * + * Sphinx HTML theme customization: read the doc + * + */ + +/* Interim: Code-blocks with line nos - lines and line numbers don't line up. + * see: https://github.com/rtfd/sphinx_rtd_theme/issues/419 + */ + +div[class^="highlight"] pre { + line-height: normal; +} +.rst-content .highlight > pre { + line-height: normal; +} + +@media screen { + + /* content column + * + * RTD theme's default is 800px as max width for the content, but we have + * tables with tons of columns, which need the full width of the view-port. + */ + + .wy-nav-content{max-width: none; } + + /* table: + * + * - Sequences of whitespace should collapse into a single whitespace. + * - make the overflow auto (scrollbar if needed) + * - align caption "left" ("center" is unsuitable on vast tables) + */ + + .wy-table-responsive table td { white-space: normal; } + .wy-table-responsive { overflow: auto; } + .rst-content table.docutils caption { text-align: left; font-size: 100%; } + + /* captions: + * + * - captions should have 100% (not 85%) font size + * - hide the permalink symbol as long as link is not hovered + */ + + .toc-title { + font-size: 150%; + font-weight: bold; + } + + caption, .wy-table caption, .rst-content table.field-list caption { + font-size: 100%; + } + caption a.headerlink { opacity: 0; } + caption a.headerlink:hover { opacity: 1; } + + /* Menu selection and keystrokes */ + + span.menuselection { + color: blue; + font-family: "Courier New", Courier, monospace + } + + code.kbd, code.kbd span { + color: white; + background-color: darkblue; + font-weight: bold; + font-family: "Courier New", Courier, monospace + } + + /* fix bottom margin of lists items */ + + .rst-content .section ul li:last-child, .rst-content .section ul li p:last-child { + margin-bottom: 12px; + } + + /* inline literal: drop the borderbox, padding and red color */ + + code, .rst-content tt, .rst-content code { + color: inherit; + border: none; + padding: unset; + background: inherit; + font-size: 85%; + } + + .rst-content tt.literal,.rst-content tt.literal,.rst-content code.literal { + color: inherit; + } +} diff --git a/roms/u-boot/doc/sphinx/automarkup.py b/roms/u-boot/doc/sphinx/automarkup.py new file mode 100644 index 000000000..953b24b6e --- /dev/null +++ b/roms/u-boot/doc/sphinx/automarkup.py @@ -0,0 +1,290 @@ +# SPDX-License-Identifier: GPL-2.0 +# Copyright 2019 Jonathan Corbet <corbet@lwn.net> +# +# Apply kernel-specific tweaks after the initial document processing +# has been done. +# +from docutils import nodes +import sphinx +from sphinx import addnodes +if sphinx.version_info[0] < 2 or \ + sphinx.version_info[0] == 2 and sphinx.version_info[1] < 1: + from sphinx.environment import NoUri +else: + from sphinx.errors import NoUri +import re +from itertools import chain + +# +# Python 2 lacks re.ASCII... +# +try: + ascii_p3 = re.ASCII +except AttributeError: + ascii_p3 = 0 + +# +# Regex nastiness. Of course. +# Try to identify "function()" that's not already marked up some +# other way. Sphinx doesn't like a lot of stuff right after a +# :c:func: block (i.e. ":c:func:`mmap()`s" flakes out), so the last +# bit tries to restrict matches to things that won't create trouble. +# +RE_function = re.compile(r'\b(([a-zA-Z_]\w+)\(\))', flags=ascii_p3) + +# +# Sphinx 2 uses the same :c:type role for struct, union, enum and typedef +# +RE_generic_type = re.compile(r'\b(struct|union|enum|typedef)\s+([a-zA-Z_]\w+)', + flags=ascii_p3) + +# +# Sphinx 3 uses a different C role for each one of struct, union, enum and +# typedef +# +RE_struct = re.compile(r'\b(struct)\s+([a-zA-Z_]\w+)', flags=ascii_p3) +RE_union = re.compile(r'\b(union)\s+([a-zA-Z_]\w+)', flags=ascii_p3) +RE_enum = re.compile(r'\b(enum)\s+([a-zA-Z_]\w+)', flags=ascii_p3) +RE_typedef = re.compile(r'\b(typedef)\s+([a-zA-Z_]\w+)', flags=ascii_p3) + +# +# Detects a reference to a documentation page of the form Documentation/... with +# an optional extension +# +RE_doc = re.compile(r'\bDocumentation(/[\w\-_/]+)(\.\w+)*') + +RE_namespace = re.compile(r'^\s*..\s*c:namespace::\s*(\S+)\s*$') + +# +# Reserved C words that we should skip when cross-referencing +# +Skipnames = [ 'for', 'if', 'register', 'sizeof', 'struct', 'unsigned' ] + + +# +# Many places in the docs refer to common system calls. It is +# pointless to try to cross-reference them and, as has been known +# to happen, somebody defining a function by these names can lead +# to the creation of incorrect and confusing cross references. So +# just don't even try with these names. +# +Skipfuncs = [ 'open', 'close', 'read', 'write', 'fcntl', 'mmap', + 'select', 'poll', 'fork', 'execve', 'clone', 'ioctl', + 'socket' ] + +c_namespace = '' + +def markup_refs(docname, app, node): + t = node.astext() + done = 0 + repl = [ ] + # + # Associate each regex with the function that will markup its matches + # + markup_func_sphinx2 = {RE_doc: markup_doc_ref, + RE_function: markup_c_ref, + RE_generic_type: markup_c_ref} + + markup_func_sphinx3 = {RE_doc: markup_doc_ref, + RE_function: markup_func_ref_sphinx3, + RE_struct: markup_c_ref, + RE_union: markup_c_ref, + RE_enum: markup_c_ref, + RE_typedef: markup_c_ref} + + if sphinx.version_info[0] >= 3: + markup_func = markup_func_sphinx3 + else: + markup_func = markup_func_sphinx2 + + match_iterators = [regex.finditer(t) for regex in markup_func] + # + # Sort all references by the starting position in text + # + sorted_matches = sorted(chain(*match_iterators), key=lambda m: m.start()) + for m in sorted_matches: + # + # Include any text prior to match as a normal text node. + # + if m.start() > done: + repl.append(nodes.Text(t[done:m.start()])) + + # + # Call the function associated with the regex that matched this text and + # append its return to the text + # + repl.append(markup_func[m.re](docname, app, m)) + + done = m.end() + if done < len(t): + repl.append(nodes.Text(t[done:])) + return repl + +# +# In sphinx3 we can cross-reference to C macro and function, each one with its +# own C role, but both match the same regex, so we try both. +# +def markup_func_ref_sphinx3(docname, app, match): + class_str = ['c-func', 'c-macro'] + reftype_str = ['function', 'macro'] + + cdom = app.env.domains['c'] + # + # Go through the dance of getting an xref out of the C domain + # + base_target = match.group(2) + target_text = nodes.Text(match.group(0)) + xref = None + possible_targets = [base_target] + # Check if this document has a namespace, and if so, try + # cross-referencing inside it first. + if c_namespace: + possible_targets.insert(0, c_namespace + "." + base_target) + + if base_target not in Skipnames: + for target in possible_targets: + if target not in Skipfuncs: + for class_s, reftype_s in zip(class_str, reftype_str): + lit_text = nodes.literal(classes=['xref', 'c', class_s]) + lit_text += target_text + pxref = addnodes.pending_xref('', refdomain = 'c', + reftype = reftype_s, + reftarget = target, modname = None, + classname = None) + # + # XXX The Latex builder will throw NoUri exceptions here, + # work around that by ignoring them. + # + try: + xref = cdom.resolve_xref(app.env, docname, app.builder, + reftype_s, target, pxref, + lit_text) + except NoUri: + xref = None + + if xref: + return xref + + return target_text + +def markup_c_ref(docname, app, match): + class_str = {# Sphinx 2 only + RE_function: 'c-func', + RE_generic_type: 'c-type', + # Sphinx 3+ only + RE_struct: 'c-struct', + RE_union: 'c-union', + RE_enum: 'c-enum', + RE_typedef: 'c-type', + } + reftype_str = {# Sphinx 2 only + RE_function: 'function', + RE_generic_type: 'type', + # Sphinx 3+ only + RE_struct: 'struct', + RE_union: 'union', + RE_enum: 'enum', + RE_typedef: 'type', + } + + cdom = app.env.domains['c'] + # + # Go through the dance of getting an xref out of the C domain + # + base_target = match.group(2) + target_text = nodes.Text(match.group(0)) + xref = None + possible_targets = [base_target] + # Check if this document has a namespace, and if so, try + # cross-referencing inside it first. + if c_namespace: + possible_targets.insert(0, c_namespace + "." + base_target) + + if base_target not in Skipnames: + for target in possible_targets: + if not (match.re == RE_function and target in Skipfuncs): + lit_text = nodes.literal(classes=['xref', 'c', class_str[match.re]]) + lit_text += target_text + pxref = addnodes.pending_xref('', refdomain = 'c', + reftype = reftype_str[match.re], + reftarget = target, modname = None, + classname = None) + # + # XXX The Latex builder will throw NoUri exceptions here, + # work around that by ignoring them. + # + try: + xref = cdom.resolve_xref(app.env, docname, app.builder, + reftype_str[match.re], target, pxref, + lit_text) + except NoUri: + xref = None + + if xref: + return xref + + return target_text + +# +# Try to replace a documentation reference of the form Documentation/... with a +# cross reference to that page +# +def markup_doc_ref(docname, app, match): + stddom = app.env.domains['std'] + # + # Go through the dance of getting an xref out of the std domain + # + target = match.group(1) + xref = None + pxref = addnodes.pending_xref('', refdomain = 'std', reftype = 'doc', + reftarget = target, modname = None, + classname = None, refexplicit = False) + # + # XXX The Latex builder will throw NoUri exceptions here, + # work around that by ignoring them. + # + try: + xref = stddom.resolve_xref(app.env, docname, app.builder, 'doc', + target, pxref, None) + except NoUri: + xref = None + # + # Return the xref if we got it; otherwise just return the plain text. + # + if xref: + return xref + else: + return nodes.Text(match.group(0)) + +def get_c_namespace(app, docname): + source = app.env.doc2path(docname) + with open(source) as f: + for l in f: + match = RE_namespace.search(l) + if match: + return match.group(1) + return '' + +def auto_markup(app, doctree, name): + global c_namespace + c_namespace = get_c_namespace(app, name) + # + # This loop could eventually be improved on. Someday maybe we + # want a proper tree traversal with a lot of awareness of which + # kinds of nodes to prune. But this works well for now. + # + # The nodes.literal test catches ``literal text``, its purpose is to + # avoid adding cross-references to functions that have been explicitly + # marked with cc:func:. + # + for para in doctree.traverse(nodes.paragraph): + for node in para.traverse(nodes.Text): + if not isinstance(node.parent, nodes.literal): + node.parent.replace(node, markup_refs(name, app, node)) + +def setup(app): + app.connect('doctree-resolved', auto_markup) + return { + 'parallel_read_safe': True, + 'parallel_write_safe': True, + } diff --git a/roms/u-boot/doc/sphinx/cdomain.py b/roms/u-boot/doc/sphinx/cdomain.py new file mode 100644 index 000000000..014a5229e --- /dev/null +++ b/roms/u-boot/doc/sphinx/cdomain.py @@ -0,0 +1,259 @@ +# -*- coding: utf-8; mode: python -*- +# pylint: disable=W0141,C0113,C0103,C0325 +u""" + cdomain + ~~~~~~~ + + Replacement for the sphinx c-domain. + + :copyright: Copyright (C) 2016 Markus Heiser + :license: GPL Version 2, June 1991 see Linux/COPYING for details. + + List of customizations: + + * Moved the *duplicate C object description* warnings for function + declarations in the nitpicky mode. See Sphinx documentation for + the config values for ``nitpick`` and ``nitpick_ignore``. + + * Add option 'name' to the "c:function:" directive. With option 'name' the + ref-name of a function can be modified. E.g.:: + + .. c:function:: int ioctl( int fd, int request ) + :name: VIDIOC_LOG_STATUS + + The func-name (e.g. ioctl) remains in the output but the ref-name changed + from 'ioctl' to 'VIDIOC_LOG_STATUS'. The function is referenced by:: + + * :c:func:`VIDIOC_LOG_STATUS` or + * :any:`VIDIOC_LOG_STATUS` (``:any:`` needs sphinx 1.3) + + * Handle signatures of function-like macros well. Don't try to deduce + arguments types of function-like macros. + +""" + +from docutils import nodes +from docutils.parsers.rst import directives + +import sphinx +from sphinx import addnodes +from sphinx.domains.c import c_funcptr_sig_re, c_sig_re +from sphinx.domains.c import CObject as Base_CObject +from sphinx.domains.c import CDomain as Base_CDomain +from itertools import chain +import re + +__version__ = '1.1' + +# Get Sphinx version +major, minor, patch = sphinx.version_info[:3] + +# Namespace to be prepended to the full name +namespace = None + +# +# Handle trivial newer c domain tags that are part of Sphinx 3.1 c domain tags +# - Store the namespace if ".. c:namespace::" tag is found +# +RE_namespace = re.compile(r'^\s*..\s*c:namespace::\s*(\S+)\s*$') + +def markup_namespace(match): + global namespace + + namespace = match.group(1) + + return "" + +# +# Handle c:macro for function-style declaration +# +RE_macro = re.compile(r'^\s*..\s*c:macro::\s*(\S+)\s+(\S.*)\s*$') +def markup_macro(match): + return ".. c:function:: " + match.group(1) + ' ' + match.group(2) + +# +# Handle newer c domain tags that are evaluated as .. c:type: for +# backward-compatibility with Sphinx < 3.0 +# +RE_ctype = re.compile(r'^\s*..\s*c:(struct|union|enum|enumerator|alias)::\s*(.*)$') + +def markup_ctype(match): + return ".. c:type:: " + match.group(2) + +# +# Handle newer c domain tags that are evaluated as :c:type: for +# backward-compatibility with Sphinx < 3.0 +# +RE_ctype_refs = re.compile(r':c:(var|struct|union|enum|enumerator)::`([^\`]+)`') +def markup_ctype_refs(match): + return ":c:type:`" + match.group(2) + '`' + +# +# Simply convert :c:expr: and :c:texpr: into a literal block. +# +RE_expr = re.compile(r':c:(expr|texpr):`([^\`]+)`') +def markup_c_expr(match): + return '\ ``' + match.group(2) + '``\ ' + +# +# Parse Sphinx 3.x C markups, replacing them by backward-compatible ones +# +def c_markups(app, docname, source): + result = "" + markup_func = { + RE_namespace: markup_namespace, + RE_expr: markup_c_expr, + RE_macro: markup_macro, + RE_ctype: markup_ctype, + RE_ctype_refs: markup_ctype_refs, + } + + lines = iter(source[0].splitlines(True)) + for n in lines: + match_iterators = [regex.finditer(n) for regex in markup_func] + matches = sorted(chain(*match_iterators), key=lambda m: m.start()) + for m in matches: + n = n[:m.start()] + markup_func[m.re](m) + n[m.end():] + + result = result + n + + source[0] = result + +# +# Now implements support for the cdomain namespacing logic +# + +def setup(app): + + # Handle easy Sphinx 3.1+ simple new tags: :c:expr and .. c:namespace:: + app.connect('source-read', c_markups) + + if (major == 1 and minor < 8): + app.override_domain(CDomain) + else: + app.add_domain(CDomain, override=True) + + return dict( + version = __version__, + parallel_read_safe = True, + parallel_write_safe = True + ) + +class CObject(Base_CObject): + + """ + Description of a C language object. + """ + option_spec = { + "name" : directives.unchanged + } + + def handle_func_like_macro(self, sig, signode): + u"""Handles signatures of function-like macros. + + If the objtype is 'function' and the the signature ``sig`` is a + function-like macro, the name of the macro is returned. Otherwise + ``False`` is returned. """ + + global namespace + + if not self.objtype == 'function': + return False + + m = c_funcptr_sig_re.match(sig) + if m is None: + m = c_sig_re.match(sig) + if m is None: + raise ValueError('no match') + + rettype, fullname, arglist, _const = m.groups() + arglist = arglist.strip() + if rettype or not arglist: + return False + + arglist = arglist.replace('`', '').replace('\\ ', '') # remove markup + arglist = [a.strip() for a in arglist.split(",")] + + # has the first argument a type? + if len(arglist[0].split(" ")) > 1: + return False + + # This is a function-like macro, it's arguments are typeless! + signode += addnodes.desc_name(fullname, fullname) + paramlist = addnodes.desc_parameterlist() + signode += paramlist + + for argname in arglist: + param = addnodes.desc_parameter('', '', noemph=True) + # separate by non-breaking space in the output + param += nodes.emphasis(argname, argname) + paramlist += param + + if namespace: + fullname = namespace + "." + fullname + + return fullname + + def handle_signature(self, sig, signode): + """Transform a C signature into RST nodes.""" + + global namespace + + fullname = self.handle_func_like_macro(sig, signode) + if not fullname: + fullname = super(CObject, self).handle_signature(sig, signode) + + if "name" in self.options: + if self.objtype == 'function': + fullname = self.options["name"] + else: + # FIXME: handle :name: value of other declaration types? + pass + else: + if namespace: + fullname = namespace + "." + fullname + + return fullname + + def add_target_and_index(self, name, sig, signode): + # for C API items we add a prefix since names are usually not qualified + # by a module name and so easily clash with e.g. section titles + targetname = 'c.' + name + if targetname not in self.state.document.ids: + signode['names'].append(targetname) + signode['ids'].append(targetname) + signode['first'] = (not self.names) + self.state.document.note_explicit_target(signode) + inv = self.env.domaindata['c']['objects'] + if (name in inv and self.env.config.nitpicky): + if self.objtype == 'function': + if ('c:func', name) not in self.env.config.nitpick_ignore: + self.state_machine.reporter.warning( + 'duplicate C object description of %s, ' % name + + 'other instance in ' + self.env.doc2path(inv[name][0]), + line=self.lineno) + inv[name] = (self.env.docname, self.objtype) + + indextext = self.get_index_text(name) + if indextext: + if major == 1 and minor < 4: + # indexnode's tuple changed in 1.4 + # https://github.com/sphinx-doc/sphinx/commit/e6a5a3a92e938fcd75866b4227db9e0524d58f7c + self.indexnode['entries'].append( + ('single', indextext, targetname, '')) + else: + self.indexnode['entries'].append( + ('single', indextext, targetname, '', None)) + +class CDomain(Base_CDomain): + + """C language domain.""" + name = 'c' + label = 'C' + directives = { + 'function': CObject, + 'member': CObject, + 'macro': CObject, + 'type': CObject, + 'var': CObject, + } diff --git a/roms/u-boot/doc/sphinx/kernel_abi.py b/roms/u-boot/doc/sphinx/kernel_abi.py new file mode 100644 index 000000000..f3da859c9 --- /dev/null +++ b/roms/u-boot/doc/sphinx/kernel_abi.py @@ -0,0 +1,194 @@ +# -*- coding: utf-8; mode: python -*- +# coding=utf-8 +# SPDX-License-Identifier: GPL-2.0 +# +u""" + kernel-abi + ~~~~~~~~~~ + + Implementation of the ``kernel-abi`` reST-directive. + + :copyright: Copyright (C) 2016 Markus Heiser + :copyright: Copyright (C) 2016-2020 Mauro Carvalho Chehab + :maintained-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> + :license: GPL Version 2, June 1991 see Linux/COPYING for details. + + The ``kernel-abi`` (:py:class:`KernelCmd`) directive calls the + scripts/get_abi.pl script to parse the Kernel ABI files. + + Overview of directive's argument and options. + + .. code-block:: rst + + .. kernel-abi:: <ABI directory location> + :debug: + + The argument ``<ABI directory location>`` is required. It contains the + location of the ABI files to be parsed. + + ``debug`` + Inserts a code-block with the *raw* reST. Sometimes it is helpful to see + what reST is generated. + +""" + +import codecs +import os +import subprocess +import sys +import re +import kernellog + +from os import path + +from docutils import nodes, statemachine +from docutils.statemachine import ViewList +from docutils.parsers.rst import directives, Directive +from docutils.utils.error_reporting import ErrorString + +# +# AutodocReporter is only good up to Sphinx 1.7 +# +import sphinx + +Use_SSI = sphinx.__version__[:3] >= '1.7' +if Use_SSI: + from sphinx.util.docutils import switch_source_input +else: + from sphinx.ext.autodoc import AutodocReporter + +__version__ = '1.0' + +def setup(app): + + app.add_directive("kernel-abi", KernelCmd) + return dict( + version = __version__ + , parallel_read_safe = True + , parallel_write_safe = True + ) + +class KernelCmd(Directive): + + u"""KernelABI (``kernel-abi``) directive""" + + required_arguments = 1 + optional_arguments = 2 + has_content = False + final_argument_whitespace = True + + option_spec = { + "debug" : directives.flag, + "rst" : directives.unchanged + } + + def run(self): + + doc = self.state.document + if not doc.settings.file_insertion_enabled: + raise self.warning("docutils: file insertion disabled") + + env = doc.settings.env + cwd = path.dirname(doc.current_source) + cmd = "get_abi.pl rest --enable-lineno --dir " + cmd += self.arguments[0] + + if 'rst' in self.options: + cmd += " --rst-source" + + srctree = path.abspath(os.environ["srctree"]) + + fname = cmd + + # extend PATH with $(srctree)/scripts + path_env = os.pathsep.join([ + srctree + os.sep + "scripts", + os.environ["PATH"] + ]) + shell_env = os.environ.copy() + shell_env["PATH"] = path_env + shell_env["srctree"] = srctree + + lines = self.runCmd(cmd, shell=True, cwd=cwd, env=shell_env) + nodeList = self.nestedParse(lines, self.arguments[0]) + return nodeList + + def runCmd(self, cmd, **kwargs): + u"""Run command ``cmd`` and return it's stdout as unicode.""" + + try: + proc = subprocess.Popen( + cmd + , stdout = subprocess.PIPE + , stderr = subprocess.PIPE + , **kwargs + ) + out, err = proc.communicate() + + out, err = codecs.decode(out, 'utf-8'), codecs.decode(err, 'utf-8') + + if proc.returncode != 0: + raise self.severe( + u"command '%s' failed with return code %d" + % (cmd, proc.returncode) + ) + except OSError as exc: + raise self.severe(u"problems with '%s' directive: %s." + % (self.name, ErrorString(exc))) + return out + + def nestedParse(self, lines, fname): + content = ViewList() + node = nodes.section() + + if "debug" in self.options: + code_block = "\n\n.. code-block:: rst\n :linenos:\n" + for l in lines.split("\n"): + code_block += "\n " + l + lines = code_block + "\n\n" + + line_regex = re.compile("^#define LINENO (\S+)\#([0-9]+)$") + ln = 0 + n = 0 + f = fname + + for line in lines.split("\n"): + n = n + 1 + match = line_regex.search(line) + if match: + new_f = match.group(1) + + # Sphinx parser is lazy: it stops parsing contents in the + # middle, if it is too big. So, handle it per input file + if new_f != f and content: + self.do_parse(content, node) + content = ViewList() + + f = new_f + + # sphinx counts lines from 0 + ln = int(match.group(2)) - 1 + else: + content.append(line, f, ln) + + kernellog.info(self.state.document.settings.env.app, "%s: parsed %i lines" % (fname, n)) + + if content: + self.do_parse(content, node) + + return node.children + + def do_parse(self, content, node): + if Use_SSI: + with switch_source_input(self.state, content): + self.state.nested_parse(content, 0, node, match_titles=1) + else: + buf = self.state.memo.title_styles, self.state.memo.section_level, self.state.memo.reporter + + self.state.memo.title_styles = [] + self.state.memo.section_level = 0 + self.state.memo.reporter = AutodocReporter(content, self.state.memo.reporter) + try: + self.state.nested_parse(content, 0, node, match_titles=1) + finally: + self.state.memo.title_styles, self.state.memo.section_level, self.state.memo.reporter = buf diff --git a/roms/u-boot/doc/sphinx/kernel_feat.py b/roms/u-boot/doc/sphinx/kernel_feat.py new file mode 100644 index 000000000..2fee04f1d --- /dev/null +++ b/roms/u-boot/doc/sphinx/kernel_feat.py @@ -0,0 +1,169 @@ +# coding=utf-8 +# SPDX-License-Identifier: GPL-2.0 +# +u""" + kernel-feat + ~~~~~~~~~~~ + + Implementation of the ``kernel-feat`` reST-directive. + + :copyright: Copyright (C) 2016 Markus Heiser + :copyright: Copyright (C) 2016-2019 Mauro Carvalho Chehab + :maintained-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org> + :license: GPL Version 2, June 1991 see Linux/COPYING for details. + + The ``kernel-feat`` (:py:class:`KernelFeat`) directive calls the + scripts/get_feat.pl script to parse the Kernel ABI files. + + Overview of directive's argument and options. + + .. code-block:: rst + + .. kernel-feat:: <ABI directory location> + :debug: + + The argument ``<ABI directory location>`` is required. It contains the + location of the ABI files to be parsed. + + ``debug`` + Inserts a code-block with the *raw* reST. Sometimes it is helpful to see + what reST is generated. + +""" + +import codecs +import os +import subprocess +import sys + +from os import path + +from docutils import nodes, statemachine +from docutils.statemachine import ViewList +from docutils.parsers.rst import directives, Directive +from docutils.utils.error_reporting import ErrorString + +# +# AutodocReporter is only good up to Sphinx 1.7 +# +import sphinx + +Use_SSI = sphinx.__version__[:3] >= '1.7' +if Use_SSI: + from sphinx.util.docutils import switch_source_input +else: + from sphinx.ext.autodoc import AutodocReporter + +__version__ = '1.0' + +def setup(app): + + app.add_directive("kernel-feat", KernelFeat) + return dict( + version = __version__ + , parallel_read_safe = True + , parallel_write_safe = True + ) + +class KernelFeat(Directive): + + u"""KernelFeat (``kernel-feat``) directive""" + + required_arguments = 1 + optional_arguments = 2 + has_content = False + final_argument_whitespace = True + + option_spec = { + "debug" : directives.flag + } + + def warn(self, message, **replace): + replace["fname"] = self.state.document.current_source + replace["line_no"] = replace.get("line_no", self.lineno) + message = ("%(fname)s:%(line_no)s: [kernel-feat WARN] : " + message) % replace + self.state.document.settings.env.app.warn(message, prefix="") + + def run(self): + + doc = self.state.document + if not doc.settings.file_insertion_enabled: + raise self.warning("docutils: file insertion disabled") + + env = doc.settings.env + cwd = path.dirname(doc.current_source) + cmd = "get_feat.pl rest --dir " + cmd += self.arguments[0] + + if len(self.arguments) > 1: + cmd += " --arch " + self.arguments[1] + + srctree = path.abspath(os.environ["srctree"]) + + fname = cmd + + # extend PATH with $(srctree)/scripts + path_env = os.pathsep.join([ + srctree + os.sep + "scripts", + os.environ["PATH"] + ]) + shell_env = os.environ.copy() + shell_env["PATH"] = path_env + shell_env["srctree"] = srctree + + lines = self.runCmd(cmd, shell=True, cwd=cwd, env=shell_env) + nodeList = self.nestedParse(lines, fname) + return nodeList + + def runCmd(self, cmd, **kwargs): + u"""Run command ``cmd`` and return it's stdout as unicode.""" + + try: + proc = subprocess.Popen( + cmd + , stdout = subprocess.PIPE + , stderr = subprocess.PIPE + , **kwargs + ) + out, err = proc.communicate() + + out, err = codecs.decode(out, 'utf-8'), codecs.decode(err, 'utf-8') + + if proc.returncode != 0: + raise self.severe( + u"command '%s' failed with return code %d" + % (cmd, proc.returncode) + ) + except OSError as exc: + raise self.severe(u"problems with '%s' directive: %s." + % (self.name, ErrorString(exc))) + return out + + def nestedParse(self, lines, fname): + content = ViewList() + node = nodes.section() + + if "debug" in self.options: + code_block = "\n\n.. code-block:: rst\n :linenos:\n" + for l in lines.split("\n"): + code_block += "\n " + l + lines = code_block + "\n\n" + + for c, l in enumerate(lines.split("\n")): + content.append(l, fname, c) + + buf = self.state.memo.title_styles, self.state.memo.section_level, self.state.memo.reporter + + if Use_SSI: + with switch_source_input(self.state, content): + self.state.nested_parse(content, 0, node, match_titles=1) + else: + self.state.memo.title_styles = [] + self.state.memo.section_level = 0 + self.state.memo.reporter = AutodocReporter(content, self.state.memo.reporter) + try: + self.state.nested_parse(content, 0, node, match_titles=1) + finally: + self.state.memo.title_styles, self.state.memo.section_level, self.state.memo.reporter = buf + + return node.children diff --git a/roms/u-boot/doc/sphinx/kernel_include.py b/roms/u-boot/doc/sphinx/kernel_include.py new file mode 100755 index 000000000..f523aa68a --- /dev/null +++ b/roms/u-boot/doc/sphinx/kernel_include.py @@ -0,0 +1,190 @@ +#!/usr/bin/env python3 +# -*- coding: utf-8; mode: python -*- +# pylint: disable=R0903, C0330, R0914, R0912, E0401 + +u""" + kernel-include + ~~~~~~~~~~~~~~ + + Implementation of the ``kernel-include`` reST-directive. + + :copyright: Copyright (C) 2016 Markus Heiser + :license: GPL Version 2, June 1991 see linux/COPYING for details. + + The ``kernel-include`` reST-directive is a replacement for the ``include`` + directive. The ``kernel-include`` directive expand environment variables in + the path name and allows to include files from arbitrary locations. + + .. hint:: + + Including files from arbitrary locations (e.g. from ``/etc``) is a + security risk for builders. This is why the ``include`` directive from + docutils *prohibit* pathnames pointing to locations *above* the filesystem + tree where the reST document with the include directive is placed. + + Substrings of the form $name or ${name} are replaced by the value of + environment variable name. Malformed variable names and references to + non-existing variables are left unchanged. +""" + +# ============================================================================== +# imports +# ============================================================================== + +import os.path + +from docutils import io, nodes, statemachine +from docutils.utils.error_reporting import SafeString, ErrorString +from docutils.parsers.rst import directives +from docutils.parsers.rst.directives.body import CodeBlock, NumberLines +from docutils.parsers.rst.directives.misc import Include + +__version__ = '1.0' + +# ============================================================================== +def setup(app): +# ============================================================================== + + app.add_directive("kernel-include", KernelInclude) + return dict( + version = __version__, + parallel_read_safe = True, + parallel_write_safe = True + ) + +# ============================================================================== +class KernelInclude(Include): +# ============================================================================== + + u"""KernelInclude (``kernel-include``) directive""" + + def run(self): + path = os.path.realpath( + os.path.expandvars(self.arguments[0])) + + # to get a bit security back, prohibit /etc: + if path.startswith(os.sep + "etc"): + raise self.severe( + 'Problems with "%s" directive, prohibited path: %s' + % (self.name, path)) + + self.arguments[0] = path + + #return super(KernelInclude, self).run() # won't work, see HINTs in _run() + return self._run() + + def _run(self): + """Include a file as part of the content of this reST file.""" + + # HINT: I had to copy&paste the whole Include.run method. I'am not happy + # with this, but due to security reasons, the Include.run method does + # not allow absolute or relative pathnames pointing to locations *above* + # the filesystem tree where the reST document is placed. + + if not self.state.document.settings.file_insertion_enabled: + raise self.warning('"%s" directive disabled.' % self.name) + source = self.state_machine.input_lines.source( + self.lineno - self.state_machine.input_offset - 1) + source_dir = os.path.dirname(os.path.abspath(source)) + path = directives.path(self.arguments[0]) + if path.startswith('<') and path.endswith('>'): + path = os.path.join(self.standard_include_path, path[1:-1]) + path = os.path.normpath(os.path.join(source_dir, path)) + + # HINT: this is the only line I had to change / commented out: + #path = utils.relative_path(None, path) + + path = nodes.reprunicode(path) + encoding = self.options.get( + 'encoding', self.state.document.settings.input_encoding) + e_handler=self.state.document.settings.input_encoding_error_handler + tab_width = self.options.get( + 'tab-width', self.state.document.settings.tab_width) + try: + self.state.document.settings.record_dependencies.add(path) + include_file = io.FileInput(source_path=path, + encoding=encoding, + error_handler=e_handler) + except UnicodeEncodeError as error: + raise self.severe('Problems with "%s" directive path:\n' + 'Cannot encode input file path "%s" ' + '(wrong locale?).' % + (self.name, SafeString(path))) + except IOError as error: + raise self.severe('Problems with "%s" directive path:\n%s.' % + (self.name, ErrorString(error))) + startline = self.options.get('start-line', None) + endline = self.options.get('end-line', None) + try: + if startline or (endline is not None): + lines = include_file.readlines() + rawtext = ''.join(lines[startline:endline]) + else: + rawtext = include_file.read() + except UnicodeError as error: + raise self.severe('Problem with "%s" directive:\n%s' % + (self.name, ErrorString(error))) + # start-after/end-before: no restrictions on newlines in match-text, + # and no restrictions on matching inside lines vs. line boundaries + after_text = self.options.get('start-after', None) + if after_text: + # skip content in rawtext before *and incl.* a matching text + after_index = rawtext.find(after_text) + if after_index < 0: + raise self.severe('Problem with "start-after" option of "%s" ' + 'directive:\nText not found.' % self.name) + rawtext = rawtext[after_index + len(after_text):] + before_text = self.options.get('end-before', None) + if before_text: + # skip content in rawtext after *and incl.* a matching text + before_index = rawtext.find(before_text) + if before_index < 0: + raise self.severe('Problem with "end-before" option of "%s" ' + 'directive:\nText not found.' % self.name) + rawtext = rawtext[:before_index] + + include_lines = statemachine.string2lines(rawtext, tab_width, + convert_whitespace=True) + if 'literal' in self.options: + # Convert tabs to spaces, if `tab_width` is positive. + if tab_width >= 0: + text = rawtext.expandtabs(tab_width) + else: + text = rawtext + literal_block = nodes.literal_block(rawtext, source=path, + classes=self.options.get('class', [])) + literal_block.line = 1 + self.add_name(literal_block) + if 'number-lines' in self.options: + try: + startline = int(self.options['number-lines'] or 1) + except ValueError: + raise self.error(':number-lines: with non-integer ' + 'start value') + endline = startline + len(include_lines) + if text.endswith('\n'): + text = text[:-1] + tokens = NumberLines([([], text)], startline, endline) + for classes, value in tokens: + if classes: + literal_block += nodes.inline(value, value, + classes=classes) + else: + literal_block += nodes.Text(value, value) + else: + literal_block += nodes.Text(text, text) + return [literal_block] + if 'code' in self.options: + self.options['source'] = path + codeblock = CodeBlock(self.name, + [self.options.pop('code')], # arguments + self.options, + include_lines, # content + self.lineno, + self.content_offset, + self.block_text, + self.state, + self.state_machine) + return codeblock.run() + self.state_machine.insert_input(include_lines, path) + return [] diff --git a/roms/u-boot/doc/sphinx/kerneldoc.py b/roms/u-boot/doc/sphinx/kerneldoc.py new file mode 100644 index 000000000..e9857ab90 --- /dev/null +++ b/roms/u-boot/doc/sphinx/kerneldoc.py @@ -0,0 +1,190 @@ +# coding=utf-8 +# +# Copyright © 2016 Intel Corporation +# +# Permission is hereby granted, free of charge, to any person obtaining a +# copy of this software and associated documentation files (the "Software"), +# to deal in the Software without restriction, including without limitation +# the rights to use, copy, modify, merge, publish, distribute, sublicense, +# and/or sell copies of the Software, and to permit persons to whom the +# Software is furnished to do so, subject to the following conditions: +# +# The above copyright notice and this permission notice (including the next +# paragraph) shall be included in all copies or substantial portions of the +# Software. +# +# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL +# THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING +# FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS +# IN THE SOFTWARE. +# +# Authors: +# Jani Nikula <jani.nikula@intel.com> +# +# Please make sure this works on both python2 and python3. +# + +import codecs +import os +import subprocess +import sys +import re +import glob + +from docutils import nodes, statemachine +from docutils.statemachine import ViewList +from docutils.parsers.rst import directives, Directive + +# +# AutodocReporter is only good up to Sphinx 1.7 +# +import sphinx + +Use_SSI = sphinx.__version__[:3] >= '1.7' +if Use_SSI: + from sphinx.util.docutils import switch_source_input +else: + from sphinx.ext.autodoc import AutodocReporter + +import kernellog + +__version__ = '1.0' + +class KernelDocDirective(Directive): + """Extract kernel-doc comments from the specified file""" + required_argument = 1 + optional_arguments = 4 + option_spec = { + 'doc': directives.unchanged_required, + 'export': directives.unchanged, + 'internal': directives.unchanged, + 'identifiers': directives.unchanged, + 'no-identifiers': directives.unchanged, + 'functions': directives.unchanged, + } + has_content = False + + def run(self): + env = self.state.document.settings.env + cmd = [env.config.kerneldoc_bin, '-rst', '-enable-lineno'] + + # Pass the version string to kernel-doc, as it needs to use a different + # dialect, depending what the C domain supports for each specific + # Sphinx versions + cmd += ['-sphinx-version', sphinx.__version__] + + filename = env.config.kerneldoc_srctree + '/' + self.arguments[0] + export_file_patterns = [] + + # Tell sphinx of the dependency + env.note_dependency(os.path.abspath(filename)) + + tab_width = self.options.get('tab-width', self.state.document.settings.tab_width) + + # 'function' is an alias of 'identifiers' + if 'functions' in self.options: + self.options['identifiers'] = self.options.get('functions') + + # FIXME: make this nicer and more robust against errors + if 'export' in self.options: + cmd += ['-export'] + export_file_patterns = str(self.options.get('export')).split() + elif 'internal' in self.options: + cmd += ['-internal'] + export_file_patterns = str(self.options.get('internal')).split() + elif 'doc' in self.options: + cmd += ['-function', str(self.options.get('doc'))] + elif 'identifiers' in self.options: + identifiers = self.options.get('identifiers').split() + if identifiers: + for i in identifiers: + cmd += ['-function', i] + else: + cmd += ['-no-doc-sections'] + + if 'no-identifiers' in self.options: + no_identifiers = self.options.get('no-identifiers').split() + if no_identifiers: + for i in no_identifiers: + cmd += ['-nosymbol', i] + + for pattern in export_file_patterns: + for f in glob.glob(env.config.kerneldoc_srctree + '/' + pattern): + env.note_dependency(os.path.abspath(f)) + cmd += ['-export-file', f] + + cmd += [filename] + + try: + kernellog.verbose(env.app, + 'calling kernel-doc \'%s\'' % (" ".join(cmd))) + + p = subprocess.Popen(cmd, stdout=subprocess.PIPE, stderr=subprocess.PIPE) + out, err = p.communicate() + + out, err = codecs.decode(out, 'utf-8'), codecs.decode(err, 'utf-8') + + if p.returncode != 0: + sys.stderr.write(err) + + kernellog.warn(env.app, + 'kernel-doc \'%s\' failed with return code %d' % (" ".join(cmd), p.returncode)) + return [nodes.error(None, nodes.paragraph(text = "kernel-doc missing"))] + elif env.config.kerneldoc_verbosity > 0: + sys.stderr.write(err) + + lines = statemachine.string2lines(out, tab_width, convert_whitespace=True) + result = ViewList() + + lineoffset = 0; + line_regex = re.compile("^#define LINENO ([0-9]+)$") + for line in lines: + match = line_regex.search(line) + if match: + # sphinx counts lines from 0 + lineoffset = int(match.group(1)) - 1 + # we must eat our comments since the upset the markup + else: + doc = env.srcdir + "/" + env.docname + ":" + str(self.lineno) + result.append(line, doc + ": " + filename, lineoffset) + lineoffset += 1 + + node = nodes.section() + self.do_parse(result, node) + + return node.children + + except Exception as e: # pylint: disable=W0703 + kernellog.warn(env.app, 'kernel-doc \'%s\' processing failed with: %s' % + (" ".join(cmd), str(e))) + return [nodes.error(None, nodes.paragraph(text = "kernel-doc missing"))] + + def do_parse(self, result, node): + if Use_SSI: + with switch_source_input(self.state, result): + self.state.nested_parse(result, 0, node, match_titles=1) + else: + save = self.state.memo.title_styles, self.state.memo.section_level, self.state.memo.reporter + self.state.memo.reporter = AutodocReporter(result, self.state.memo.reporter) + self.state.memo.title_styles, self.state.memo.section_level = [], 0 + try: + self.state.nested_parse(result, 0, node, match_titles=1) + finally: + self.state.memo.title_styles, self.state.memo.section_level, self.state.memo.reporter = save + + +def setup(app): + app.add_config_value('kerneldoc_bin', None, 'env') + app.add_config_value('kerneldoc_srctree', None, 'env') + app.add_config_value('kerneldoc_verbosity', 1, 'env') + + app.add_directive('kernel-doc', KernelDocDirective) + + return dict( + version = __version__, + parallel_read_safe = True, + parallel_write_safe = True + ) diff --git a/roms/u-boot/doc/sphinx/kernellog.py b/roms/u-boot/doc/sphinx/kernellog.py new file mode 100644 index 000000000..8ac7d274f --- /dev/null +++ b/roms/u-boot/doc/sphinx/kernellog.py @@ -0,0 +1,32 @@ +# SPDX-License-Identifier: GPL-2.0 +# +# Sphinx has deprecated its older logging interface, but the replacement +# only goes back to 1.6. So here's a wrapper layer to keep around for +# as long as we support 1.4. +# +import sphinx + +if sphinx.__version__[:3] >= '1.6': + UseLogging = True + from sphinx.util import logging + logger = logging.getLogger('kerneldoc') +else: + UseLogging = False + +def warn(app, message): + if UseLogging: + logger.warning(message) + else: + app.warn(message) + +def verbose(app, message): + if UseLogging: + logger.verbose(message) + else: + app.verbose(message) + +def info(app, message): + if UseLogging: + logger.info(message) + else: + app.info(message) diff --git a/roms/u-boot/doc/sphinx/kfigure.py b/roms/u-boot/doc/sphinx/kfigure.py new file mode 100644 index 000000000..788704886 --- /dev/null +++ b/roms/u-boot/doc/sphinx/kfigure.py @@ -0,0 +1,557 @@ +# -*- coding: utf-8; mode: python -*- +# pylint: disable=C0103, R0903, R0912, R0915 +u""" + scalable figure and image handling + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + + Sphinx extension which implements scalable image handling. + + :copyright: Copyright (C) 2016 Markus Heiser + :license: GPL Version 2, June 1991 see Linux/COPYING for details. + + The build for image formats depend on image's source format and output's + destination format. This extension implement methods to simplify image + handling from the author's POV. Directives like ``kernel-figure`` implement + methods *to* always get the best output-format even if some tools are not + installed. For more details take a look at ``convert_image(...)`` which is + the core of all conversions. + + * ``.. kernel-image``: for image handling / a ``.. image::`` replacement + + * ``.. kernel-figure``: for figure handling / a ``.. figure::`` replacement + + * ``.. kernel-render``: for render markup / a concept to embed *render* + markups (or languages). Supported markups (see ``RENDER_MARKUP_EXT``) + + - ``DOT``: render embedded Graphviz's **DOC** + - ``SVG``: render embedded Scalable Vector Graphics (**SVG**) + - ... *developable* + + Used tools: + + * ``dot(1)``: Graphviz (https://www.graphviz.org). If Graphviz is not + available, the DOT language is inserted as literal-block. + + * SVG to PDF: To generate PDF, you need at least one of this tools: + + - ``convert(1)``: ImageMagick (https://www.imagemagick.org) + + List of customizations: + + * generate PDF from SVG / used by PDF (LaTeX) builder + + * generate SVG (html-builder) and PDF (latex-builder) from DOT files. + DOT: see https://www.graphviz.org/content/dot-language + + """ + +import os +from os import path +import subprocess +from hashlib import sha1 +import sys + +from docutils import nodes +from docutils.statemachine import ViewList +from docutils.parsers.rst import directives +from docutils.parsers.rst.directives import images +import sphinx + +from sphinx.util.nodes import clean_astext +from six import iteritems + +import kernellog + +PY3 = sys.version_info[0] == 3 + +if PY3: + _unicode = str +else: + _unicode = unicode + +# Get Sphinx version +major, minor, patch = sphinx.version_info[:3] +if major == 1 and minor > 3: + # patches.Figure only landed in Sphinx 1.4 + from sphinx.directives.patches import Figure # pylint: disable=C0413 +else: + Figure = images.Figure + +__version__ = '1.0.0' + +# simple helper +# ------------- + +def which(cmd): + """Searches the ``cmd`` in the ``PATH`` environment. + + This *which* searches the PATH for executable ``cmd`` . First match is + returned, if nothing is found, ``None` is returned. + """ + envpath = os.environ.get('PATH', None) or os.defpath + for folder in envpath.split(os.pathsep): + fname = folder + os.sep + cmd + if path.isfile(fname): + return fname + +def mkdir(folder, mode=0o775): + if not path.isdir(folder): + os.makedirs(folder, mode) + +def file2literal(fname): + with open(fname, "r") as src: + data = src.read() + node = nodes.literal_block(data, data) + return node + +def isNewer(path1, path2): + """Returns True if ``path1`` is newer than ``path2`` + + If ``path1`` exists and is newer than ``path2`` the function returns + ``True`` is returned otherwise ``False`` + """ + return (path.exists(path1) + and os.stat(path1).st_ctime > os.stat(path2).st_ctime) + +def pass_handle(self, node): # pylint: disable=W0613 + pass + +# setup conversion tools and sphinx extension +# ------------------------------------------- + +# Graphviz's dot(1) support +dot_cmd = None + +# ImageMagick' convert(1) support +convert_cmd = None + + +def setup(app): + # check toolchain first + app.connect('builder-inited', setupTools) + + # image handling + app.add_directive("kernel-image", KernelImage) + app.add_node(kernel_image, + html = (visit_kernel_image, pass_handle), + latex = (visit_kernel_image, pass_handle), + texinfo = (visit_kernel_image, pass_handle), + text = (visit_kernel_image, pass_handle), + man = (visit_kernel_image, pass_handle), ) + + # figure handling + app.add_directive("kernel-figure", KernelFigure) + app.add_node(kernel_figure, + html = (visit_kernel_figure, pass_handle), + latex = (visit_kernel_figure, pass_handle), + texinfo = (visit_kernel_figure, pass_handle), + text = (visit_kernel_figure, pass_handle), + man = (visit_kernel_figure, pass_handle), ) + + # render handling + app.add_directive('kernel-render', KernelRender) + app.add_node(kernel_render, + html = (visit_kernel_render, pass_handle), + latex = (visit_kernel_render, pass_handle), + texinfo = (visit_kernel_render, pass_handle), + text = (visit_kernel_render, pass_handle), + man = (visit_kernel_render, pass_handle), ) + + app.connect('doctree-read', add_kernel_figure_to_std_domain) + + return dict( + version = __version__, + parallel_read_safe = True, + parallel_write_safe = True + ) + + +def setupTools(app): + u""" + Check available build tools and log some *verbose* messages. + + This function is called once, when the builder is initiated. + """ + global dot_cmd, convert_cmd # pylint: disable=W0603 + kernellog.verbose(app, "kfigure: check installed tools ...") + + dot_cmd = which('dot') + convert_cmd = which('convert') + + if dot_cmd: + kernellog.verbose(app, "use dot(1) from: " + dot_cmd) + else: + kernellog.warn(app, "dot(1) not found, for better output quality install " + "graphviz from https://www.graphviz.org") + if convert_cmd: + kernellog.verbose(app, "use convert(1) from: " + convert_cmd) + else: + kernellog.warn(app, + "convert(1) not found, for SVG to PDF conversion install " + "ImageMagick (https://www.imagemagick.org)") + + +# integrate conversion tools +# -------------------------- + +RENDER_MARKUP_EXT = { + # The '.ext' must be handled by convert_image(..) function's *in_ext* input. + # <name> : <.ext> + 'DOT' : '.dot', + 'SVG' : '.svg' +} + +def convert_image(img_node, translator, src_fname=None): + """Convert a image node for the builder. + + Different builder prefer different image formats, e.g. *latex* builder + prefer PDF while *html* builder prefer SVG format for images. + + This function handles output image formats in dependence of source the + format (of the image) and the translator's output format. + """ + app = translator.builder.app + + fname, in_ext = path.splitext(path.basename(img_node['uri'])) + if src_fname is None: + src_fname = path.join(translator.builder.srcdir, img_node['uri']) + if not path.exists(src_fname): + src_fname = path.join(translator.builder.outdir, img_node['uri']) + + dst_fname = None + + # in kernel builds, use 'make SPHINXOPTS=-v' to see verbose messages + + kernellog.verbose(app, 'assert best format for: ' + img_node['uri']) + + if in_ext == '.dot': + + if not dot_cmd: + kernellog.verbose(app, + "dot from graphviz not available / include DOT raw.") + img_node.replace_self(file2literal(src_fname)) + + elif translator.builder.format == 'latex': + dst_fname = path.join(translator.builder.outdir, fname + '.pdf') + img_node['uri'] = fname + '.pdf' + img_node['candidates'] = {'*': fname + '.pdf'} + + + elif translator.builder.format == 'html': + dst_fname = path.join( + translator.builder.outdir, + translator.builder.imagedir, + fname + '.svg') + img_node['uri'] = path.join( + translator.builder.imgpath, fname + '.svg') + img_node['candidates'] = { + '*': path.join(translator.builder.imgpath, fname + '.svg')} + + else: + # all other builder formats will include DOT as raw + img_node.replace_self(file2literal(src_fname)) + + elif in_ext == '.svg': + + if translator.builder.format == 'latex': + if convert_cmd is None: + kernellog.verbose(app, + "no SVG to PDF conversion available / include SVG raw.") + img_node.replace_self(file2literal(src_fname)) + else: + dst_fname = path.join(translator.builder.outdir, fname + '.pdf') + img_node['uri'] = fname + '.pdf' + img_node['candidates'] = {'*': fname + '.pdf'} + + if dst_fname: + # the builder needs not to copy one more time, so pop it if exists. + translator.builder.images.pop(img_node['uri'], None) + _name = dst_fname[len(translator.builder.outdir) + 1:] + + if isNewer(dst_fname, src_fname): + kernellog.verbose(app, + "convert: {out}/%s already exists and is newer" % _name) + + else: + ok = False + mkdir(path.dirname(dst_fname)) + + if in_ext == '.dot': + kernellog.verbose(app, 'convert DOT to: {out}/' + _name) + ok = dot2format(app, src_fname, dst_fname) + + elif in_ext == '.svg': + kernellog.verbose(app, 'convert SVG to: {out}/' + _name) + ok = svg2pdf(app, src_fname, dst_fname) + + if not ok: + img_node.replace_self(file2literal(src_fname)) + + +def dot2format(app, dot_fname, out_fname): + """Converts DOT file to ``out_fname`` using ``dot(1)``. + + * ``dot_fname`` pathname of the input DOT file, including extension ``.dot`` + * ``out_fname`` pathname of the output file, including format extension + + The *format extension* depends on the ``dot`` command (see ``man dot`` + option ``-Txxx``). Normally you will use one of the following extensions: + + - ``.ps`` for PostScript, + - ``.svg`` or ``svgz`` for Structured Vector Graphics, + - ``.fig`` for XFIG graphics and + - ``.png`` or ``gif`` for common bitmap graphics. + + """ + out_format = path.splitext(out_fname)[1][1:] + cmd = [dot_cmd, '-T%s' % out_format, dot_fname] + exit_code = 42 + + with open(out_fname, "w") as out: + exit_code = subprocess.call(cmd, stdout = out) + if exit_code != 0: + kernellog.warn(app, + "Error #%d when calling: %s" % (exit_code, " ".join(cmd))) + return bool(exit_code == 0) + +def svg2pdf(app, svg_fname, pdf_fname): + """Converts SVG to PDF with ``convert(1)`` command. + + Uses ``convert(1)`` from ImageMagick (https://www.imagemagick.org) for + conversion. Returns ``True`` on success and ``False`` if an error occurred. + + * ``svg_fname`` pathname of the input SVG file with extension (``.svg``) + * ``pdf_name`` pathname of the output PDF file with extension (``.pdf``) + + """ + cmd = [convert_cmd, svg_fname, pdf_fname] + # use stdout and stderr from parent + exit_code = subprocess.call(cmd) + if exit_code != 0: + kernellog.warn(app, "Error #%d when calling: %s" % (exit_code, " ".join(cmd))) + return bool(exit_code == 0) + + +# image handling +# --------------------- + +def visit_kernel_image(self, node): # pylint: disable=W0613 + """Visitor of the ``kernel_image`` Node. + + Handles the ``image`` child-node with the ``convert_image(...)``. + """ + img_node = node[0] + convert_image(img_node, self) + +class kernel_image(nodes.image): + """Node for ``kernel-image`` directive.""" + pass + +class KernelImage(images.Image): + u"""KernelImage directive + + Earns everything from ``.. image::`` directive, except *remote URI* and + *glob* pattern. The KernelImage wraps a image node into a + kernel_image node. See ``visit_kernel_image``. + """ + + def run(self): + uri = self.arguments[0] + if uri.endswith('.*') or uri.find('://') != -1: + raise self.severe( + 'Error in "%s: %s": glob pattern and remote images are not allowed' + % (self.name, uri)) + result = images.Image.run(self) + if len(result) == 2 or isinstance(result[0], nodes.system_message): + return result + (image_node,) = result + # wrap image node into a kernel_image node / see visitors + node = kernel_image('', image_node) + return [node] + +# figure handling +# --------------------- + +def visit_kernel_figure(self, node): # pylint: disable=W0613 + """Visitor of the ``kernel_figure`` Node. + + Handles the ``image`` child-node with the ``convert_image(...)``. + """ + img_node = node[0][0] + convert_image(img_node, self) + +class kernel_figure(nodes.figure): + """Node for ``kernel-figure`` directive.""" + +class KernelFigure(Figure): + u"""KernelImage directive + + Earns everything from ``.. figure::`` directive, except *remote URI* and + *glob* pattern. The KernelFigure wraps a figure node into a kernel_figure + node. See ``visit_kernel_figure``. + """ + + def run(self): + uri = self.arguments[0] + if uri.endswith('.*') or uri.find('://') != -1: + raise self.severe( + 'Error in "%s: %s":' + ' glob pattern and remote images are not allowed' + % (self.name, uri)) + result = Figure.run(self) + if len(result) == 2 or isinstance(result[0], nodes.system_message): + return result + (figure_node,) = result + # wrap figure node into a kernel_figure node / see visitors + node = kernel_figure('', figure_node) + return [node] + + +# render handling +# --------------------- + +def visit_kernel_render(self, node): + """Visitor of the ``kernel_render`` Node. + + If rendering tools available, save the markup of the ``literal_block`` child + node into a file and replace the ``literal_block`` node with a new created + ``image`` node, pointing to the saved markup file. Afterwards, handle the + image child-node with the ``convert_image(...)``. + """ + app = self.builder.app + srclang = node.get('srclang') + + kernellog.verbose(app, 'visit kernel-render node lang: "%s"' % (srclang)) + + tmp_ext = RENDER_MARKUP_EXT.get(srclang, None) + if tmp_ext is None: + kernellog.warn(app, 'kernel-render: "%s" unknown / include raw.' % (srclang)) + return + + if not dot_cmd and tmp_ext == '.dot': + kernellog.verbose(app, "dot from graphviz not available / include raw.") + return + + literal_block = node[0] + + code = literal_block.astext() + hashobj = code.encode('utf-8') # str(node.attributes) + fname = path.join('%s-%s' % (srclang, sha1(hashobj).hexdigest())) + + tmp_fname = path.join( + self.builder.outdir, self.builder.imagedir, fname + tmp_ext) + + if not path.isfile(tmp_fname): + mkdir(path.dirname(tmp_fname)) + with open(tmp_fname, "w") as out: + out.write(code) + + img_node = nodes.image(node.rawsource, **node.attributes) + img_node['uri'] = path.join(self.builder.imgpath, fname + tmp_ext) + img_node['candidates'] = { + '*': path.join(self.builder.imgpath, fname + tmp_ext)} + + literal_block.replace_self(img_node) + convert_image(img_node, self, tmp_fname) + + +class kernel_render(nodes.General, nodes.Inline, nodes.Element): + """Node for ``kernel-render`` directive.""" + pass + +class KernelRender(Figure): + u"""KernelRender directive + + Render content by external tool. Has all the options known from the + *figure* directive, plus option ``caption``. If ``caption`` has a + value, a figure node with the *caption* is inserted. If not, a image node is + inserted. + + The KernelRender directive wraps the text of the directive into a + literal_block node and wraps it into a kernel_render node. See + ``visit_kernel_render``. + """ + has_content = True + required_arguments = 1 + optional_arguments = 0 + final_argument_whitespace = False + + # earn options from 'figure' + option_spec = Figure.option_spec.copy() + option_spec['caption'] = directives.unchanged + + def run(self): + return [self.build_node()] + + def build_node(self): + + srclang = self.arguments[0].strip() + if srclang not in RENDER_MARKUP_EXT.keys(): + return [self.state_machine.reporter.warning( + 'Unknown source language "%s", use one of: %s.' % ( + srclang, ",".join(RENDER_MARKUP_EXT.keys())), + line=self.lineno)] + + code = '\n'.join(self.content) + if not code.strip(): + return [self.state_machine.reporter.warning( + 'Ignoring "%s" directive without content.' % ( + self.name), + line=self.lineno)] + + node = kernel_render() + node['alt'] = self.options.get('alt','') + node['srclang'] = srclang + literal_node = nodes.literal_block(code, code) + node += literal_node + + caption = self.options.get('caption') + if caption: + # parse caption's content + parsed = nodes.Element() + self.state.nested_parse( + ViewList([caption], source=''), self.content_offset, parsed) + caption_node = nodes.caption( + parsed[0].rawsource, '', *parsed[0].children) + caption_node.source = parsed[0].source + caption_node.line = parsed[0].line + + figure_node = nodes.figure('', node) + for k,v in self.options.items(): + figure_node[k] = v + figure_node += caption_node + + node = figure_node + + return node + +def add_kernel_figure_to_std_domain(app, doctree): + """Add kernel-figure anchors to 'std' domain. + + The ``StandardDomain.process_doc(..)`` method does not know how to resolve + the caption (label) of ``kernel-figure`` directive (it only knows about + standard nodes, e.g. table, figure etc.). Without any additional handling + this will result in a 'undefined label' for kernel-figures. + + This handle adds labels of kernel-figure to the 'std' domain labels. + """ + + std = app.env.domains["std"] + docname = app.env.docname + labels = std.data["labels"] + + for name, explicit in iteritems(doctree.nametypes): + if not explicit: + continue + labelid = doctree.nameids[name] + if labelid is None: + continue + node = doctree.ids[labelid] + + if node.tagname == 'kernel_figure': + for n in node.next_node(): + if n.tagname == 'caption': + sectname = clean_astext(n) + # add label to std domain + labels[name] = docname, labelid, sectname + break diff --git a/roms/u-boot/doc/sphinx/load_config.py b/roms/u-boot/doc/sphinx/load_config.py new file mode 100644 index 000000000..eeb394b39 --- /dev/null +++ b/roms/u-boot/doc/sphinx/load_config.py @@ -0,0 +1,57 @@ +# -*- coding: utf-8; mode: python -*- +# pylint: disable=R0903, C0330, R0914, R0912, E0401 + +import os +import sys +from sphinx.util.pycompat import execfile_ + +# ------------------------------------------------------------------------------ +def loadConfig(namespace): +# ------------------------------------------------------------------------------ + + u"""Load an additional configuration file into *namespace*. + + The name of the configuration file is taken from the environment + ``SPHINX_CONF``. The external configuration file extends (or overwrites) the + configuration values from the origin ``conf.py``. With this you are able to + maintain *build themes*. """ + + config_file = os.environ.get("SPHINX_CONF", None) + if (config_file is not None + and os.path.normpath(namespace["__file__"]) != os.path.normpath(config_file) ): + config_file = os.path.abspath(config_file) + + # Let's avoid one conf.py file just due to latex_documents + start = config_file.find('Documentation/') + if start >= 0: + start = config_file.find('/', start + 1) + + end = config_file.rfind('/') + if start >= 0 and end > 0: + dir = config_file[start + 1:end] + + print("source directory: %s" % dir) + new_latex_docs = [] + latex_documents = namespace['latex_documents'] + + for l in latex_documents: + if l[0].find(dir + '/') == 0: + has = True + fn = l[0][len(dir) + 1:] + new_latex_docs.append((fn, l[1], l[2], l[3], l[4])) + break + + namespace['latex_documents'] = new_latex_docs + + # If there is an extra conf.py file, load it + if os.path.isfile(config_file): + sys.stdout.write("load additional sphinx-config: %s\n" % config_file) + config = namespace.copy() + config['__file__'] = config_file + execfile_(config_file, config) + del config['__file__'] + namespace.update(config) + else: + config = namespace.copy() + config['tags'].add("subproject") + namespace.update(config) diff --git a/roms/u-boot/doc/sphinx/maintainers_include.py b/roms/u-boot/doc/sphinx/maintainers_include.py new file mode 100755 index 000000000..dc8fed48d --- /dev/null +++ b/roms/u-boot/doc/sphinx/maintainers_include.py @@ -0,0 +1,197 @@ +#!/usr/bin/env python +# SPDX-License-Identifier: GPL-2.0 +# -*- coding: utf-8; mode: python -*- +# pylint: disable=R0903, C0330, R0914, R0912, E0401 + +u""" + maintainers-include + ~~~~~~~~~~~~~~~~~~~ + + Implementation of the ``maintainers-include`` reST-directive. + + :copyright: Copyright (C) 2019 Kees Cook <keescook@chromium.org> + :license: GPL Version 2, June 1991 see linux/COPYING for details. + + The ``maintainers-include`` reST-directive performs extensive parsing + specific to the Linux kernel's standard "MAINTAINERS" file, in an + effort to avoid needing to heavily mark up the original plain text. +""" + +import sys +import re +import os.path + +from docutils import statemachine +from docutils.utils.error_reporting import ErrorString +from docutils.parsers.rst import Directive +from docutils.parsers.rst.directives.misc import Include + +__version__ = '1.0' + +def setup(app): + app.add_directive("maintainers-include", MaintainersInclude) + return dict( + version = __version__, + parallel_read_safe = True, + parallel_write_safe = True + ) + +class MaintainersInclude(Include): + u"""MaintainersInclude (``maintainers-include``) directive""" + required_arguments = 0 + + def parse_maintainers(self, path): + """Parse all the MAINTAINERS lines into ReST for human-readability""" + + result = list() + result.append(".. _maintainers:") + result.append("") + + # Poor man's state machine. + descriptions = False + maintainers = False + subsystems = False + + # Field letter to field name mapping. + field_letter = None + fields = dict() + + prev = None + field_prev = "" + field_content = "" + + for line in open(path): + if sys.version_info.major == 2: + line = unicode(line, 'utf-8') + # Have we reached the end of the preformatted Descriptions text? + if descriptions and line.startswith('Maintainers'): + descriptions = False + # Ensure a blank line following the last "|"-prefixed line. + result.append("") + + # Start subsystem processing? This is to skip processing the text + # between the Maintainers heading and the first subsystem name. + if maintainers and not subsystems: + if re.search('^[A-Z0-9]', line): + subsystems = True + + # Drop needless input whitespace. + line = line.rstrip() + + # Linkify all non-wildcard refs to ReST files in Documentation/. + pat = '(Documentation/([^\s\?\*]*)\.rst)' + m = re.search(pat, line) + if m: + # maintainers.rst is in a subdirectory, so include "../". + line = re.sub(pat, ':doc:`%s <../%s>`' % (m.group(2), m.group(2)), line) + + # Check state machine for output rendering behavior. + output = None + if descriptions: + # Escape the escapes in preformatted text. + output = "| %s" % (line.replace("\\", "\\\\")) + # Look for and record field letter to field name mappings: + # R: Designated *reviewer*: FullName <address@domain> + m = re.search("\s(\S):\s", line) + if m: + field_letter = m.group(1) + if field_letter and not field_letter in fields: + m = re.search("\*([^\*]+)\*", line) + if m: + fields[field_letter] = m.group(1) + elif subsystems: + # Skip empty lines: subsystem parser adds them as needed. + if len(line) == 0: + continue + # Subsystem fields are batched into "field_content" + if line[1] != ':': + # Render a subsystem entry as: + # SUBSYSTEM NAME + # ~~~~~~~~~~~~~~ + + # Flush pending field content. + output = field_content + "\n\n" + field_content = "" + + # Collapse whitespace in subsystem name. + heading = re.sub("\s+", " ", line) + output = output + "%s\n%s" % (heading, "~" * len(heading)) + field_prev = "" + else: + # Render a subsystem field as: + # :Field: entry + # entry... + field, details = line.split(':', 1) + details = details.strip() + + # Mark paths (and regexes) as literal text for improved + # readability and to escape any escapes. + if field in ['F', 'N', 'X', 'K']: + # But only if not already marked :) + if not ':doc:' in details: + details = '``%s``' % (details) + + # Comma separate email field continuations. + if field == field_prev and field_prev in ['M', 'R', 'L']: + field_content = field_content + "," + + # Do not repeat field names, so that field entries + # will be collapsed together. + if field != field_prev: + output = field_content + "\n" + field_content = ":%s:" % (fields.get(field, field)) + field_content = field_content + "\n\t%s" % (details) + field_prev = field + else: + output = line + + # Re-split on any added newlines in any above parsing. + if output != None: + for separated in output.split('\n'): + result.append(separated) + + # Update the state machine when we find heading separators. + if line.startswith('----------'): + if prev.startswith('Descriptions'): + descriptions = True + if prev.startswith('Maintainers'): + maintainers = True + + # Retain previous line for state machine transitions. + prev = line + + # Flush pending field contents. + if field_content != "": + for separated in field_content.split('\n'): + result.append(separated) + + output = "\n".join(result) + # For debugging the pre-rendered results... + #print(output, file=open("/tmp/MAINTAINERS.rst", "w")) + + self.state_machine.insert_input( + statemachine.string2lines(output), path) + + def run(self): + """Include the MAINTAINERS file as part of this reST file.""" + if not self.state.document.settings.file_insertion_enabled: + raise self.warning('"%s" directive disabled.' % self.name) + + # Walk up source path directories to find Documentation/../ + path = self.state_machine.document.attributes['source'] + path = os.path.realpath(path) + tail = path + while tail != "Documentation" and tail != "": + (path, tail) = os.path.split(path) + + # Append "MAINTAINERS" + path = os.path.join(path, "MAINTAINERS") + + try: + self.state.document.settings.record_dependencies.add(path) + lines = self.parse_maintainers(path) + except IOError as error: + raise self.severe('Problems with "%s" directive path:\n%s.' % + (self.name, ErrorString(error))) + + return [] diff --git a/roms/u-boot/doc/sphinx/parallel-wrapper.sh b/roms/u-boot/doc/sphinx/parallel-wrapper.sh new file mode 100644 index 000000000..e54c44ce1 --- /dev/null +++ b/roms/u-boot/doc/sphinx/parallel-wrapper.sh @@ -0,0 +1,33 @@ +#!/bin/sh +# SPDX-License-Identifier: GPL-2.0+ +# +# Figure out if we should follow a specific parallelism from the make +# environment (as exported by scripts/jobserver-exec), or fall back to +# the "auto" parallelism when "-jN" is not specified at the top-level +# "make" invocation. + +sphinx="$1" +shift || true + +parallel="$PARALLELISM" +if [ -z "$parallel" ] ; then + # If no parallelism is specified at the top-level make, then + # fall back to the expected "-jauto" mode that the "htmldocs" + # target has had. + auto=$(perl -e 'open IN,"'"$sphinx"' --version 2>&1 |"; + while (<IN>) { + if (m/([\d\.]+)/) { + print "auto" if ($1 >= "1.7") + } + } + close IN') + if [ -n "$auto" ] ; then + parallel="$auto" + fi +fi +# Only if some parallelism has been determined do we add the -jN option. +if [ -n "$parallel" ] ; then + parallel="-j$parallel" +fi + +exec "$sphinx" $parallel "$@" diff --git a/roms/u-boot/doc/sphinx/parse-headers.pl b/roms/u-boot/doc/sphinx/parse-headers.pl new file mode 100755 index 000000000..b063f2f1c --- /dev/null +++ b/roms/u-boot/doc/sphinx/parse-headers.pl @@ -0,0 +1,401 @@ +#!/usr/bin/env perl +use strict; +use Text::Tabs; +use Getopt::Long; +use Pod::Usage; + +my $debug; +my $help; +my $man; + +GetOptions( + "debug" => \$debug, + 'usage|?' => \$help, + 'help' => \$man +) or pod2usage(2); + +pod2usage(1) if $help; +pod2usage(-exitstatus => 0, -verbose => 2) if $man; +pod2usage(2) if (scalar @ARGV < 2 || scalar @ARGV > 3); + +my ($file_in, $file_out, $file_exceptions) = @ARGV; + +my $data; +my %ioctls; +my %defines; +my %typedefs; +my %enums; +my %enum_symbols; +my %structs; + +require Data::Dumper if ($debug); + +# +# read the file and get identifiers +# + +my $is_enum = 0; +my $is_comment = 0; +open IN, $file_in or die "Can't open $file_in"; +while (<IN>) { + $data .= $_; + + my $ln = $_; + if (!$is_comment) { + $ln =~ s,/\*.*(\*/),,g; + + $is_comment = 1 if ($ln =~ s,/\*.*,,); + } else { + if ($ln =~ s,^(.*\*/),,) { + $is_comment = 0; + } else { + next; + } + } + + if ($is_enum && $ln =~ m/^\s*([_\w][\w\d_]+)\s*[\,=]?/) { + my $s = $1; + my $n = $1; + $n =~ tr/A-Z/a-z/; + $n =~ tr/_/-/; + + $enum_symbols{$s} = "\\ :ref:`$s <$n>`\\ "; + + $is_enum = 0 if ($is_enum && m/\}/); + next; + } + $is_enum = 0 if ($is_enum && m/\}/); + + if ($ln =~ m/^\s*#\s*define\s+([_\w][\w\d_]+)\s+_IO/) { + my $s = $1; + my $n = $1; + $n =~ tr/A-Z/a-z/; + + $ioctls{$s} = "\\ :ref:`$s <$n>`\\ "; + next; + } + + if ($ln =~ m/^\s*#\s*define\s+([_\w][\w\d_]+)\s+/) { + my $s = $1; + my $n = $1; + $n =~ tr/A-Z/a-z/; + $n =~ tr/_/-/; + + $defines{$s} = "\\ :ref:`$s <$n>`\\ "; + next; + } + + if ($ln =~ m/^\s*typedef\s+([_\w][\w\d_]+)\s+(.*)\s+([_\w][\w\d_]+);/) { + my $s = $2; + my $n = $3; + + $typedefs{$n} = "\\ :c:type:`$n <$s>`\\ "; + next; + } + if ($ln =~ m/^\s*enum\s+([_\w][\w\d_]+)\s+\{/ + || $ln =~ m/^\s*enum\s+([_\w][\w\d_]+)$/ + || $ln =~ m/^\s*typedef\s*enum\s+([_\w][\w\d_]+)\s+\{/ + || $ln =~ m/^\s*typedef\s*enum\s+([_\w][\w\d_]+)$/) { + my $s = $1; + + $enums{$s} = "enum :c:type:`$s`\\ "; + + $is_enum = $1; + next; + } + if ($ln =~ m/^\s*struct\s+([_\w][\w\d_]+)\s+\{/ + || $ln =~ m/^\s*struct\s+([[_\w][\w\d_]+)$/ + || $ln =~ m/^\s*typedef\s*struct\s+([_\w][\w\d_]+)\s+\{/ + || $ln =~ m/^\s*typedef\s*struct\s+([[_\w][\w\d_]+)$/ + ) { + my $s = $1; + + $structs{$s} = "struct $s\\ "; + next; + } +} +close IN; + +# +# Handle multi-line typedefs +# + +my @matches = ($data =~ m/typedef\s+struct\s+\S+?\s*\{[^\}]+\}\s*(\S+)\s*\;/g, + $data =~ m/typedef\s+enum\s+\S+?\s*\{[^\}]+\}\s*(\S+)\s*\;/g,); +foreach my $m (@matches) { + my $s = $m; + + $typedefs{$s} = "\\ :c:type:`$s`\\ "; + next; +} + +# +# Handle exceptions, if any +# + +my %def_reftype = ( + "ioctl" => ":ref", + "define" => ":ref", + "symbol" => ":ref", + "typedef" => ":c:type", + "enum" => ":c:type", + "struct" => ":c:type", +); + +if ($file_exceptions) { + open IN, $file_exceptions or die "Can't read $file_exceptions"; + while (<IN>) { + next if (m/^\s*$/ || m/^\s*#/); + + # Parsers to ignore a symbol + + if (m/^ignore\s+ioctl\s+(\S+)/) { + delete $ioctls{$1} if (exists($ioctls{$1})); + next; + } + if (m/^ignore\s+define\s+(\S+)/) { + delete $defines{$1} if (exists($defines{$1})); + next; + } + if (m/^ignore\s+typedef\s+(\S+)/) { + delete $typedefs{$1} if (exists($typedefs{$1})); + next; + } + if (m/^ignore\s+enum\s+(\S+)/) { + delete $enums{$1} if (exists($enums{$1})); + next; + } + if (m/^ignore\s+struct\s+(\S+)/) { + delete $structs{$1} if (exists($structs{$1})); + next; + } + if (m/^ignore\s+symbol\s+(\S+)/) { + delete $enum_symbols{$1} if (exists($enum_symbols{$1})); + next; + } + + # Parsers to replace a symbol + my ($type, $old, $new, $reftype); + + if (m/^replace\s+(\S+)\s+(\S+)\s+(\S+)/) { + $type = $1; + $old = $2; + $new = $3; + } else { + die "Can't parse $file_exceptions: $_"; + } + + if ($new =~ m/^\:c\:(data|func|macro|type)\:\`(.+)\`/) { + $reftype = ":c:$1"; + $new = $2; + } elsif ($new =~ m/\:ref\:\`(.+)\`/) { + $reftype = ":ref"; + $new = $1; + } else { + $reftype = $def_reftype{$type}; + } + $new = "$reftype:`$old <$new>`"; + + if ($type eq "ioctl") { + $ioctls{$old} = $new if (exists($ioctls{$old})); + next; + } + if ($type eq "define") { + $defines{$old} = $new if (exists($defines{$old})); + next; + } + if ($type eq "symbol") { + $enum_symbols{$old} = $new if (exists($enum_symbols{$old})); + next; + } + if ($type eq "typedef") { + $typedefs{$old} = $new if (exists($typedefs{$old})); + next; + } + if ($type eq "enum") { + $enums{$old} = $new if (exists($enums{$old})); + next; + } + if ($type eq "struct") { + $structs{$old} = $new if (exists($structs{$old})); + next; + } + + die "Can't parse $file_exceptions: $_"; + } +} + +if ($debug) { + print Data::Dumper->Dump([\%ioctls], [qw(*ioctls)]) if (%ioctls); + print Data::Dumper->Dump([\%typedefs], [qw(*typedefs)]) if (%typedefs); + print Data::Dumper->Dump([\%enums], [qw(*enums)]) if (%enums); + print Data::Dumper->Dump([\%structs], [qw(*structs)]) if (%structs); + print Data::Dumper->Dump([\%defines], [qw(*defines)]) if (%defines); + print Data::Dumper->Dump([\%enum_symbols], [qw(*enum_symbols)]) if (%enum_symbols); +} + +# +# Align block +# +$data = expand($data); +$data = " " . $data; +$data =~ s/\n/\n /g; +$data =~ s/\n\s+$/\n/g; +$data =~ s/\n\s+\n/\n\n/g; + +# +# Add escape codes for special characters +# +$data =~ s,([\_\`\*\<\>\&\\\\:\/\|\%\$\#\{\}\~\^]),\\$1,g; + +$data =~ s,DEPRECATED,**DEPRECATED**,g; + +# +# Add references +# + +my $start_delim = "[ \n\t\(\=\*\@]"; +my $end_delim = "(\\s|,|\\\\=|\\\\:|\\;|\\\)|\\}|\\{)"; + +foreach my $r (keys %ioctls) { + my $s = $ioctls{$r}; + + $r =~ s,([\_\`\*\<\>\&\\\\:\/]),\\\\$1,g; + + print "$r -> $s\n" if ($debug); + + $data =~ s/($start_delim)($r)$end_delim/$1$s$3/g; +} + +foreach my $r (keys %defines) { + my $s = $defines{$r}; + + $r =~ s,([\_\`\*\<\>\&\\\\:\/]),\\\\$1,g; + + print "$r -> $s\n" if ($debug); + + $data =~ s/($start_delim)($r)$end_delim/$1$s$3/g; +} + +foreach my $r (keys %enum_symbols) { + my $s = $enum_symbols{$r}; + + $r =~ s,([\_\`\*\<\>\&\\\\:\/]),\\\\$1,g; + + print "$r -> $s\n" if ($debug); + + $data =~ s/($start_delim)($r)$end_delim/$1$s$3/g; +} + +foreach my $r (keys %enums) { + my $s = $enums{$r}; + + $r =~ s,([\_\`\*\<\>\&\\\\:\/]),\\\\$1,g; + + print "$r -> $s\n" if ($debug); + + $data =~ s/enum\s+($r)$end_delim/$s$2/g; +} + +foreach my $r (keys %structs) { + my $s = $structs{$r}; + + $r =~ s,([\_\`\*\<\>\&\\\\:\/]),\\\\$1,g; + + print "$r -> $s\n" if ($debug); + + $data =~ s/struct\s+($r)$end_delim/$s$2/g; +} + +foreach my $r (keys %typedefs) { + my $s = $typedefs{$r}; + + $r =~ s,([\_\`\*\<\>\&\\\\:\/]),\\\\$1,g; + + print "$r -> $s\n" if ($debug); + $data =~ s/($start_delim)($r)$end_delim/$1$s$3/g; +} + +$data =~ s/\\ ([\n\s])/\1/g; + +# +# Generate output file +# + +my $title = $file_in; +$title =~ s,.*/,,; + +open OUT, "> $file_out" or die "Can't open $file_out"; +print OUT ".. -*- coding: utf-8; mode: rst -*-\n\n"; +print OUT "$title\n"; +print OUT "=" x length($title); +print OUT "\n\n.. parsed-literal::\n\n"; +print OUT $data; +close OUT; + +__END__ + +=head1 NAME + +parse_headers.pl - parse a C file, in order to identify functions, structs, +enums and defines and create cross-references to a Sphinx book. + +=head1 SYNOPSIS + +B<parse_headers.pl> [<options>] <C_FILE> <OUT_FILE> [<EXCEPTIONS_FILE>] + +Where <options> can be: --debug, --help or --usage. + +=head1 OPTIONS + +=over 8 + +=item B<--debug> + +Put the script in verbose mode, useful for debugging. + +=item B<--usage> + +Prints a brief help message and exits. + +=item B<--help> + +Prints a more detailed help message and exits. + +=back + +=head1 DESCRIPTION + +Convert a C header or source file (C_FILE), into a ReStructured Text +included via ..parsed-literal block with cross-references for the +documentation files that describe the API. It accepts an optional +EXCEPTIONS_FILE with describes what elements will be either ignored or +be pointed to a non-default reference. + +The output is written at the (OUT_FILE). + +It is capable of identifying defines, functions, structs, typedefs, +enums and enum symbols and create cross-references for all of them. +It is also capable of distinguish #define used for specifying a Linux +ioctl. + +The EXCEPTIONS_FILE contain two rules to allow ignoring a symbol or +to replace the default references by a custom one. + +Please read Documentation/doc-guide/parse-headers.rst at the Kernel's +tree for more details. + +=head1 BUGS + +Report bugs to Mauro Carvalho Chehab <mchehab@kernel.org> + +=head1 COPYRIGHT + +Copyright (c) 2016 by Mauro Carvalho Chehab <mchehab+samsung@kernel.org>. + +License GPLv2: GNU GPL version 2 <https://gnu.org/licenses/gpl.html>. + +This is free software: you are free to change and redistribute it. +There is NO WARRANTY, to the extent permitted by law. + +=cut diff --git a/roms/u-boot/doc/sphinx/requirements.txt b/roms/u-boot/doc/sphinx/requirements.txt new file mode 100644 index 000000000..af79d2c11 --- /dev/null +++ b/roms/u-boot/doc/sphinx/requirements.txt @@ -0,0 +1,4 @@ +docutils==0.16 +Sphinx==2.4.4 +sphinx_rtd_theme +six diff --git a/roms/u-boot/doc/sphinx/rstFlatTable.py b/roms/u-boot/doc/sphinx/rstFlatTable.py new file mode 100755 index 000000000..2019a55f6 --- /dev/null +++ b/roms/u-boot/doc/sphinx/rstFlatTable.py @@ -0,0 +1,374 @@ +#!/usr/bin/env python3 +# -*- coding: utf-8; mode: python -*- +# pylint: disable=C0330, R0903, R0912 + +u""" + flat-table + ~~~~~~~~~~ + + Implementation of the ``flat-table`` reST-directive. + + :copyright: Copyright (C) 2016 Markus Heiser + :license: GPL Version 2, June 1991 see linux/COPYING for details. + + The ``flat-table`` (:py:class:`FlatTable`) is a double-stage list similar to + the ``list-table`` with some additional features: + + * *column-span*: with the role ``cspan`` a cell can be extended through + additional columns + + * *row-span*: with the role ``rspan`` a cell can be extended through + additional rows + + * *auto span* rightmost cell of a table row over the missing cells on the + right side of that table-row. With Option ``:fill-cells:`` this behavior + can changed from *auto span* to *auto fill*, which automaticly inserts + (empty) cells instead of spanning the last cell. + + Options: + + * header-rows: [int] count of header rows + * stub-columns: [int] count of stub columns + * widths: [[int] [int] ... ] widths of columns + * fill-cells: instead of autospann missing cells, insert missing cells + + roles: + + * cspan: [int] additionale columns (*morecols*) + * rspan: [int] additionale rows (*morerows*) +""" + +# ============================================================================== +# imports +# ============================================================================== + +import sys + +from docutils import nodes +from docutils.parsers.rst import directives, roles +from docutils.parsers.rst.directives.tables import Table +from docutils.utils import SystemMessagePropagation + +# ============================================================================== +# common globals +# ============================================================================== + +__version__ = '1.0' + +PY3 = sys.version_info[0] == 3 +PY2 = sys.version_info[0] == 2 + +if PY3: + # pylint: disable=C0103, W0622 + unicode = str + basestring = str + +# ============================================================================== +def setup(app): +# ============================================================================== + + app.add_directive("flat-table", FlatTable) + roles.register_local_role('cspan', c_span) + roles.register_local_role('rspan', r_span) + + return dict( + version = __version__, + parallel_read_safe = True, + parallel_write_safe = True + ) + +# ============================================================================== +def c_span(name, rawtext, text, lineno, inliner, options=None, content=None): +# ============================================================================== + # pylint: disable=W0613 + + options = options if options is not None else {} + content = content if content is not None else [] + nodelist = [colSpan(span=int(text))] + msglist = [] + return nodelist, msglist + +# ============================================================================== +def r_span(name, rawtext, text, lineno, inliner, options=None, content=None): +# ============================================================================== + # pylint: disable=W0613 + + options = options if options is not None else {} + content = content if content is not None else [] + nodelist = [rowSpan(span=int(text))] + msglist = [] + return nodelist, msglist + + +# ============================================================================== +class rowSpan(nodes.General, nodes.Element): pass # pylint: disable=C0103,C0321 +class colSpan(nodes.General, nodes.Element): pass # pylint: disable=C0103,C0321 +# ============================================================================== + +# ============================================================================== +class FlatTable(Table): +# ============================================================================== + + u"""FlatTable (``flat-table``) directive""" + + option_spec = { + 'name': directives.unchanged + , 'class': directives.class_option + , 'header-rows': directives.nonnegative_int + , 'stub-columns': directives.nonnegative_int + , 'widths': directives.positive_int_list + , 'fill-cells' : directives.flag } + + def run(self): + + if not self.content: + error = self.state_machine.reporter.error( + 'The "%s" directive is empty; content required.' % self.name, + nodes.literal_block(self.block_text, self.block_text), + line=self.lineno) + return [error] + + title, messages = self.make_title() + node = nodes.Element() # anonymous container for parsing + self.state.nested_parse(self.content, self.content_offset, node) + + tableBuilder = ListTableBuilder(self) + tableBuilder.parseFlatTableNode(node) + tableNode = tableBuilder.buildTableNode() + # SDK.CONSOLE() # print --> tableNode.asdom().toprettyxml() + if title: + tableNode.insert(0, title) + return [tableNode] + messages + + +# ============================================================================== +class ListTableBuilder(object): +# ============================================================================== + + u"""Builds a table from a double-stage list""" + + def __init__(self, directive): + self.directive = directive + self.rows = [] + self.max_cols = 0 + + def buildTableNode(self): + + colwidths = self.directive.get_column_widths(self.max_cols) + if isinstance(colwidths, tuple): + # Since docutils 0.13, get_column_widths returns a (widths, + # colwidths) tuple, where widths is a string (i.e. 'auto'). + # See https://sourceforge.net/p/docutils/patches/120/. + colwidths = colwidths[1] + stub_columns = self.directive.options.get('stub-columns', 0) + header_rows = self.directive.options.get('header-rows', 0) + + table = nodes.table() + tgroup = nodes.tgroup(cols=len(colwidths)) + table += tgroup + + + for colwidth in colwidths: + colspec = nodes.colspec(colwidth=colwidth) + # FIXME: It seems, that the stub method only works well in the + # absence of rowspan (observed by the html buidler, the docutils-xml + # build seems OK). This is not extraordinary, because there exists + # no table directive (except *this* flat-table) which allows to + # define coexistent of rowspan and stubs (there was no use-case + # before flat-table). This should be reviewed (later). + if stub_columns: + colspec.attributes['stub'] = 1 + stub_columns -= 1 + tgroup += colspec + stub_columns = self.directive.options.get('stub-columns', 0) + + if header_rows: + thead = nodes.thead() + tgroup += thead + for row in self.rows[:header_rows]: + thead += self.buildTableRowNode(row) + + tbody = nodes.tbody() + tgroup += tbody + + for row in self.rows[header_rows:]: + tbody += self.buildTableRowNode(row) + return table + + def buildTableRowNode(self, row_data, classes=None): + classes = [] if classes is None else classes + row = nodes.row() + for cell in row_data: + if cell is None: + continue + cspan, rspan, cellElements = cell + + attributes = {"classes" : classes} + if rspan: + attributes['morerows'] = rspan + if cspan: + attributes['morecols'] = cspan + entry = nodes.entry(**attributes) + entry.extend(cellElements) + row += entry + return row + + def raiseError(self, msg): + error = self.directive.state_machine.reporter.error( + msg + , nodes.literal_block(self.directive.block_text + , self.directive.block_text) + , line = self.directive.lineno ) + raise SystemMessagePropagation(error) + + def parseFlatTableNode(self, node): + u"""parses the node from a :py:class:`FlatTable` directive's body""" + + if len(node) != 1 or not isinstance(node[0], nodes.bullet_list): + self.raiseError( + 'Error parsing content block for the "%s" directive: ' + 'exactly one bullet list expected.' % self.directive.name ) + + for rowNum, rowItem in enumerate(node[0]): + row = self.parseRowItem(rowItem, rowNum) + self.rows.append(row) + self.roundOffTableDefinition() + + def roundOffTableDefinition(self): + u"""Round off the table definition. + + This method rounds off the table definition in :py:member:`rows`. + + * This method inserts the needed ``None`` values for the missing cells + arising from spanning cells over rows and/or columns. + + * recount the :py:member:`max_cols` + + * Autospan or fill (option ``fill-cells``) missing cells on the right + side of the table-row + """ + + y = 0 + while y < len(self.rows): + x = 0 + + while x < len(self.rows[y]): + cell = self.rows[y][x] + if cell is None: + x += 1 + continue + cspan, rspan = cell[:2] + # handle colspan in current row + for c in range(cspan): + try: + self.rows[y].insert(x+c+1, None) + except: # pylint: disable=W0702 + # the user sets ambiguous rowspans + pass # SDK.CONSOLE() + # handle colspan in spanned rows + for r in range(rspan): + for c in range(cspan + 1): + try: + self.rows[y+r+1].insert(x+c, None) + except: # pylint: disable=W0702 + # the user sets ambiguous rowspans + pass # SDK.CONSOLE() + x += 1 + y += 1 + + # Insert the missing cells on the right side. For this, first + # re-calculate the max columns. + + for row in self.rows: + if self.max_cols < len(row): + self.max_cols = len(row) + + # fill with empty cells or cellspan? + + fill_cells = False + if 'fill-cells' in self.directive.options: + fill_cells = True + + for row in self.rows: + x = self.max_cols - len(row) + if x and not fill_cells: + if row[-1] is None: + row.append( ( x - 1, 0, []) ) + else: + cspan, rspan, content = row[-1] + row[-1] = (cspan + x, rspan, content) + elif x and fill_cells: + for i in range(x): + row.append( (0, 0, nodes.comment()) ) + + def pprint(self): + # for debugging + retVal = "[ " + for row in self.rows: + retVal += "[ " + for col in row: + if col is None: + retVal += ('%r' % col) + retVal += "\n , " + else: + content = col[2][0].astext() + if len (content) > 30: + content = content[:30] + "..." + retVal += ('(cspan=%s, rspan=%s, %r)' + % (col[0], col[1], content)) + retVal += "]\n , " + retVal = retVal[:-2] + retVal += "]\n , " + retVal = retVal[:-2] + return retVal + "]" + + def parseRowItem(self, rowItem, rowNum): + row = [] + childNo = 0 + error = False + cell = None + target = None + + for child in rowItem: + if (isinstance(child , nodes.comment) + or isinstance(child, nodes.system_message)): + pass + elif isinstance(child , nodes.target): + target = child + elif isinstance(child, nodes.bullet_list): + childNo += 1 + cell = child + else: + error = True + break + + if childNo != 1 or error: + self.raiseError( + 'Error parsing content block for the "%s" directive: ' + 'two-level bullet list expected, but row %s does not ' + 'contain a second-level bullet list.' + % (self.directive.name, rowNum + 1)) + + for cellItem in cell: + cspan, rspan, cellElements = self.parseCellItem(cellItem) + if target is not None: + cellElements.insert(0, target) + row.append( (cspan, rspan, cellElements) ) + return row + + def parseCellItem(self, cellItem): + # search and remove cspan, rspan colspec from the first element in + # this listItem (field). + cspan = rspan = 0 + if not len(cellItem): + return cspan, rspan, [] + for elem in cellItem[0]: + if isinstance(elem, colSpan): + cspan = elem.get("span") + elem.parent.remove(elem) + continue + if isinstance(elem, rowSpan): + rspan = elem.get("span") + elem.parent.remove(elem) + continue + return cspan, rspan, cellItem[:] diff --git a/roms/u-boot/doc/uImage.FIT/beaglebone_vboot.txt b/roms/u-boot/doc/uImage.FIT/beaglebone_vboot.txt new file mode 100644 index 000000000..ebd2068ed --- /dev/null +++ b/roms/u-boot/doc/uImage.FIT/beaglebone_vboot.txt @@ -0,0 +1,607 @@ +Verified Boot on the Beaglebone Black +===================================== + +Introduction +------------ + +Before reading this, please read verified-boot.txt and signature.txt. These +instructions are for mainline U-Boot from v2014.07 onwards. + +There is quite a bit of documentation in this directory describing how +verified boot works in U-Boot. There is also a test which runs through the +entire process of signing an image and running U-Boot (sandbox) to check it. +However, it might be useful to also have an example on a real board. + +Beaglebone Black is a fairly common board so seems to be a reasonable choice +for an example of how to enable verified boot using U-Boot. + +First a note that may to help avoid confusion. U-Boot and Linux both use +device tree. They may use the same device tree source, but it is seldom useful +for them to use the exact same binary from the same place. More typically, +U-Boot has its device tree packaged wtih it, and the kernel's device tree is +packaged with the kernel. In particular this is important with verified boot, +since U-Boot's device tree must be immutable. If it can be changed then the +public keys can be changed and verified boot is useless. An attacker can +simply generate a new key and put his public key into U-Boot so that +everything verifies. On the other hand the kernel's device tree typically +changes when the kernel changes, so it is useful to package an updated device +tree with the kernel binary. U-Boot supports the latter with its flexible FIT +format (Flat Image Tree). + + +Overview +-------- + +The steps are roughly as follows: + +1. Build U-Boot for the board, with the verified boot options enabled. + +2. Obtain a suitable Linux kernel + +3. Create a Image Tree Source file (ITS) file describing how you want the +kernel to be packaged, compressed and signed. + +4. Create a key pair + +5. Sign the kernel + +6. Put the public key into U-Boot's image + +7. Put U-Boot and the kernel onto the board + +8. Try it + + +Step 1: Build U-Boot +-------------------- + +a. Set up the environment variable to point to your toolchain. You will need +this for U-Boot and also for the kernel if you build it. For example if you +installed a Linaro version manually it might be something like: + + export CROSS_COMPILE=/opt/linaro/gcc-linaro-arm-linux-gnueabihf-4.8-2013.08_linux/bin/arm-linux-gnueabihf- + +or if you just installed gcc-arm-linux-gnueabi then it might be + + export CROSS_COMPILE=arm-linux-gnueabi- + +b. Configure and build U-Boot with verified boot enabled: + + export UBOOT=/path/to/u-boot + cd $UBOOT + # You can add -j10 if you have 10 CPUs to make it faster + make O=b/am335x_boneblack_vboot am335x_boneblack_vboot_config all + export UOUT=$UBOOT/b/am335x_boneblack_vboot + +c. You will now have a U-Boot image: + + file b/am335x_boneblack_vboot/u-boot-dtb.img +b/am335x_boneblack_vboot/u-boot-dtb.img: u-boot legacy uImage, U-Boot 2014.07-rc2-00065-g2f69f8, Firmware/ARM, Firmware Image (Not compressed), 395375 bytes, Sat May 31 16:19:04 2014, Load Address: 0x80800000, Entry Point: 0x00000000, Header CRC: 0x0ABD6ACA, Data CRC: 0x36DEF7E4 + + +Step 2: Build Linux +-------------------- + +a. Find the kernel image ('Image') and device tree (.dtb) file you plan to +use. In our case it is am335x-boneblack.dtb and it is built with the kernel. +At the time of writing an SD Boot image can be obtained from here: + + http://www.elinux.org/Beagleboard:Updating_The_Software#Image_For_Booting_From_microSD + +You can write this to an SD card and then mount it to extract the kernel and +device tree files. + +You can also build a kernel. Instructions for this are are here: + + http://elinux.org/Building_BBB_Kernel + +or you can use your favourite search engine. Following these instructions +produces a kernel Image and device tree files. For the record the steps were: + + export KERNEL=/path/to/kernel + cd $KERNEL + git clone git://github.com/beagleboard/kernel.git . + git checkout v3.14 + ./patch.sh + cp configs/beaglebone kernel/arch/arm/configs/beaglebone_defconfig + cd kernel + make beaglebone_defconfig + make uImage dtbs # -j10 if you have 10 CPUs + export OKERNEL=$KERNEL/kernel/arch/arm/boot + +c. You now have the 'Image' and 'am335x-boneblack.dtb' files needed to boot. + + +Step 3: Create the ITS +---------------------- + +Set up a directory for your work. + + export WORK=/path/to/dir + cd $WORK + +Put this into a file in that directory called sign.its: + +/dts-v1/; + +/ { + description = "Beaglebone black"; + #address-cells = <1>; + + images { + kernel { + data = /incbin/("Image.lzo"); + type = "kernel"; + arch = "arm"; + os = "linux"; + compression = "lzo"; + load = <0x80008000>; + entry = <0x80008000>; + hash-1 { + algo = "sha1"; + }; + }; + fdt-1 { + description = "beaglebone-black"; + data = /incbin/("am335x-boneblack.dtb"); + type = "flat_dt"; + arch = "arm"; + compression = "none"; + hash-1 { + algo = "sha1"; + }; + }; + }; + configurations { + default = "conf-1"; + conf-1 { + kernel = "kernel"; + fdt = "fdt-1"; + signature-1 { + algo = "sha1,rsa2048"; + key-name-hint = "dev"; + sign-images = "fdt", "kernel"; + }; + }; + }; +}; + + +The explanation for this is all in the documentation you have already read. +But briefly it packages a kernel and device tree, and provides a single +configuration to be signed with a key named 'dev'. The kernel is compressed +with LZO to make it smaller. + + +Step 4: Create a key pair +------------------------- + +See signature.txt for details on this step. + + cd $WORK + mkdir keys + openssl genrsa -F4 -out keys/dev.key 2048 + openssl req -batch -new -x509 -key keys/dev.key -out keys/dev.crt + +Note: keys/dev.key contains your private key and is very secret. If anyone +gets access to that file they can sign kernels with it. Keep it secure. + + +Step 5: Sign the kernel +----------------------- + +We need to use mkimage (which was built when you built U-Boot) to package the +Linux kernel into a FIT (Flat Image Tree, a flexible file format that U-Boot +can load) using the ITS file you just created. + +At the same time we must put the public key into U-Boot device tree, with the +'required' property, which tells U-Boot that this key must be verified for the +image to be valid. You will make this key available to U-Boot for booting in +step 6. + + ln -s $OKERNEL/dts/am335x-boneblack.dtb + ln -s $OKERNEL/Image + ln -s $UOUT/u-boot-dtb.img + cp $UOUT/arch/arm/dts/am335x-boneblack.dtb am335x-boneblack-pubkey.dtb + lzop Image + $UOUT/tools/mkimage -f sign.its -K am335x-boneblack-pubkey.dtb -k keys -r image.fit + +You should see something like this: + +FIT description: Beaglebone black +Created: Sun Jun 1 12:50:30 2014 + Image 0 (kernel) + Description: unavailable + Created: Sun Jun 1 12:50:30 2014 + Type: Kernel Image + Compression: lzo compressed + Data Size: 7790938 Bytes = 7608.34 kB = 7.43 MB + Architecture: ARM + OS: Linux + Load Address: 0x80008000 + Entry Point: 0x80008000 + Hash algo: sha1 + Hash value: c94364646427e10f423837e559898ef02c97b988 + Image 1 (fdt-1) + Description: beaglebone-black + Created: Sun Jun 1 12:50:30 2014 + Type: Flat Device Tree + Compression: uncompressed + Data Size: 31547 Bytes = 30.81 kB = 0.03 MB + Architecture: ARM + Hash algo: sha1 + Hash value: cb09202f889d824f23b8e4404b781be5ad38a68d + Default Configuration: 'conf-1' + Configuration 0 (conf-1) + Description: unavailable + Kernel: kernel + FDT: fdt-1 + + +Now am335x-boneblack-pubkey.dtb contains the public key and image.fit contains +the signed kernel. Jump to step 6 if you like, or continue reading to increase +your understanding. + +You can also run fit_check_sign to check it: + + $UOUT/tools/fit_check_sign -f image.fit -k am335x-boneblack-pubkey.dtb + +which results in: + +Verifying Hash Integrity ... sha1,rsa2048:dev+ +## Loading kernel from FIT Image at 7fc6ee469000 ... + Using 'conf-1' configuration + Verifying Hash Integrity ... +sha1,rsa2048:dev+ +OK + + Trying 'kernel' kernel subimage + Description: unavailable + Created: Sun Jun 1 12:50:30 2014 + Type: Kernel Image + Compression: lzo compressed + Data Size: 7790938 Bytes = 7608.34 kB = 7.43 MB + Architecture: ARM + OS: Linux + Load Address: 0x80008000 + Entry Point: 0x80008000 + Hash algo: sha1 + Hash value: c94364646427e10f423837e559898ef02c97b988 + Verifying Hash Integrity ... +sha1+ +OK + +Unimplemented compression type 4 +## Loading fdt from FIT Image at 7fc6ee469000 ... + Using 'conf-1' configuration + Trying 'fdt-1' fdt subimage + Description: beaglebone-black + Created: Sun Jun 1 12:50:30 2014 + Type: Flat Device Tree + Compression: uncompressed + Data Size: 31547 Bytes = 30.81 kB = 0.03 MB + Architecture: ARM + Hash algo: sha1 + Hash value: cb09202f889d824f23b8e4404b781be5ad38a68d + Verifying Hash Integrity ... +sha1+ +OK + + Loading Flat Device Tree ... OK + +## Loading ramdisk from FIT Image at 7fc6ee469000 ... + Using 'conf-1' configuration +Could not find subimage node + +Signature check OK + + +At the top, you see "sha1,rsa2048:dev+". This means that it checked an RSA key +of size 2048 bits using SHA1 as the hash algorithm. The key name checked was +'dev' and the '+' means that it verified. If it showed '-' that would be bad. + +Once the configuration is verified it is then possible to rely on the hashes +in each image referenced by that configuration. So fit_check_sign goes on to +load each of the images. We have a kernel and an FDT but no ramkdisk. In each +case fit_check_sign checks the hash and prints sha1+ meaning that the SHA1 +hash verified. This means that none of the images has been tampered with. + +There is a test in test/vboot which uses U-Boot's sandbox build to verify that +the above flow works. + +But it is fun to do this by hand, so you can load image.fit into a hex editor +like ghex, and change a byte in the kernel: + + $UOUT/tools/fit_info -f image.fit -n /images/kernel -p data +NAME: kernel +LEN: 7790938 +OFF: 168 + +This tells us that the kernel starts at byte offset 168 (decimal) in image.fit +and extends for about 7MB. Try changing a byte at 0x2000 (say) and run +fit_check_sign again. You should see something like: + +Verifying Hash Integrity ... sha1,rsa2048:dev+ +## Loading kernel from FIT Image at 7f5a39571000 ... + Using 'conf-1' configuration + Verifying Hash Integrity ... +sha1,rsa2048:dev+ +OK + + Trying 'kernel' kernel subimage + Description: unavailable + Created: Sun Jun 1 13:09:21 2014 + Type: Kernel Image + Compression: lzo compressed + Data Size: 7790938 Bytes = 7608.34 kB = 7.43 MB + Architecture: ARM + OS: Linux + Load Address: 0x80008000 + Entry Point: 0x80008000 + Hash algo: sha1 + Hash value: c94364646427e10f423837e559898ef02c97b988 + Verifying Hash Integrity ... +sha1 error +Bad hash value for 'hash-1' hash node in 'kernel' image node +Bad Data Hash + +## Loading fdt from FIT Image at 7f5a39571000 ... + Using 'conf-1' configuration + Trying 'fdt-1' fdt subimage + Description: beaglebone-black + Created: Sun Jun 1 13:09:21 2014 + Type: Flat Device Tree + Compression: uncompressed + Data Size: 31547 Bytes = 30.81 kB = 0.03 MB + Architecture: ARM + Hash algo: sha1 + Hash value: cb09202f889d824f23b8e4404b781be5ad38a68d + Verifying Hash Integrity ... +sha1+ +OK + + Loading Flat Device Tree ... OK + +## Loading ramdisk from FIT Image at 7f5a39571000 ... + Using 'conf-1' configuration +Could not find subimage node + +Signature check Bad (error 1) + + +It has detected the change in the kernel. + +You can also be sneaky and try to switch images, using the libfdt utilities +that come with dtc (package name is device-tree-compiler but you will need a +recent version like 1.4: + + dtc -v +Version: DTC 1.4.0 + +First we can check which nodes are actually hashed by the configuration: + + fdtget -l image.fit / +images +configurations + + fdtget -l image.fit /configurations +conf-1 +fdtget -l image.fit /configurations/conf-1 +signature-1 + + fdtget -p image.fit /configurations/conf-1/signature-1 +hashed-strings +hashed-nodes +timestamp +signer-version +signer-name +value +algo +key-name-hint +sign-images + + fdtget image.fit /configurations/conf-1/signature-1 hashed-nodes +/ /configurations/conf-1 /images/fdt-1 /images/fdt-1/hash /images/kernel /images/kernel/hash-1 + +This gives us a bit of a look into the signature that mkimage added. Note you +can also use fdtdump to list the entire device tree. + +Say we want to change the kernel that this configuration uses +(/images/kernel). We could just put a new kernel in the image, but we will +need to change the hash to match. Let's simulate that by changing a byte of +the hash: + + fdtget -tx image.fit /images/kernel/hash-1 value +c9436464 6427e10f 423837e5 59898ef0 2c97b988 + fdtput -tx image.fit /images/kernel/hash-1 value c9436464 6427e10f 423837e5 59898ef0 2c97b981 + +Now check it again: + + $UOUT/tools/fit_check_sign -f image.fit -k am335x-boneblack-pubkey.dtb +Verifying Hash Integrity ... sha1,rsa2048:devrsa_verify_with_keynode: RSA failed to verify: -13 +rsa_verify_with_keynode: RSA failed to verify: -13 +- +Failed to verify required signature 'key-dev' +Signature check Bad (error 1) + +This time we don't even get as far as checking the images, since the +configuration signature doesn't match. We can't change any hashes without the +signature check noticing. The configuration is essentially locked. U-Boot has +a public key for which it requires a match, and will not permit the use of any +configuration that does not match that public key. The only way the +configuration will match is if it was signed by the matching private key. + +It would also be possible to add a new signature node that does match your new +configuration. But that won't work since you are not allowed to change the +configuration in any way. Try it with a fresh (valid) image if you like by +running the mkimage link again. Then: + + fdtput -p image.fit /configurations/conf-1/signature-1 value fred + $UOUT/tools/fit_check_sign -f image.fit -k am335x-boneblack-pubkey.dtb +Verifying Hash Integrity ... - +sha1,rsa2048:devrsa_verify_with_keynode: RSA failed to verify: -13 +rsa_verify_with_keynode: RSA failed to verify: -13 +- +Failed to verify required signature 'key-dev' +Signature check Bad (error 1) + + +Of course it would be possible to add an entirely new configuration and boot +with that, but it still needs to be signed, so it won't help. + + +6. Put the public key into U-Boot's image +----------------------------------------- + +Having confirmed that the signature is doing its job, let's try it out in +U-Boot on the board. U-Boot needs access to the public key corresponding to +the private key that you signed with so that it can verify any kernels that +you sign. + + cd $UBOOT + make O=b/am335x_boneblack_vboot EXT_DTB=${WORK}/am335x-boneblack-pubkey.dtb + +Here we are overriding the normal device tree file with our one, which +contains the public key. + +Now you have a special U-Boot image with the public key. It can verify can +kernel that you sign with the private key as in step 5. + +If you like you can take a look at the public key information that mkimage +added to U-Boot's device tree: + + fdtget -p am335x-boneblack-pubkey.dtb /signature/key-dev +required +algo +rsa,r-squared +rsa,modulus +rsa,n0-inverse +rsa,num-bits +key-name-hint + +This has information about the key and some pre-processed values which U-Boot +can use to verify against it. These values are obtained from the public key +certificate by mkimage, but require quite a bit of code to generate. To save +code space in U-Boot, the information is extracted and written in raw form for +U-Boot to easily use. The same mechanism is used in Google's Chrome OS. + +Notice the 'required' property. This marks the key as required - U-Boot will +not boot any image that does not verify against this key. + + +7. Put U-Boot and the kernel onto the board +------------------------------------------- + +The method here varies depending on how you are booting. For this example we +are booting from an micro-SD card with two partitions, one for U-Boot and one +for Linux. Put it into your machine and write U-Boot and the kernel to it. +Here the card is /dev/sde: + + cd $WORK + export UDEV=/dev/sde1 # Change thes two lines to the correct device + export KDEV=/dev/sde2 + sudo mount $UDEV /mnt/tmp && sudo cp $UOUT/u-boot-dtb.img /mnt/tmp/u-boot.img && sleep 1 && sudo umount $UDEV + sudo mount $KDEV /mnt/tmp && sudo cp $WORK/image.fit /mnt/tmp/boot/image.fit && sleep 1 && sudo umount $KDEV + + +8. Try it +--------- + +Boot the board using the commands below: + + setenv bootargs console=ttyO0,115200n8 quiet root=/dev/mmcblk0p2 ro rootfstype=ext4 rootwait + ext2load mmc 0:2 82000000 /boot/image.fit + bootm 82000000 + +You should then see something like this: + +U-Boot# setenv bootargs console=ttyO0,115200n8 quiet root=/dev/mmcblk0p2 ro rootfstype=ext4 rootwait +U-Boot# ext2load mmc 0:2 82000000 /boot/image.fit +7824930 bytes read in 589 ms (12.7 MiB/s) +U-Boot# bootm 82000000 +## Loading kernel from FIT Image at 82000000 ... + Using 'conf-1' configuration + Verifying Hash Integrity ... sha1,rsa2048:dev+ OK + Trying 'kernel' kernel subimage + Description: unavailable + Created: 2014-06-01 19:32:54 UTC + Type: Kernel Image + Compression: lzo compressed + Data Start: 0x820000a8 + Data Size: 7790938 Bytes = 7.4 MiB + Architecture: ARM + OS: Linux + Load Address: 0x80008000 + Entry Point: 0x80008000 + Hash algo: sha1 + Hash value: c94364646427e10f423837e559898ef02c97b988 + Verifying Hash Integrity ... sha1+ OK +## Loading fdt from FIT Image at 82000000 ... + Using 'conf-1' configuration + Trying 'fdt-1' fdt subimage + Description: beaglebone-black + Created: 2014-06-01 19:32:54 UTC + Type: Flat Device Tree + Compression: uncompressed + Data Start: 0x8276e2ec + Data Size: 31547 Bytes = 30.8 KiB + Architecture: ARM + Hash algo: sha1 + Hash value: cb09202f889d824f23b8e4404b781be5ad38a68d + Verifying Hash Integrity ... sha1+ OK + Booting using the fdt blob at 0x8276e2ec + Uncompressing Kernel Image ... OK + Loading Device Tree to 8fff5000, end 8ffffb3a ... OK + +Starting kernel ... + +[ 0.582377] omap_init_mbox: hwmod doesn't have valid attrs +[ 2.589651] musb-hdrc musb-hdrc.0.auto: Failed to request rx1. +[ 2.595830] musb-hdrc musb-hdrc.0.auto: musb_init_controller failed with status -517 +[ 2.606470] musb-hdrc musb-hdrc.1.auto: Failed to request rx1. +[ 2.612723] musb-hdrc musb-hdrc.1.auto: musb_init_controller failed with status -517 +[ 2.940808] drivers/rtc/hctosys.c: unable to open rtc device (rtc0) +[ 7.248889] libphy: PHY 4a101000.mdio:01 not found +[ 7.253995] net eth0: phy 4a101000.mdio:01 not found on slave 1 +systemd-fsck[83]: Angstrom: clean, 50607/218160 files, 306348/872448 blocks + +.---O---. +| | .-. o o +| | |-----.-----.-----.| | .----..-----.-----. +| | | __ | ---'| '--.| .-'| | | +| | | | | |--- || --'| | | ' | | | | +'---'---'--'--'--. |-----''----''--' '-----'-'-'-' + -' | + '---' + +The Angstrom Distribution beaglebone ttyO0 + +Angstrom v2012.12 - Kernel 3.14.1+ + +beaglebone login: + +At this point your kernel has been verified and you can be sure that it is one +that you signed. As an exercise, try changing image.fit as in step 5 and see +what happens. + + +Further Improvements +-------------------- + +Several of the steps here can be easily automated. In particular it would be +capital if signing and packaging a kernel were easy, perhaps a simple make +target in the kernel. + +Some mention of how to use multiple .dtb files in a FIT might be useful. + +U-Boot's verified boot mechanism has not had a robust and independent security +review. Such a review should look at the implementation and its resistance to +attacks. + +Perhaps the verified boot feature could could be integrated into the Amstrom +distribution. + + +Simon Glass +sjg@chromium.org +2-June-14 diff --git a/roms/u-boot/doc/uImage.FIT/command_syntax_extensions.txt b/roms/u-boot/doc/uImage.FIT/command_syntax_extensions.txt new file mode 100644 index 000000000..6a99089ab --- /dev/null +++ b/roms/u-boot/doc/uImage.FIT/command_syntax_extensions.txt @@ -0,0 +1,201 @@ +Command syntax extensions for the new uImage format +=================================================== + +Author: Bartlomiej Sieka <tur@semihalf.com> + +With the introduction of the new uImage format, bootm command (and other +commands as well) have to understand new syntax of the arguments. This is +necessary in order to specify objects contained in the new uImage, on which +bootm has to operate. This note attempts to first summarize bootm usage +scenarios, and then introduces new argument syntax. + + +bootm usage scenarios +--------------------- + +Below is a summary of bootm usage scenarios, focused on booting a PowerPC +Linux kernel. The purpose of the following list is to document a complete list +of supported bootm usages. + +Note: U-Boot supports two methods of booting a PowerPC Linux kernel: old way, +i.e., without passing the Flattened Device Tree (FDT), and new way, where the +kernel is passed a pointer to the FDT. The boot method is indicated for each +scenario. + + +1. bootm boot image at the current address, equivalent to 2,3,8 + +Old uImage: +2. bootm <addr1> /* single image at <addr1> */ +3. bootm <addr1> /* multi-image at <addr1> */ +4. bootm <addr1> - /* multi-image at <addr1> */ +5. bootm <addr1> <addr2> /* single image at <addr1> */ +6. bootm <addr1> <addr2> <addr3> /* single image at <addr1> */ +7. bootm <addr1> - <addr3> /* single image at <addr1> */ + +New uImage: +8. bootm <addr1> +9. bootm [<addr1>]:<subimg1> +10. bootm [<addr1>]#<conf>[#<extra-conf[#...]] +11. bootm [<addr1>]:<subimg1> [<addr2>]:<subimg2> +12. bootm [<addr1>]:<subimg1> [<addr2>]:<subimg2> [<addr3>]:<subimg3> +13. bootm [<addr1>]:<subimg1> [<addr2>]:<subimg2> <addr3> +14. bootm [<addr1>]:<subimg1> - [<addr3>]:<subimg3> +15. bootm [<addr1>]:<subimg1> - <addr3> + + +Ad. 1. This is equivalent to cases 2,3,8, depending on the type of image at +the current image address. +- boot method: see cases 2,3,8 + +Ad. 2. Boot kernel image located at <addr1>. +- boot method: non-FDT + +Ad. 3. First and second components of the image at <addr1> are assumed to be a +kernel and a ramdisk, respectively. The kernel is booted with initrd loaded +with the ramdisk from the image. +- boot method: depends on the number of components at <addr1>, and on whether + U-Boot is compiled with OF support: + + | 2 components | 3 components | + | (kernel, initrd) | (kernel, initrd, fdt) | +--------------------------------------------------------------------- +#ifdef CONFIG_OF_* | non-FDT | FDT | +#ifndef CONFIG_OF_* | non-FDT | non-FDT | + +Ad. 4. Similar to case 3, but the kernel is booted without initrd. Second +component of the multi-image is irrelevant (it can be a dummy, 1-byte file). +- boot method: see case 3 + +Ad. 5. Boot kernel image located at <addr1> with initrd loaded with ramdisk +from the image at <addr2>. +- boot method: non-FDT + +Ad. 6. <addr1> is the address of a kernel image, <addr2> is the address of a +ramdisk image, and <addr3> is the address of a FDT binary blob. Kernel is +booted with initrd loaded with ramdisk from the image at <addr2>. +- boot method: FDT + +Ad. 7. <addr1> is the address of a kernel image and <addr3> is the address of +a FDT binary blob. Kernel is booted without initrd. +- boot method: FDT + +Ad. 8. Image at <addr1> is assumed to contain a default configuration, which +is booted. +- boot method: FDT or non-FDT, depending on whether the default configuration + defines FDT + +Ad. 9. Similar to case 2: boot kernel stored in <subimg1> from the image at +address <addr1>. +- boot method: non-FDT + +Ad. 10. Boot configuration <conf> from the image at <addr1>. +- boot method: FDT or non-FDT, depending on whether the configuration given + defines FDT + +Ad. 11. Equivalent to case 5: boot kernel stored in <subimg1> from the image +at <addr1> with initrd loaded with ramdisk <subimg2> from the image at +<addr2>. +- boot method: non-FDT + +Ad. 12. Equivalent to case 6: boot kernel stored in <subimg1> from the image +at <addr1> with initrd loaded with ramdisk <subimg2> from the image at +<addr2>, and pass FDT blob <subimg3> from the image at <addr3>. +- boot method: FDT + +Ad. 13. Similar to case 12, the difference being that <addr3> is the address +of FDT binary blob that is to be passed to the kernel. +- boot method: FDT + +Ad. 14. Equivalent to case 7: boot kernel stored in <subimg1> from the image +at <addr1>, without initrd, and pass FDT blob <subimg3> from the image at +<addr3>. +- boot method: FDT + +Ad. 15. Similar to case 14, the difference being that <addr3> is the address +of the FDT binary blob that is to be passed to the kernel. +- boot method: FDT + + +New uImage argument syntax +-------------------------- + +New uImage support introduces two new forms for bootm arguments, with the +following syntax: + +- new uImage sub-image specification +<addr>:<sub-image unit_name> + +- new uImage configuration specification +<addr>#<configuration unit_name> + +- new uImage configuration specification with extra configuration components +<addr>#<configuration unit_name>[#<extra configuration unit_name>[#..]] + +The extra configuration currently is supported only for additional device tree +overlays to apply on the base device tree supplied by the first configuration +unit. + +Examples: + +- boot kernel "kernel-1" stored in a new uImage located at 200000: +bootm 200000:kernel-1 + +- boot configuration "cfg-1" from a new uImage located at 200000: +bootm 200000#cfg-1 + +- boot configuration "cfg-1" with extra "cfg-2" from a new uImage located + at 200000: +bootm 200000#cfg-1#cfg-2 + +- boot "kernel-1" from a new uImage at 200000 with initrd "ramdisk-2" found in + some other new uImage stored at address 800000: +bootm 200000:kernel-1 800000:ramdisk-2 + +- boot "kernel-2" from a new uImage at 200000, with initrd "ramdisk-1" and FDT + "fdt-1", both stored in some other new uImage located at 800000: +bootm 200000:kernel-1 800000:ramdisk-1 800000:fdt-1 + +- boot kernel "kernel-2" with initrd "ramdisk-2", both stored in a new uImage + at address 200000, with a raw FDT blob stored at address 600000: +bootm 200000:kernel-2 200000:ramdisk-2 600000 + +- boot kernel "kernel-2" from new uImage at 200000 with FDT "fdt-1" from the + same new uImage: +bootm 200000:kernel-2 - 200000:fdt-1 + + +Note on current image address +----------------------------- + +When bootm is called without arguments, the image at current image address is +booted. The current image address is the address set most recently by a load +command, etc, and is by default equal to CONFIG_SYS_LOAD_ADDR. For example, consider +the following commands: + +tftp 200000 /tftpboot/kernel +bootm +Last command is equivalent to: +bootm 200000 + +In case of the new uImage argument syntax, the address portion of any argument +can be omitted. If <addr3> is omitted, then it is assumed that image at +<addr2> should be used. Similarly, when <addr2> is omitted, it is assumed that +image at <addr1> should be used. If <addr1> is omitted, it is assumed that the +current image address is to be used. For example, consider the following +commands: + +tftp 200000 /tftpboot/uImage +bootm :kernel-1 +Last command is equivalent to: +bootm 200000:kernel-1 + +tftp 200000 /tftpboot/uImage +bootm 400000:kernel-1 :ramdisk-1 +Last command is equivalent to: +bootm 400000:kernel-1 400000:ramdisk-1 + +tftp 200000 /tftpboot/uImage +bootm :kernel-1 400000:ramdisk-1 :fdt-1 +Last command is equivalent to: +bootm 200000:kernel-1 400000:ramdisk-1 400000:fdt-1 diff --git a/roms/u-boot/doc/uImage.FIT/howto.txt b/roms/u-boot/doc/uImage.FIT/howto.txt new file mode 100644 index 000000000..019dda24a --- /dev/null +++ b/roms/u-boot/doc/uImage.FIT/howto.txt @@ -0,0 +1,405 @@ +How to use images in the new image format +========================================= + +Author: Bartlomiej Sieka <tur@semihalf.com> + + +Overview +-------- + +The new uImage format allows more flexibility in handling images of various +types (kernel, ramdisk, etc.), it also enhances integrity protection of images +with sha1 and md5 checksums. + +Two auxiliary tools are needed on the development host system in order to +create an uImage in the new format: mkimage and dtc, although only one +(mkimage) is invoked directly. dtc is called from within mkimage and operates +behind the scenes, but needs to be present in the $PATH nevertheless. It is +important that the dtc used has support for binary includes -- refer to + + git://git.kernel.org/pub/scm/utils/dtc/dtc.git + +for its latest version. mkimage (together with dtc) takes as input +an image source file, which describes the contents of the image and defines +its various properties used during booting. By convention, image source file +has the ".its" extension, also, the details of its format are given in +doc/uImage.FIT/source_file_format.txt. The actual data that is to be included in +the uImage (kernel, ramdisk, etc.) is specified in the image source file in the +form of paths to appropriate data files. The outcome of the image creation +process is a binary file (by convention with the ".itb" extension) that +contains all the referenced data (kernel, ramdisk, etc.) and other information +needed by U-Boot to handle the uImage properly. The uImage file is then +transferred to the target (e.g., via tftp) and booted using the bootm command. + +To summarize the prerequisites needed for new uImage creation: +- mkimage +- dtc (with support for binary includes) +- image source file (*.its) +- image data file(s) + + +Here's a graphical overview of the image creation and booting process: + +image source file mkimage + dtc transfer to target + + ---------------> image file --------------------> bootm +image data file(s) + +SPL usage +--------- + +The SPL can make use of the new image format as well, this traditionally +is used to ship multiple device tree files within one image. Code in the SPL +will choose the one matching the current board and append this to the +U-Boot proper binary to be automatically used up by it. +Aside from U-Boot proper and one device tree blob the SPL can load multiple, +arbitrary image files as well. These binaries should be specified in their +own subnode under the /images node, which should then be referenced from one or +multiple /configurations subnodes. The required images must be enumerated in +the "loadables" property as a list of strings. + +If a platform specific image source file (.its) is shipped with the U-Boot +source, it can be specified using the CONFIG_SPL_FIT_SOURCE Kconfig symbol. +In this case it will be automatically used by U-Boot's Makefile to generate +the image. +If a static source file is not flexible enough, CONFIG_SPL_FIT_GENERATOR +can point to a script which generates this image source file during +the build process. It gets passed a list of device tree files (taken from the +CONFIG_OF_LIST symbol). + +The SPL also records to a DT all additional images (called loadables) which are +loaded. The information about loadables locations is passed via the DT node with +fit-images name. + +Loadables Example +----------------- +Consider the following case for an ARM64 platform where U-Boot runs in EL2 +started by ATF where SPL is loading U-Boot (as loadables) and ATF (as firmware). + +/dts-v1/; + +/ { + description = "Configuration to load ATF before U-Boot"; + + images { + uboot { + description = "U-Boot (64-bit)"; + data = /incbin/("u-boot-nodtb.bin"); + type = "firmware"; + os = "u-boot"; + arch = "arm64"; + compression = "none"; + load = <0x8 0x8000000>; + entry = <0x8 0x8000000>; + hash { + algo = "md5"; + }; + }; + atf { + description = "ARM Trusted Firmware"; + data = /incbin/("bl31.bin"); + type = "firmware"; + os = "arm-trusted-firmware"; + arch = "arm64"; + compression = "none"; + load = <0xfffea000>; + entry = <0xfffea000>; + hash { + algo = "md5"; + }; + }; + fdt_1 { + description = "zynqmp-zcu102-revA"; + data = /incbin/("arch/arm/dts/zynqmp-zcu102-revA.dtb"); + type = "flat_dt"; + arch = "arm64"; + compression = "none"; + load = <0x100000>; + hash { + algo = "md5"; + }; + }; + }; + configurations { + default = "config_1"; + + config_1 { + description = "zynqmp-zcu102-revA"; + firmware = "atf"; + loadables = "uboot"; + fdt = "fdt_1"; + }; + }; +}; + +In this case the SPL records via fit-images DT node the information about +loadables U-Boot image. + +ZynqMP> fdt addr $fdtcontroladdr +ZynqMP> fdt print /fit-images +fit-images { + uboot { + os = "u-boot"; + type = "firmware"; + size = <0x001017c8>; + entry = <0x00000008 0x08000000>; + load = <0x00000008 0x08000000>; + }; +}; + +As you can see entry and load properties are 64bit wide to support loading +images above 4GB (in past entry and load properties where just 32bit). + + +Example 1 -- old-style (non-FDT) kernel booting +----------------------------------------------- + +Consider a simple scenario, where a PPC Linux kernel built from sources on the +development host is to be booted old-style (non-FDT) by U-Boot on an embedded +target. Assume that the outcome of the build is vmlinux.bin.gz, a file which +contains a gzip-compressed PPC Linux kernel (the only data file in this case). +The uImage can be produced using the image source file +doc/uImage.FIT/kernel.its (note that kernel.its assumes that vmlinux.bin.gz is +in the current working directory; if desired, an alternative path can be +specified in the kernel.its file). Here's how to create the image and inspect +its contents: + +[on the host system] +$ mkimage -f kernel.its kernel.itb +DTC: dts->dtb on file "kernel.its" +$ +$ mkimage -l kernel.itb +FIT description: Simple image with single Linux kernel +Created: Tue Mar 11 17:26:15 2008 + Image 0 (kernel) + Description: Vanilla Linux kernel + Type: Kernel Image + Compression: gzip compressed + Data Size: 943347 Bytes = 921.24 kB = 0.90 MB + Architecture: PowerPC + OS: Linux + Load Address: 0x00000000 + Entry Point: 0x00000000 + Hash algo: crc32 + Hash value: 2ae2bb40 + Hash algo: sha1 + Hash value: 3c200f34e2c226ddc789240cca0c59fc54a67cf4 + Default Configuration: 'config-1' + Configuration 0 (config-1) + Description: Boot Linux kernel + Kernel: kernel + + +The resulting image file kernel.itb can be now transferred to the target, +inspected and booted (note that first three U-Boot commands below are shown +for completeness -- they are part of the standard booting procedure and not +specific to the new image format). + +[on the target system] +=> print nfsargs +nfsargs=setenv bootargs root=/dev/nfs rw nfsroot=${serverip}:${rootpath} +=> print addip +addip=setenv bootargs ${bootargs} ip=${ipaddr}:${serverip}:${gatewayip}:${netmask}:${hostname}:${netdev}:off panic=1 +=> run nfsargs addip +=> tftp 900000 /path/to/tftp/location/kernel.itb +Using FEC device +TFTP from server 192.168.1.1; our IP address is 192.168.160.5 +Filename '/path/to/tftp/location/kernel.itb'. +Load address: 0x900000 +Loading: ################################################################# +done +Bytes transferred = 944464 (e6950 hex) +=> iminfo + +## Checking Image at 00900000 ... + FIT image found + FIT description: Simple image with single Linux kernel + Created: 2008-03-11 16:26:15 UTC + Image 0 (kernel) + Description: Vanilla Linux kernel + Type: Kernel Image + Compression: gzip compressed + Data Start: 0x009000e0 + Data Size: 943347 Bytes = 921.2 kB + Architecture: PowerPC + OS: Linux + Load Address: 0x00000000 + Entry Point: 0x00000000 + Hash algo: crc32 + Hash value: 2ae2bb40 + Hash algo: sha1 + Hash value: 3c200f34e2c226ddc789240cca0c59fc54a67cf4 + Default Configuration: 'config-1' + Configuration 0 (config-1) + Description: Boot Linux kernel + Kernel: kernel + +=> bootm +## Booting kernel from FIT Image at 00900000 ... + Using 'config-1' configuration + Trying 'kernel' kernel subimage + Description: Vanilla Linux kernel + Type: Kernel Image + Compression: gzip compressed + Data Start: 0x009000e0 + Data Size: 943347 Bytes = 921.2 kB + Architecture: PowerPC + OS: Linux + Load Address: 0x00000000 + Entry Point: 0x00000000 + Hash algo: crc32 + Hash value: 2ae2bb40 + Hash algo: sha1 + Hash value: 3c200f34e2c226ddc789240cca0c59fc54a67cf4 + Verifying Hash Integrity ... crc32+ sha1+ OK + Uncompressing Kernel Image ... OK +Memory BAT mapping: BAT2=256Mb, BAT3=0Mb, residual: 0Mb +Linux version 2.4.25 (m8@hekate) (gcc version 4.0.0 (DENX ELDK 4.0 4.0.0)) #2 czw lip 5 17:56:18 CEST 2007 +On node 0 totalpages: 65536 +zone(0): 65536 pages. +zone(1): 0 pages. +zone(2): 0 pages. +Kernel command line: root=/dev/nfs rw nfsroot=192.168.1.1:/opt/eldk-4.1/ppc_6xx ip=192.168.160.5:192.168.1.1::255.255.0.0:lite5200b:eth0:off panic=1 +Calibrating delay loop... 307.20 BogoMIPS + + +Example 2 -- new-style (FDT) kernel booting +------------------------------------------- + +Consider another simple scenario, where a PPC Linux kernel is to be booted +new-style, i.e., with a FDT blob. In this case there are two prerequisite data +files: vmlinux.bin.gz (Linux kernel) and target.dtb (FDT blob). The uImage can +be produced using image source file doc/uImage.FIT/kernel_fdt.its like this +(note again, that both prerequisite data files are assumed to be present in +the current working directory -- image source file kernel_fdt.its can be +modified to take the files from some other location if needed): + +[on the host system] +$ mkimage -f kernel_fdt.its kernel_fdt.itb +DTC: dts->dtb on file "kernel_fdt.its" +$ +$ mkimage -l kernel_fdt.itb +FIT description: Simple image with single Linux kernel and FDT blob +Created: Tue Mar 11 16:29:22 2008 + Image 0 (kernel) + Description: Vanilla Linux kernel + Type: Kernel Image + Compression: gzip compressed + Data Size: 1092037 Bytes = 1066.44 kB = 1.04 MB + Architecture: PowerPC + OS: Linux + Load Address: 0x00000000 + Entry Point: 0x00000000 + Hash algo: crc32 + Hash value: 2c0cc807 + Hash algo: sha1 + Hash value: 264b59935470e42c418744f83935d44cdf59a3bb + Image 1 (fdt-1) + Description: Flattened Device Tree blob + Type: Flat Device Tree + Compression: uncompressed + Data Size: 16384 Bytes = 16.00 kB = 0.02 MB + Architecture: PowerPC + Hash algo: crc32 + Hash value: 0d655d71 + Hash algo: sha1 + Hash value: 25ab4e15cd4b8a5144610394560d9c318ce52def + Default Configuration: 'conf-1' + Configuration 0 (conf-1) + Description: Boot Linux kernel with FDT blob + Kernel: kernel + FDT: fdt-1 + + +The resulting image file kernel_fdt.itb can be now transferred to the target, +inspected and booted: + +[on the target system] +=> tftp 900000 /path/to/tftp/location/kernel_fdt.itb +Using FEC device +TFTP from server 192.168.1.1; our IP address is 192.168.160.5 +Filename '/path/to/tftp/location/kernel_fdt.itb'. +Load address: 0x900000 +Loading: ################################################################# + ########### +done +Bytes transferred = 1109776 (10ef10 hex) +=> iminfo + +## Checking Image at 00900000 ... + FIT image found + FIT description: Simple image with single Linux kernel and FDT blob + Created: 2008-03-11 15:29:22 UTC + Image 0 (kernel) + Description: Vanilla Linux kernel + Type: Kernel Image + Compression: gzip compressed + Data Start: 0x009000ec + Data Size: 1092037 Bytes = 1 MB + Architecture: PowerPC + OS: Linux + Load Address: 0x00000000 + Entry Point: 0x00000000 + Hash algo: crc32 + Hash value: 2c0cc807 + Hash algo: sha1 + Hash value: 264b59935470e42c418744f83935d44cdf59a3bb + Image 1 (fdt-1) + Description: Flattened Device Tree blob + Type: Flat Device Tree + Compression: uncompressed + Data Start: 0x00a0abdc + Data Size: 16384 Bytes = 16 kB + Architecture: PowerPC + Hash algo: crc32 + Hash value: 0d655d71 + Hash algo: sha1 + Hash value: 25ab4e15cd4b8a5144610394560d9c318ce52def + Default Configuration: 'conf-1' + Configuration 0 (conf-1) + Description: Boot Linux kernel with FDT blob + Kernel: kernel + FDT: fdt-1 +=> bootm +## Booting kernel from FIT Image at 00900000 ... + Using 'conf-1' configuration + Trying 'kernel' kernel subimage + Description: Vanilla Linux kernel + Type: Kernel Image + Compression: gzip compressed + Data Start: 0x009000ec + Data Size: 1092037 Bytes = 1 MB + Architecture: PowerPC + OS: Linux + Load Address: 0x00000000 + Entry Point: 0x00000000 + Hash algo: crc32 + Hash value: 2c0cc807 + Hash algo: sha1 + Hash value: 264b59935470e42c418744f83935d44cdf59a3bb + Verifying Hash Integrity ... crc32+ sha1+ OK + Uncompressing Kernel Image ... OK +## Flattened Device Tree from FIT Image at 00900000 + Using 'conf-1' configuration + Trying 'fdt-1' FDT blob subimage + Description: Flattened Device Tree blob + Type: Flat Device Tree + Compression: uncompressed + Data Start: 0x00a0abdc + Data Size: 16384 Bytes = 16 kB + Architecture: PowerPC + Hash algo: crc32 + Hash value: 0d655d71 + Hash algo: sha1 + Hash value: 25ab4e15cd4b8a5144610394560d9c318ce52def + Verifying Hash Integrity ... crc32+ sha1+ OK + Booting using the fdt blob at 0xa0abdc + Loading Device Tree to 007fc000, end 007fffff ... OK +[ 0.000000] Using lite5200 machine description +[ 0.000000] Linux version 2.6.24-rc6-gaebecdfc (m8@hekate) (gcc version 4.0.0 (DENX ELDK 4.1 4.0.0)) #1 Sat Jan 12 15:38:48 CET 2008 + + +Example 3 -- advanced booting +----------------------------- + +Refer to doc/uImage.FIT/multi.its for an image source file that allows more +sophisticated booting scenarios (multiple kernels, ramdisks and fdt blobs). diff --git a/roms/u-boot/doc/uImage.FIT/kernel.its b/roms/u-boot/doc/uImage.FIT/kernel.its new file mode 100644 index 000000000..77ddf622d --- /dev/null +++ b/roms/u-boot/doc/uImage.FIT/kernel.its @@ -0,0 +1,91 @@ +/* + * Simple U-Boot uImage source file containing a single kernel + */ + +/dts-v1/; + +/ { + description = "Simple image with single Linux kernel"; + #address-cells = <1>; + + images { + kernel { + description = "Vanilla Linux kernel"; + data = /incbin/("./vmlinux.bin.gz"); + type = "kernel"; + arch = "ppc"; + os = "linux"; + compression = "gzip"; + load = <00000000>; + entry = <00000000>; + hash-1 { + algo = "crc32"; + }; + hash-2 { + algo = "sha1"; + }; + }; + }; + + configurations { + default = "config-1"; + config-1 { + description = "Boot Linux kernel"; + kernel = "kernel"; + }; + }; +}; + + + +For x86 a setup node is also required: see x86-fit-boot.txt. + +/dts-v1/; + +/ { + description = "Simple image with single Linux kernel on x86"; + #address-cells = <1>; + + images { + kernel { + description = "Vanilla Linux kernel"; + data = /incbin/("./image.bin.lzo"); + type = "kernel"; + arch = "x86"; + os = "linux"; + compression = "lzo"; + load = <0x01000000>; + entry = <0x00000000>; + hash-2 { + algo = "sha1"; + }; + }; + + setup { + description = "Linux setup.bin"; + data = /incbin/("./setup.bin"); + type = "x86_setup"; + arch = "x86"; + os = "linux"; + compression = "none"; + load = <0x00090000>; + entry = <0x00090000>; + hash-2 { + algo = "sha1"; + }; + }; + }; + + configurations { + default = "config-1"; + config-1 { + description = "Boot Linux kernel"; + kernel = "kernel"; + setup = "setup"; + }; + }; +}; + +Note: the above assumes a 32-bit kernel. To directly boot a 64-bit kernel, +change both arch values to "x86_64". U-Boot will then change to 64-bit mode +before booting the kernel (see boot_linux_kernel()). diff --git a/roms/u-boot/doc/uImage.FIT/kernel_fdt.its b/roms/u-boot/doc/uImage.FIT/kernel_fdt.its new file mode 100644 index 000000000..000d85b8e --- /dev/null +++ b/roms/u-boot/doc/uImage.FIT/kernel_fdt.its @@ -0,0 +1,51 @@ +/* + * Simple U-Boot uImage source file containing a single kernel and FDT blob + */ + +/dts-v1/; + +/ { + description = "Simple image with single Linux kernel and FDT blob"; + #address-cells = <1>; + + images { + kernel { + description = "Vanilla Linux kernel"; + data = /incbin/("./vmlinux.bin.gz"); + type = "kernel"; + arch = "ppc"; + os = "linux"; + compression = "gzip"; + load = <00000000>; + entry = <00000000>; + hash-1 { + algo = "crc32"; + }; + hash-2 { + algo = "sha1"; + }; + }; + fdt-1 { + description = "Flattened Device Tree blob"; + data = /incbin/("./target.dtb"); + type = "flat_dt"; + arch = "ppc"; + compression = "none"; + hash-1 { + algo = "crc32"; + }; + hash-2 { + algo = "sha1"; + }; + }; + }; + + configurations { + default = "conf-1"; + conf-1 { + description = "Boot Linux kernel with FDT blob"; + kernel = "kernel"; + fdt = "fdt-1"; + }; + }; +}; diff --git a/roms/u-boot/doc/uImage.FIT/kernel_fdts_compressed.its b/roms/u-boot/doc/uImage.FIT/kernel_fdts_compressed.its new file mode 100644 index 000000000..8f81106ef --- /dev/null +++ b/roms/u-boot/doc/uImage.FIT/kernel_fdts_compressed.its @@ -0,0 +1,73 @@ +/* + * U-Boot uImage source file with a kernel and multiple compressed FDT blobs. + * Since the FDTs are compressed, configurations must provide a compatible + * string to match directly. + */ + +/dts-v1/; + +/ { + description = "Image with single Linux kernel and compressed FDT blobs"; + #address-cells = <1>; + + images { + kernel { + description = "Vanilla Linux kernel"; + data = /incbin/("./vmlinux.bin.gz"); + type = "kernel"; + arch = "ppc"; + os = "linux"; + compression = "gzip"; + load = <00000000>; + entry = <00000000>; + hash-1 { + algo = "crc32"; + }; + hash-2 { + algo = "sha1"; + }; + }; + fdt@1 { + description = "Flattened Device Tree blob 1"; + data = /incbin/("./myboard-var1.dtb"); + type = "flat_dt"; + arch = "ppc"; + compression = "gzip"; + hash-1 { + algo = "crc32"; + }; + hash-2 { + algo = "sha1"; + }; + }; + fdt@2 { + description = "Flattened Device Tree blob 2"; + data = /incbin/("./myboard-var2.dtb"); + type = "flat_dt"; + arch = "ppc"; + compression = "lzma"; + hash-1 { + algo = "crc32"; + }; + hash-2 { + algo = "sha1"; + }; + }; + }; + + configurations { + default = "conf@1"; + conf@1 { + description = "Boot Linux kernel with FDT blob 1"; + kernel = "kernel"; + fdt = "fdt@1"; + compatible = "myvendor,myboard-variant1"; + }; + conf@2 { + description = "Boot Linux kernel with FDT blob 2"; + kernel = "kernel"; + fdt = "fdt@2"; + compatible = "myvendor,myboard-variant2"; + }; + }; +}; diff --git a/roms/u-boot/doc/uImage.FIT/multi-with-fpga.its b/roms/u-boot/doc/uImage.FIT/multi-with-fpga.its new file mode 100644 index 000000000..021cbc7cf --- /dev/null +++ b/roms/u-boot/doc/uImage.FIT/multi-with-fpga.its @@ -0,0 +1,68 @@ +/* + * U-Boot uImage source file with multiple kernels, ramdisks and FDT blobs + * This example makes use of the 'loadables' field + */ + +/dts-v1/; + +/ { + description = "Configuration to load fpga before Kernel"; + #address-cells = <1>; + + images { + fdt-1 { + description = "zc706"; + data = /incbin/("/tftpboot/devicetree.dtb"); + type = "flat_dt"; + arch = "arm"; + compression = "none"; + load = <0x10000000>; + hash-1 { + algo = "md5"; + }; + }; + + fpga { + description = "FPGA"; + data = /incbin/("/tftpboot/download.bit"); + type = "fpga"; + arch = "arm"; + compression = "none"; + load = <0x30000000>; + compatible = "u-boot,fpga-legacy" + hash-1 { + algo = "md5"; + }; + }; + + linux_kernel { + description = "Linux"; + data = /incbin/("/tftpboot/zImage"); + type = "kernel"; + arch = "arm"; + os = "linux"; + compression = "none"; + load = <0x8000>; + entry = <0x8000>; + hash-1 { + algo = "md5"; + }; + }; + }; + + configurations { + default = "config-2"; + config-1 { + description = "Linux"; + kernel = "linux_kernel"; + fdt = "fdt-1"; + }; + + config-2 { + description = "Linux with fpga"; + kernel = "linux_kernel"; + fdt = "fdt-1"; + loadables = "fpga"; + }; + }; +}; diff --git a/roms/u-boot/doc/uImage.FIT/multi-with-loadables.its b/roms/u-boot/doc/uImage.FIT/multi-with-loadables.its new file mode 100644 index 000000000..4d4909f83 --- /dev/null +++ b/roms/u-boot/doc/uImage.FIT/multi-with-loadables.its @@ -0,0 +1,89 @@ +/* + * U-Boot uImage source file with multiple kernels, ramdisks and FDT blobs + * This example makes use of the 'loadables' field + */ + +/dts-v1/; + +/ { + description = "Configuration to load a Xen Kernel"; + #address-cells = <1>; + + images { + xen_kernel { + description = "xen binary"; + data = /incbin/("./xen"); + type = "kernel"; + arch = "arm"; + os = "linux"; + compression = "none"; + load = <0xa0000000>; + entry = <0xa0000000>; + hash-1 { + algo = "md5"; + }; + }; + + fdt-1 { + description = "xexpress-ca15 tree blob"; + data = /incbin/("./vexpress-v2p-ca15-tc1.dtb"); + type = "flat_dt"; + arch = "arm"; + compression = "none"; + load = <0xb0000000>; + hash-1 { + algo = "md5"; + }; + }; + + fdt-2 { + description = "xexpress-ca15 tree blob"; + data = /incbin/("./vexpress-v2p-ca15-tc1.dtb"); + type = "flat_dt"; + arch = "arm"; + compression = "none"; + load = <0xb0400000>; + hash-1 { + algo = "md5"; + }; + }; + + linux_kernel { + description = "Linux Image"; + data = /incbin/("./Image"); + type = "kernel"; + arch = "arm"; + os = "linux"; + compression = "none"; + load = <0xa0000000>; + entry = <0xa0000000>; + hash-1 { + algo = "md5"; + }; + }; + }; + + configurations { + default = "config-2"; + + config-1 { + description = "Just plain Linux"; + kernel = "linux_kernel"; + fdt = "fdt-1"; + }; + + config-2 { + description = "Xen one loadable"; + kernel = "xen_kernel"; + fdt = "fdt-1"; + loadables = "linux_kernel"; + }; + + config-3 { + description = "Xen two loadables"; + kernel = "xen_kernel"; + fdt = "fdt-1"; + loadables = "linux_kernel", "fdt-2"; + }; + }; +}; diff --git a/roms/u-boot/doc/uImage.FIT/multi.its b/roms/u-boot/doc/uImage.FIT/multi.its new file mode 100644 index 000000000..26c8dad6a --- /dev/null +++ b/roms/u-boot/doc/uImage.FIT/multi.its @@ -0,0 +1,133 @@ +/* + * U-Boot uImage source file with multiple kernels, ramdisks and FDT blobs + */ + +/dts-v1/; + +/ { + description = "Various kernels, ramdisks and FDT blobs"; + #address-cells = <1>; + + images { + kernel-1 { + description = "vanilla-2.6.23"; + data = /incbin/("./vmlinux.bin.gz"); + type = "kernel"; + arch = "ppc"; + os = "linux"; + compression = "gzip"; + load = <00000000>; + entry = <00000000>; + hash-1 { + algo = "md5"; + }; + hash-2 { + algo = "sha1"; + }; + }; + + kernel-2 { + description = "2.6.23-denx"; + data = /incbin/("./2.6.23-denx.bin.gz"); + type = "kernel"; + arch = "ppc"; + os = "linux"; + compression = "gzip"; + load = <00000000>; + entry = <00000000>; + hash-1 { + algo = "sha1"; + }; + }; + + kernel-3 { + description = "2.4.25-denx"; + data = /incbin/("./2.4.25-denx.bin.gz"); + type = "kernel"; + arch = "ppc"; + os = "linux"; + compression = "gzip"; + load = <00000000>; + entry = <00000000>; + hash-1 { + algo = "md5"; + }; + }; + + ramdisk-1 { + description = "eldk-4.2-ramdisk"; + data = /incbin/("./eldk-4.2-ramdisk"); + type = "ramdisk"; + arch = "ppc"; + os = "linux"; + compression = "gzip"; + load = <00000000>; + entry = <00000000>; + hash-1 { + algo = "sha1"; + }; + }; + + ramdisk-2 { + description = "eldk-3.1-ramdisk"; + data = /incbin/("./eldk-3.1-ramdisk"); + type = "ramdisk"; + arch = "ppc"; + os = "linux"; + compression = "gzip"; + load = <00000000>; + entry = <00000000>; + hash-1 { + algo = "crc32"; + }; + }; + + fdt-1 { + description = "tqm5200-fdt"; + data = /incbin/("./tqm5200.dtb"); + type = "flat_dt"; + arch = "ppc"; + compression = "none"; + hash-1 { + algo = "crc32"; + }; + }; + + fdt-2 { + description = "tqm5200s-fdt"; + data = /incbin/("./tqm5200s.dtb"); + type = "flat_dt"; + arch = "ppc"; + compression = "none"; + load = <00700000>; + hash-1 { + algo = "sha1"; + }; + }; + + }; + + configurations { + default = "config-1"; + + config-1 { + description = "tqm5200 vanilla-2.6.23 configuration"; + kernel = "kernel-1"; + ramdisk = "ramdisk-1"; + fdt = "fdt-1"; + }; + + config-2 { + description = "tqm5200s denx-2.6.23 configuration"; + kernel = "kernel-2"; + ramdisk = "ramdisk-1"; + fdt = "fdt-2"; + }; + + config-3 { + description = "tqm5200s denx-2.4.25 configuration"; + kernel = "kernel-3"; + ramdisk = "ramdisk-2"; + }; + }; +}; diff --git a/roms/u-boot/doc/uImage.FIT/multi_spl.its b/roms/u-boot/doc/uImage.FIT/multi_spl.its new file mode 100644 index 000000000..594219974 --- /dev/null +++ b/roms/u-boot/doc/uImage.FIT/multi_spl.its @@ -0,0 +1,96 @@ +/dts-v1/; + +/* + * (Bogus) example FIT image description file demonstrating the usage + * of multiple images loaded by the SPL. + * Several binaries will be loaded at their respective load addresses. + * + * For booting U-Boot, "firmware" is searched first. If not found, "loadables" + * is used to identify images to be loaded into memory. If falcon boot is + * enabled, "kernel" is searched first. If not found, it falls back to the + * same flow as booting U-Boot. Changing image type will result skipping + * specific image. + * + * Finally the one image specifying an entry point will be entered by the SPL. + */ + +/ { + description = "multiple firmware blobs and U-Boot, loaded by SPL"; + #address-cells = <0x1>; + + images { + + uboot { + description = "U-Boot (64-bit)"; + type = "standalone"; + arch = "arm64"; + compression = "none"; + load = <0x4a000000>; + }; + + atf { + description = "ARM Trusted Firmware"; + type = "firmware"; + arch = "arm64"; + compression = "none"; + load = <0x18000>; + entry = <0x18000>; + }; + + mgmt-firmware { + description = "arisc management processor firmware"; + type = "firmware"; + arch = "or1k"; + compression = "none"; + load = <0x40000>; + }; + + fdt-1 { + description = "Pine64+ DT"; + type = "flat_dt"; + compression = "none"; + load = <0x4fa00000>; + arch = "arm64"; + }; + + fdt-2 { + description = "Pine64 DT"; + type = "flat_dt"; + compression = "none"; + load = <0x4fa00000>; + arch = "arm64"; + }; + + kernel { + description = "4.7-rc5 kernel"; + type = "kernel"; + compression = "none"; + load = <0x40080000>; + arch = "arm64"; + }; + + initrd { + description = "Debian installer initrd"; + type = "ramdisk"; + compression = "none"; + load = <0x4fe00000>; + arch = "arm64"; + }; + }; + + configurations { + default = "config-1"; + + config-1 { + description = "sun50i-a64-pine64-plus"; + loadables = "uboot", "atf", "kernel", "initrd"; + fdt = "fdt-1"; + }; + + config-2 { + description = "sun50i-a64-pine64"; + loadables = "uboot", "atf", "mgmt-firmware"; + fdt = "fdt-2"; + }; + }; +}; diff --git a/roms/u-boot/doc/uImage.FIT/overlay-fdt-boot.txt b/roms/u-boot/doc/uImage.FIT/overlay-fdt-boot.txt new file mode 100644 index 000000000..dddc4db1a --- /dev/null +++ b/roms/u-boot/doc/uImage.FIT/overlay-fdt-boot.txt @@ -0,0 +1,225 @@ +U-Boot FDT Overlay FIT usage +============================ + +Introduction +------------ +In many cases it is desirable to have a single FIT image support a multitude +of similar boards and their expansion options. The same kernel on DT enabled +platforms can support this easily enough by providing a DT blob upon boot +that matches the desired configuration. + +This document focuses on specifically using overlays as part of a FIT image. +General information regarding overlays including its syntax and building it +can be found in doc/README.fdt-overlays + +Configuration without overlays +------------------------------ + +Take a hypothetical board named 'foo' where there are different supported +revisions, reva and revb. Assume that both board revisions can use add a bar +add-on board, while only the revb board can use a baz add-on board. + +Without using overlays the configuration would be as follows for every case. + + /dts-v1/; + / { + images { + kernel { + data = /incbin/("./zImage"); + type = "kernel"; + arch = "arm"; + os = "linux"; + load = <0x82000000>; + entry = <0x82000000>; + }; + fdt-1 { + data = /incbin/("./foo-reva.dtb"); + type = "flat_dt"; + arch = "arm"; + }; + fdt-2 { + data = /incbin/("./foo-revb.dtb"); + type = "flat_dt"; + arch = "arm"; + }; + fdt-3 { + data = /incbin/("./foo-reva-bar.dtb"); + type = "flat_dt"; + arch = "arm"; + }; + fdt-4 { + data = /incbin/("./foo-revb-bar.dtb"); + type = "flat_dt"; + arch = "arm"; + }; + fdt-5 { + data = /incbin/("./foo-revb-baz.dtb"); + type = "flat_dt"; + arch = "arm"; + }; + fdt-6 { + data = /incbin/("./foo-revb-bar-baz.dtb"); + type = "flat_dt"; + arch = "arm"; + }; + }; + + configurations { + default = "foo-reva.dtb; + foo-reva.dtb { + kernel = "kernel"; + fdt = "fdt-1"; + }; + foo-revb.dtb { + kernel = "kernel"; + fdt = "fdt-2"; + }; + foo-reva-bar.dtb { + kernel = "kernel"; + fdt = "fdt-3"; + }; + foo-revb-bar.dtb { + kernel = "kernel"; + fdt = "fdt-4"; + }; + foo-revb-baz.dtb { + kernel = "kernel"; + fdt = "fdt-5"; + }; + foo-revb-bar-baz.dtb { + kernel = "kernel"; + fdt = "fdt-6"; + }; + }; + }; + +Note the blob needs to be compiled for each case and the combinatorial explosion of +configurations. A typical device tree blob is in the low hunderds of kbytes so a +multitude of configuration grows the image quite a bit. + +Booting this image is done by using + + # bootm <addr>#<config> + +Where config is one of: + foo-reva.dtb, foo-revb.dtb, foo-reva-bar.dtb, foo-revb-bar.dtb, + foo-revb-baz.dtb, foo-revb-bar-baz.dtb + +This selects the DTB to use when booting. + +Configuration using overlays +---------------------------- + +Device tree overlays can be applied to a base DT and result in the same blob +being passed to the booting kernel. This saves on space and avoid the combinatorial +explosion problem. + + /dts-v1/; + / { + images { + kernel { + data = /incbin/("./zImage"); + type = "kernel"; + arch = "arm"; + os = "linux"; + load = <0x82000000>; + entry = <0x82000000>; + }; + fdt-1 { + data = /incbin/("./foo.dtb"); + type = "flat_dt"; + arch = "arm"; + load = <0x87f00000>; + }; + fdt-2 { + data = /incbin/("./reva.dtbo"); + type = "flat_dt"; + arch = "arm"; + load = <0x87fc0000>; + }; + fdt-3 { + data = /incbin/("./revb.dtbo"); + type = "flat_dt"; + arch = "arm"; + load = <0x87fc0000>; + }; + fdt-4 { + data = /incbin/("./bar.dtbo"); + type = "flat_dt"; + arch = "arm"; + load = <0x87fc0000>; + }; + fdt-5 { + data = /incbin/("./baz.dtbo"); + type = "flat_dt"; + arch = "arm"; + load = <0x87fc0000>; + }; + }; + + configurations { + default = "foo-reva.dtb; + foo-reva.dtb { + kernel = "kernel"; + fdt = "fdt-1", "fdt-2"; + }; + foo-revb.dtb { + kernel = "kernel"; + fdt = "fdt-1", "fdt-3"; + }; + foo-reva-bar.dtb { + kernel = "kernel"; + fdt = "fdt-1", "fdt-2", "fdt-4"; + }; + foo-revb-bar.dtb { + kernel = "kernel"; + fdt = "fdt-1", "fdt-3", "fdt-4"; + }; + foo-revb-baz.dtb { + kernel = "kernel"; + fdt = "fdt-1", "fdt-3", "fdt-5"; + }; + foo-revb-bar-baz.dtb { + kernel = "kernel"; + fdt = "fdt-1", "fdt-3", "fdt-4", "fdt-5"; + }; + bar { + fdt = "fdt-4"; + }; + baz { + fdt = "fdt-5"; + }; + }; + }; + +Booting this image is exactly the same as the non-overlay example. +u-boot will retrieve the base blob and apply the overlays in sequence as +they are declared in the configuration. + +Note the minimum amount of different DT blobs, as well as the requirement for +the DT blobs to have a load address; the overlay application requires the blobs +to be writeable. + +Configuration using overlays and feature selection +-------------------------------------------------- + +Although the configuration in the previous section works is a bit inflexible +since it requires all possible configuration options to be laid out before +hand in the FIT image. For the add-on boards the extra config selection method +might make sense. + +Note the two bar & baz configuration nodes. To boot a reva board with +the bar add-on board enabled simply use: + + # bootm <addr>#foo-reva.dtb#bar + +While booting a revb with bar and baz is as follows: + + # bootm <addr>#foo-revb.dtb#bar#baz + +The limitation for a feature selection configuration node is that a single +fdt option is currently supported. + +Pantelis Antoniou +pantelis.antoniou@konsulko.com +12/6/2017 diff --git a/roms/u-boot/doc/uImage.FIT/sec_firmware_ppa.its b/roms/u-boot/doc/uImage.FIT/sec_firmware_ppa.its new file mode 100644 index 000000000..a7acde17c --- /dev/null +++ b/roms/u-boot/doc/uImage.FIT/sec_firmware_ppa.its @@ -0,0 +1,49 @@ +/dts-v1/; + +/* + * Example FIT image description file demonstrating the usage + * of SEC Firmware and multiple loadable images loaded by the u-boot. + * For booting PPA (SEC Firmware), "firmware" is searched and loaded. + * + * Multiple binaries will be loaded as "loadables" (if present) at their + * respective load offsets from firmware image address. + */ + +/{ + description = "PPA Firmware"; + #address-cells = <1>; + images { + firmware@1 { + description = "PPA Firmware: <version>"; + data = /incbin/("../obj/monitor.bin"); + type = "firmware"; + arch = "arm64"; + compression = "none"; + }; + trustedOS@1 { + description = "Trusted OS"; + data = /incbin/("../../tee.bin"); + type = "OS"; + arch = "arm64"; + compression = "none"; + load = <0x00200000>; + }; + fuse_scr { + description = "Fuse Script"; + data = /incbin/("../../fuse_scr.bin"); + type = "firmware"; + arch = "arm64"; + compression = "none"; + load = <0x00180000>; + }; + }; + + configurations { + default = "config-1"; + config-1 { + description = "PPA Secure firmware"; + firmware = "firmware@1"; + loadables = "trustedOS@1", "fuse_scr"; + }; + }; +}; diff --git a/roms/u-boot/doc/uImage.FIT/sign-configs.its b/roms/u-boot/doc/uImage.FIT/sign-configs.its new file mode 100644 index 000000000..9e992c198 --- /dev/null +++ b/roms/u-boot/doc/uImage.FIT/sign-configs.its @@ -0,0 +1,45 @@ +/dts-v1/; + +/ { + description = "Chrome OS kernel image with one or more FDT blobs"; + #address-cells = <1>; + + images { + kernel { + data = /incbin/("test-kernel.bin"); + type = "kernel_noload"; + arch = "sandbox"; + os = "linux"; + compression = "lzo"; + load = <0x4>; + entry = <0x8>; + kernel-version = <1>; + hash-1 { + algo = "sha1"; + }; + }; + fdt-1 { + description = "snow"; + data = /incbin/("sandbox-kernel.dtb"); + type = "flat_dt"; + arch = "sandbox"; + compression = "none"; + fdt-version = <1>; + hash-1 { + algo = "sha1"; + }; + }; + }; + configurations { + default = "conf-1"; + conf-1 { + kernel = "kernel"; + fdt = "fdt-1"; + signature { + algo = "sha1,rsa2048"; + key-name-hint = "dev"; + sign-images = "fdt", "kernel"; + }; + }; + }; +}; diff --git a/roms/u-boot/doc/uImage.FIT/sign-images.its b/roms/u-boot/doc/uImage.FIT/sign-images.its new file mode 100644 index 000000000..18c759e9e --- /dev/null +++ b/roms/u-boot/doc/uImage.FIT/sign-images.its @@ -0,0 +1,42 @@ +/dts-v1/; + +/ { + description = "Chrome OS kernel image with one or more FDT blobs"; + #address-cells = <1>; + + images { + kernel { + data = /incbin/("test-kernel.bin"); + type = "kernel_noload"; + arch = "sandbox"; + os = "linux"; + compression = "none"; + load = <0x4>; + entry = <0x8>; + kernel-version = <1>; + signature { + algo = "sha1,rsa2048"; + key-name-hint = "dev"; + }; + }; + fdt-1 { + description = "snow"; + data = /incbin/("sandbox-kernel.dtb"); + type = "flat_dt"; + arch = "sandbox"; + compression = "none"; + fdt-version = <1>; + signature { + algo = "sha1,rsa2048"; + key-name-hint = "dev"; + }; + }; + }; + configurations { + default = "conf-1"; + conf-1 { + kernel = "kernel"; + fdt = "fdt-1"; + }; + }; +}; diff --git a/roms/u-boot/doc/uImage.FIT/signature.txt b/roms/u-boot/doc/uImage.FIT/signature.txt new file mode 100644 index 000000000..d9a912119 --- /dev/null +++ b/roms/u-boot/doc/uImage.FIT/signature.txt @@ -0,0 +1,682 @@ +U-Boot FIT Signature Verification +================================= + +Introduction +------------ +FIT supports hashing of images so that these hashes can be checked on +loading. This protects against corruption of the image. However it does not +prevent the substitution of one image for another. + +The signature feature allows the hash to be signed with a private key such +that it can be verified using a public key later. Provided that the private +key is kept secret and the public key is stored in a non-volatile place, +any image can be verified in this way. + +See verified-boot.txt for more general information on verified boot. + + +Concepts +-------- +Some familiarity with public key cryptography is assumed in this section. + +The procedure for signing is as follows: + + - hash an image in the FIT + - sign the hash with a private key to produce a signature + - store the resulting signature in the FIT + +The procedure for verification is: + + - read the FIT + - obtain the public key + - extract the signature from the FIT + - hash the image from the FIT + - verify (with the public key) that the extracted signature matches the + hash + +The signing is generally performed by mkimage, as part of making a firmware +image for the device. The verification is normally done in U-Boot on the +device. + + +Algorithms +---------- +In principle any suitable algorithm can be used to sign and verify a hash. +At present only one class of algorithms is supported: SHA1 hashing with RSA. +This works by hashing the image to produce a 20-byte hash. + +While it is acceptable to bring in large cryptographic libraries such as +openssl on the host side (e.g. mkimage), it is not desirable for U-Boot. +For the run-time verification side, it is important to keep code and data +size as small as possible. + +For this reason the RSA image verification uses pre-processed public keys +which can be used with a very small amount of code - just some extraction +of data from the FDT and exponentiation mod n. Code size impact is a little +under 5KB on Tegra Seaboard, for example. + +It is relatively straightforward to add new algorithms if required. If +another RSA variant is needed, then it can be added to the table in +image-sig.c. If another algorithm is needed (such as DSA) then it can be +placed alongside rsa.c, and its functions added to the table in image-sig.c +also. + + +Creating an RSA key pair and certificate +---------------------------------------- +To create a new public/private key pair, size 2048 bits: + +$ openssl genpkey -algorithm RSA -out keys/dev.key \ + -pkeyopt rsa_keygen_bits:2048 -pkeyopt rsa_keygen_pubexp:65537 + +To create a certificate for this containing the public key: + +$ openssl req -batch -new -x509 -key keys/dev.key -out keys/dev.crt + +If you like you can look at the public key also: + +$ openssl rsa -in keys/dev.key -pubout + + +Device Tree Bindings +-------------------- +The following properties are required in the FIT's signature node(s) to +allow the signer to operate. These should be added to the .its file. +Signature nodes sit at the same level as hash nodes and are called +signature-1, signature-2, etc. + +- algo: Algorithm name (e.g. "sha1,rsa2048") + +- key-name-hint: Name of key to use for signing. The keys will normally be in +a single directory (parameter -k to mkimage). For a given key <name>, its +private key is stored in <name>.key and the certificate is stored in +<name>.crt. + +When the image is signed, the following properties are added (mandatory): + +- value: The signature data (e.g. 256 bytes for 2048-bit RSA) + +When the image is signed, the following properties are optional: + +- timestamp: Time when image was signed (standard Unix time_t format) + +- signer-name: Name of the signer (e.g. "mkimage") + +- signer-version: Version string of the signer (e.g. "2013.01") + +- comment: Additional information about the signer or image + +- padding: The padding algorithm, it may be pkcs-1.5 or pss, + if no value is provided we assume pkcs-1.5 + +For config bindings (see Signed Configurations below), the following +additional properties are optional: + +- sign-images: A list of images to sign, each being a property of the conf +node that contains then. The default is "kernel,fdt" which means that these +two images will be looked up in the config and signed if present. + +For config bindings, these properties are added by the signer: + +- hashed-nodes: A list of nodes which were hashed by the signer. Each is + a string - the full path to node. A typical value might be: + + hashed-nodes = "/", "/configurations/conf-1", "/images/kernel", + "/images/kernel/hash-1", "/images/fdt-1", + "/images/fdt-1/hash-1"; + +- hashed-strings: The start and size of the string region of the FIT that + was hashed + +Example: See sign-images.its for an example image tree source file and +sign-configs.its for config signing. + + +Public Key Storage +------------------ +In order to verify an image that has been signed with a public key we need to +have a trusted public key. This cannot be stored in the signed image, since +it would be easy to alter. For this implementation we choose to store the +public key in U-Boot's control FDT (using CONFIG_OF_CONTROL). + +Public keys should be stored as sub-nodes in a /signature node. Required +properties are: + +- algo: Algorithm name (e.g. "sha1,rsa2048" or "sha256,ecdsa256") + +Optional properties are: + +- key-name-hint: Name of key used for signing. This is only a hint since it +is possible for the name to be changed. Verification can proceed by checking +all available signing keys until one matches. + +- required: If present this indicates that the key must be verified for the +image / configuration to be considered valid. Only required keys are +normally verified by the FIT image booting algorithm. Valid values are +"image" to force verification of all images, and "conf" to force verification +of the selected configuration (which then relies on hashes in the images to +verify those). + +Each signing algorithm has its own additional properties. + +For RSA the following are mandatory: + +- rsa,num-bits: Number of key bits (e.g. 2048) +- rsa,modulus: Modulus (N) as a big-endian multi-word integer +- rsa,exponent: Public exponent (E) as a 64 bit unsigned integer +- rsa,r-squared: (2^num-bits)^2 as a big-endian multi-word integer +- rsa,n0-inverse: -1 / modulus[0] mod 2^32 + +For ECDSA the following are mandatory: +- ecdsa,curve: Name of ECDSA curve (e.g. "prime256v1") +- ecdsa,x-point: Public key X coordinate as a big-endian multi-word integer +- ecdsa,y-point: Public key Y coordinate as a big-endian multi-word integer + +These parameters can be added to a binary device tree using parameter -K of the +mkimage command:: + + tools/mkimage -f fit.its -K control.dtb -k keys -r image.fit + +Here is an example of a generated device tree node:: + + signature { + key-dev { + required = "conf"; + algo = "sha256,rsa2048"; + rsa,r-squared = <0xb76d1acf 0xa1763ca5 0xeb2f126 + 0x742edc80 0xd3f42177 0x9741d9d9 + 0x35bb476e 0xff41c718 0xd3801430 + 0xf22537cb 0xa7e79960 0xae32a043 + 0x7da1427a 0x341d6492 0x3c2762f5 + 0xaac04726 0x5b262d96 0xf984e86d + 0xb99443c7 0x17080c33 0x940f6892 + 0xd57a95d1 0x6ea7b691 0xc5038fa8 + 0x6bb48a6e 0x73f1b1ea 0x37160841 + 0xe05715ce 0xa7c45bbd 0x690d82d5 + 0x99c2454c 0x6ff117b3 0xd830683b + 0x3f81c9cf 0x1ca38a91 0x0c3392e4 + 0xd817c625 0x7b8e9a24 0x175b89ea + 0xad79f3dc 0x4d50d7b4 0x9d4e90f8 + 0xad9e2939 0xc165d6a4 0x0ada7e1b + 0xfb1bf495 0xfc3131c2 0xb8c6e604 + 0xc2761124 0xf63de4a6 0x0e9565f9 + 0xc8e53761 0x7e7a37a5 0xe99dcdae + 0x9aff7e1e 0xbd44b13d 0x6b0e6aa4 + 0x038907e4 0x8e0d6850 0xef51bc20 + 0xf73c94af 0x88bea7b1 0xcbbb1b30 + 0xd024b7f3>; + rsa,modulus = <0xc0711d6cb 0x9e86db7f 0x45986dbe + 0x023f1e8c9 0xe1a4c4d0 0x8a0dfdc9 + 0x023ba0c48 0x06815f6a 0x5caa0654 + 0x07078c4b7 0x3d154853 0x40729023 + 0x0b007c8fe 0x5a3647e5 0x23b41e20 + 0x024720591 0x66915305 0x0e0b29b0 + 0x0de2ad30d 0x8589430f 0xb1590325 + 0x0fb9f5d5e 0x9eba752a 0xd88e6de9 + 0x056b3dcc6 0x9a6b8e61 0x6784f61f + 0x000f39c21 0x5eec6b33 0xd78e4f78 + 0x0921a305f 0xaa2cc27e 0x1ca917af + 0x06e1134f4 0xd48cac77 0x4e914d07 + 0x0f707aa5a 0x0d141f41 0x84677f1d + 0x0ad47a049 0x028aedb6 0xd5536fcf + 0x03fef1e4f 0x133a03d2 0xfd7a750a + 0x0f9159732 0xd207812e 0x6a807375 + 0x06434230d 0xc8e22dad 0x9f29b3d6 + 0x07c44ac2b 0xfa2aad88 0xe2429504 + 0x041febd41 0x85d0d142 0x7b194d65 + 0x06e5d55ea 0x41116961 0xf3181dde + 0x068bf5fbc 0x3dd82047 0x00ee647e + 0x0d7a44ab3>; + rsa,exponent = <0x00 0x10001>; + rsa,n0-inverse = <0xb3928b85>; + rsa,num-bits = <0x800>; + key-name-hint = "dev"; + }; + }; + + +Signed Configurations +--------------------- +While signing images is useful, it does not provide complete protection +against several types of attack. For example, it it possible to create a +FIT with the same signed images, but with the configuration changed such +that a different one is selected (mix and match attack). It is also possible +to substitute a signed image from an older FIT version into a newer FIT +(roll-back attack). + +As an example, consider this FIT: + +/ { + images { + kernel-1 { + data = <data for kernel1> + signature-1 { + algo = "sha1,rsa2048"; + value = <...kernel signature 1...> + }; + }; + kernel-2 { + data = <data for kernel2> + signature-1 { + algo = "sha1,rsa2048"; + value = <...kernel signature 2...> + }; + }; + fdt-1 { + data = <data for fdt1>; + signature-1 { + algo = "sha1,rsa2048"; + vaue = <...fdt signature 1...> + }; + }; + fdt-2 { + data = <data for fdt2>; + signature-1 { + algo = "sha1,rsa2048"; + vaue = <...fdt signature 2...> + }; + }; + }; + configurations { + default = "conf-1"; + conf-1 { + kernel = "kernel-1"; + fdt = "fdt-1"; + }; + conf-2 { + kernel = "kernel-2"; + fdt = "fdt-2"; + }; + }; +}; + +Since both kernels are signed it is easy for an attacker to add a new +configuration 3 with kernel 1 and fdt 2: + + configurations { + default = "conf-1"; + conf-1 { + kernel = "kernel-1"; + fdt = "fdt-1"; + }; + conf-2 { + kernel = "kernel-2"; + fdt = "fdt-2"; + }; + conf-3 { + kernel = "kernel-1"; + fdt = "fdt-2"; + }; + }; + +With signed images, nothing protects against this. Whether it gains an +advantage for the attacker is debatable, but it is not secure. + +To solve this problem, we support signed configurations. In this case it +is the configurations that are signed, not the image. Each image has its +own hash, and we include the hash in the configuration signature. + +So the above example is adjusted to look like this: + +/ { + images { + kernel-1 { + data = <data for kernel1> + hash-1 { + algo = "sha1"; + value = <...kernel hash 1...> + }; + }; + kernel-2 { + data = <data for kernel2> + hash-1 { + algo = "sha1"; + value = <...kernel hash 2...> + }; + }; + fdt-1 { + data = <data for fdt1>; + hash-1 { + algo = "sha1"; + value = <...fdt hash 1...> + }; + }; + fdt-2 { + data = <data for fdt2>; + hash-1 { + algo = "sha1"; + value = <...fdt hash 2...> + }; + }; + }; + configurations { + default = "conf-1"; + conf-1 { + kernel = "kernel-1"; + fdt = "fdt-1"; + signature-1 { + algo = "sha1,rsa2048"; + value = <...conf 1 signature...>; + }; + }; + conf-2 { + kernel = "kernel-2"; + fdt = "fdt-2"; + signature-1 { + algo = "sha1,rsa2048"; + value = <...conf 1 signature...>; + }; + }; + }; +}; + + +You can see that we have added hashes for all images (since they are no +longer signed), and a signature to each configuration. In the above example, +mkimage will sign configurations/conf-1, the kernel and fdt that are +pointed to by the configuration (/images/kernel-1, /images/kernel-1/hash-1, +/images/fdt-1, /images/fdt-1/hash-1) and the root structure of the image +(so that it isn't possible to add or remove root nodes). The signature is +written into /configurations/conf-1/signature-1/value. It can easily be +verified later even if the FIT has been signed with other keys in the +meantime. + + +Verification +------------ +FITs are verified when loaded. After the configuration is selected a list +of required images is produced. If there are 'required' public keys, then +each image must be verified against those keys. This means that every image +that might be used by the target needs to be signed with 'required' keys. + +This happens automatically as part of a bootm command when FITs are used. + +For Signed Configurations, the default verification behavior can be changed by +the following optional property in /signature node in U-Boot's control FDT. + +- required-mode: Valid values are "any" to allow verified boot to succeed if +the selected configuration is signed by any of the 'required' keys, and "all" +to allow verified boot to succeed if the selected configuration is signed by +all of the 'required' keys. + +This property can be added to a binary device tree using fdtput as shown in +below examples:: + + fdtput -t s control.dtb /signature required-mode any + fdtput -t s control.dtb /signature required-mode all + + +Enabling FIT Verification +------------------------- +In addition to the options to enable FIT itself, the following CONFIGs must +be enabled: + +CONFIG_FIT_SIGNATURE - enable signing and verification in FITs +CONFIG_RSA - enable RSA algorithm for signing + +WARNING: When relying on signed FIT images with required signature check +the legacy image format is default disabled by not defining +CONFIG_LEGACY_IMAGE_FORMAT + + +Testing +------- +An easy way to test signing and verification is to use the test script +provided in test/vboot/vboot_test.sh. This uses sandbox (a special version +of U-Boot which runs under Linux) to show the operation of a 'bootm' +command loading and verifying images. + +A sample run is show below: + +$ make O=sandbox sandbox_config +$ make O=sandbox +$ O=sandbox ./test/vboot/vboot_test.sh + + +Simple Verified Boot Test +========================= + +Please see doc/uImage.FIT/verified-boot.txt for more information + +/home/hs/ids/u-boot/sandbox/tools/mkimage -D -I dts -O dtb -p 2000 +Build keys +do sha1 test +Build FIT with signed images +Test Verified Boot Run: unsigned signatures:: OK +Sign images +Test Verified Boot Run: signed images: OK +Build FIT with signed configuration +Test Verified Boot Run: unsigned config: OK +Sign images +Test Verified Boot Run: signed config: OK +check signed config on the host +Signature check OK +OK +Test Verified Boot Run: signed config: OK +Test Verified Boot Run: signed config with bad hash: OK +do sha256 test +Build FIT with signed images +Test Verified Boot Run: unsigned signatures:: OK +Sign images +Test Verified Boot Run: signed images: OK +Build FIT with signed configuration +Test Verified Boot Run: unsigned config: OK +Sign images +Test Verified Boot Run: signed config: OK +check signed config on the host +Signature check OK +OK +Test Verified Boot Run: signed config: OK +Test Verified Boot Run: signed config with bad hash: OK + +Test passed + + +Software signing: keydir vs keyfile +----------------------------------- + +In the simplest case, signing is done by giving mkimage the 'keyfile'. This is +the path to a file containing the signing key. + +The alternative is to pass the 'keydir' argument. In this case the filename of +the key is derived from the 'keydir' and the "key-name-hint" property in the +FIT. In this case the "key-name-hint" property is mandatory, and the key must +exist in "<keydir>/<key-name-hint>.<ext>" Here the extension "ext" is +specific to the signing algorithm. + + +Hardware Signing with PKCS#11 or with HSM +----------------------------------------- + +Securely managing private signing keys can challenging, especially when the +keys are stored on the file system of a computer that is connected to the +Internet. If an attacker is able to steal the key, they can sign malicious FIT +images which will appear genuine to your devices. + +An alternative solution is to keep your signing key securely stored on hardware +device like a smartcard, USB token or Hardware Security Module (HSM) and have +them perform the signing. PKCS#11 is standard for interfacing with these crypto +device. + +Requirements: +Smartcard/USB token/HSM which can work with some openssl engine +openssl + +For pkcs11 engine usage: +libp11 (provides pkcs11 engine) +p11-kit (recommended to simplify setup) +opensc (for smartcards and smartcard like USB devices) +gnutls (recommended for key generation, p11tool) + +For generic HSMs respective openssl engine must be installed and locateable by +openssl. This may require setting up LD_LIBRARY_PATH if engine is not installed +to openssl's default search paths. + +PKCS11 engine support forms "key id" based on "keydir" and with +"key-name-hint". "key-name-hint" is used as "object" name (if not defined in +keydir). "keydir" (if defined) is used to define (prefix for) which PKCS11 source +is being used for lookup up for the key. + +PKCS11 engine key ids: + "pkcs11:<keydir>;object=<key-name-hint>;type=<public|private>" +or, if keydir contains "object=" + "pkcs11:<keydir>;type=<public|private>" +or + "pkcs11:object=<key-name-hint>;type=<public|private>", + +Generic HSM engine support forms "key id" based on "keydir" and with +"key-name-hint". If "keydir" is specified for mkimage it is used as a prefix in +"key id" and is appended with "key-name-hint". + +Generic engine key ids: + "<keydir><key-name-hint>" +or + "<key-name-hint>" + +As mkimage does not at this time support prompting for passwords HSM may need +key preloading wrapper to be used when invoking mkimage. + +The following examples use the Nitrokey Pro using pkcs11 engine. Instructions +for other devices may vary. + +Notes on pkcs11 engine setup: + +Make sure p11-kit, opensc are installed and that p11-kit is setup to use opensc. +/usr/share/p11-kit/modules/opensc.module should be present on your system. + + +Generating Keys On the Nitrokey: + +$ gpg --card-edit + +Reader ...........: Nitrokey Nitrokey Pro (xxxxxxxx0000000000000000) 00 00 +Application ID ...: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx +Version ..........: 2.1 +Manufacturer .....: ZeitControl +Serial number ....: xxxxxxxx +Name of cardholder: [not set] +Language prefs ...: de +Sex ..............: unspecified +URL of public key : [not set] +Login data .......: [not set] +Signature PIN ....: forced +Key attributes ...: rsa2048 rsa2048 rsa2048 +Max. PIN lengths .: 32 32 32 +PIN retry counter : 3 0 3 +Signature counter : 0 +Signature key ....: [none] +Encryption key....: [none] +Authentication key: [none] +General key info..: [none] + +gpg/card> generate +Make off-card backup of encryption key? (Y/n) n + +Please note that the factory settings of the PINs are + PIN = '123456' Admin PIN = '12345678' +You should change them using the command --change-pin + +What keysize do you want for the Signature key? (2048) 4096 +The card will now be re-configured to generate a key of 4096 bits +Note: There is no guarantee that the card supports the requested size. + If the key generation does not succeed, please check the + documentation of your card to see what sizes are allowed. +What keysize do you want for the Encryption key? (2048) 4096 +The card will now be re-configured to generate a key of 4096 bits +What keysize do you want for the Authentication key? (2048) 4096 +The card will now be re-configured to generate a key of 4096 bits +Please specify how long the key should be valid. + 0 = key does not expire + <n> = key expires in n days + <n>w = key expires in n weeks + <n>m = key expires in n months + <n>y = key expires in n years +Key is valid for? (0) +Key does not expire at all +Is this correct? (y/N) y + +GnuPG needs to construct a user ID to identify your key. + +Real name: John Doe +Email address: john.doe@email.com +Comment: +You selected this USER-ID: + "John Doe <john.doe@email.com>" + +Change (N)ame, (C)omment, (E)mail or (O)kay/(Q)uit? o + + +Using p11tool to get the token URL: + +Depending on system configuration, gpg-agent may need to be killed first. + +$ p11tool --provider /usr/lib/opensc-pkcs11.so --list-tokens +Token 0: +URL: pkcs11:model=PKCS%2315%20emulated;manufacturer=ZeitControl;serial=000xxxxxxxxx;token=OpenPGP%20card%20%28User%20PIN%20%28sig%29%29 +Label: OpenPGP card (User PIN (sig)) +Type: Hardware token +Manufacturer: ZeitControl +Model: PKCS#15 emulated +Serial: 000xxxxxxxxx +Module: (null) + + +Token 1: +URL: pkcs11:model=PKCS%2315%20emulated;manufacturer=ZeitControl;serial=000xxxxxxxxx;token=OpenPGP%20card%20%28User%20PIN%29 +Label: OpenPGP card (User PIN) +Type: Hardware token +Manufacturer: ZeitControl +Model: PKCS#15 emulated +Serial: 000xxxxxxxxx +Module: (null) + +Use the portion of the signature token URL after "pkcs11:" as the keydir argument (-k) to mkimage below. + + +Use the URL of the token to list the private keys: + +$ p11tool --login --provider /usr/lib/opensc-pkcs11.so --list-privkeys \ +"pkcs11:model=PKCS%2315%20emulated;manufacturer=ZeitControl;serial=000xxxxxxxxx;token=OpenPGP%20card%20%28User%20PIN%20%28sig%29%29" +Token 'OpenPGP card (User PIN (sig))' with URL 'pkcs11:model=PKCS%2315%20emulated;manufacturer=ZeitControl;serial=000xxxxxxxxx;token=OpenPGP%20card%20%28User%20PIN%20%28sig%29%29' requires user PIN +Enter PIN: +Object 0: +URL: pkcs11:model=PKCS%2315%20emulated;manufacturer=ZeitControl;serial=000xxxxxxxxx;token=OpenPGP%20card%20%28User%20PIN%20%28sig%29%29;id=%01;object=Signature%20key;type=private +Type: Private key +Label: Signature key +Flags: CKA_PRIVATE; CKA_NEVER_EXTRACTABLE; CKA_SENSITIVE; +ID: 01 + +Use the label, in this case "Signature key" as the key-name-hint in your FIT. + +Create the fitImage: +$ ./tools/mkimage -f fit-image.its fitImage + + +Sign the fitImage with the hardware key: + +$ ./tools/mkimage -F -k \ +"model=PKCS%2315%20emulated;manufacturer=ZeitControl;serial=000xxxxxxxxx;token=OpenPGP%20card%20%28User%20PIN%20%28sig%29%29" \ +-K u-boot.dtb -N pkcs11 -r fitImage + + +Future Work +----------- +- Roll-back protection using a TPM is done using the tpm command. This can +be scripted, but we might consider a default way of doing this, built into +bootm. + + +Possible Future Work +-------------------- +- Add support for other RSA/SHA variants, such as rsa4096,sha512. +- Other algorithms besides RSA +- More sandbox tests for failure modes +- Passwords for keys/certificates +- Perhaps implement OAEP +- Enhance bootm to permit scripted signature verification (so that a script +can verify an image but not actually boot it) + + +Simon Glass +sjg@chromium.org +1-1-13 diff --git a/roms/u-boot/doc/uImage.FIT/source_file_format.txt b/roms/u-boot/doc/uImage.FIT/source_file_format.txt new file mode 100644 index 000000000..f93ac6d1c --- /dev/null +++ b/roms/u-boot/doc/uImage.FIT/source_file_format.txt @@ -0,0 +1,311 @@ +U-Boot new uImage source file format (bindings definition) +========================================================== + +Author: Marian Balakowicz <m8@semihalf.com> +External data additions, 25/1/16 Simon Glass <sjg@chromium.org> + +1) Introduction +--------------- + +Evolution of the 2.6 Linux kernel for embedded PowerPC systems introduced new +booting method which requires that hardware description is available to the +kernel in the form of Flattened Device Tree. + +Booting with a Flattened Device Tree is much more flexible and is intended to +replace direct passing of 'struct bd_info' which was used to boot pre-FDT +kernels. + +However, U-Boot needs to support both techniques to provide backward +compatibility for platforms which are not FDT ready. Number of elements +playing role in the booting process has increased and now includes the FDT +blob. Kernel image, FDT blob and possibly ramdisk image - all must be placed +in the system memory and passed to bootm as a arguments. Some of them may be +missing: FDT is not present for legacy platforms, ramdisk is always optional. +Additionally, old uImage format has been extended to support multi sub-images +but the support is limited by simple format of the legacy uImage structure. +Single binary header 'struct image_header' is not flexible enough to cover all +possible scenarios. + +All those factors combined clearly show that there is a need for new, more +flexible, multi component uImage format. + + +2) New uImage format assumptions +-------------------------------- + +a) Implementation + +Libfdt has been selected for the new uImage format implementation as (1) it +provides needed functionality, (2) is actively maintained and developed and +(3) increases code reuse as it is already part of the U-Boot source tree. + +b) Terminology + +This document defines new uImage structure by providing FDT bindings for new +uImage internals. Bindings are defined from U-Boot perspective, i.e. describe +final form of the uImage at the moment when it reaches U-Boot. User +perspective may be simpler, as some of the properties (like timestamps and +hashes) will need to be filled in automatically by the U-Boot mkimage tool. + +To avoid confusion with the kernel FDT the following naming convention is +proposed for the new uImage format related terms: + +FIT - Flattened uImage Tree + +FIT is formally a flattened device tree (in the libfdt meaning), which +conforms to bindings defined in this document. + +.its - image tree source +.itb - flattened image tree blob + +c) Image building procedure + +The following picture shows how the new uImage is prepared. Input consists of +image source file (.its) and a set of data files. Image is created with the +help of standard U-Boot mkimage tool which in turn uses dtc (device tree +compiler) to produce image tree blob (.itb). Resulting .itb file is the +actual binary of a new uImage. + + +tqm5200.its ++ +vmlinux.bin.gz mkimage + dtc xfer to target +eldk-4.2-ramdisk --------------> tqm5200.itb --------------> bootm +tqm5200.dtb /|\ +... | + 'new uImage' + + - create .its file, automatically filled-in properties are omitted + - call mkimage tool on a .its file + - mkimage calls dtc to create .itb image and assures that + missing properties are added + - .itb (new uImage) is uploaded onto the target and used therein + + +d) Unique identifiers + +To identify FIT sub-nodes representing images, hashes, configurations (which +are defined in the following sections), the "unit name" of the given sub-node +is used as it's identifier as it assures uniqueness without additional +checking required. + + +3) Root node properties +----------------------- + +Root node of the uImage Tree should have the following layout: + +/ o image-tree + |- description = "image description" + |- timestamp = <12399321> + |- #address-cells = <1> + | + o images + | | + | o image-1 {...} + | o image-2 {...} + | ... + | + o configurations + |- default = "conf-1" + | + o conf-1 {...} + o conf-2 {...} + ... + + + Optional property: + - description : Textual description of the uImage + + Mandatory property: + - timestamp : Last image modification time being counted in seconds since + 1970-01-01 00:00:00 - to be automatically calculated by mkimage tool. + + Conditionally mandatory property: + - #address-cells : Number of 32bit cells required to represent entry and + load addresses supplied within sub-image nodes. May be omitted when no + entry or load addresses are used. + + Mandatory nodes: + - images : This node contains a set of sub-nodes, each of them representing + single component sub-image (like kernel, ramdisk, etc.). At least one + sub-image is required. + - configurations : Contains a set of available configuration nodes and + defines a default configuration. + + +4) '/images' node +----------------- + +This node is a container node for component sub-image nodes. Each sub-node of +the '/images' node should have the following layout: + + o image-1 + |- description = "component sub-image description" + |- data = /incbin/("path/to/data/file.bin") + |- type = "sub-image type name" + |- arch = "ARCH name" + |- os = "OS name" + |- compression = "compression name" + |- load = <00000000> + |- entry = <00000000> + | + o hash-1 {...} + o hash-2 {...} + ... + + Mandatory properties: + - description : Textual description of the component sub-image + - type : Name of component sub-image type, supported types are: + "standalone", "kernel", "kernel_noload", "ramdisk", "firmware", "script", + "filesystem", "flat_dt" and others (see uimage_type in common/image.c). + - data : Path to the external file which contains this node's binary data. + - compression : Compression used by included data. Supported compressions + are "gzip" and "bzip2". If no compression is used compression property + should be set to "none". If the data is compressed but it should not be + uncompressed by U-Boot (e.g. compressed ramdisk), this should also be set + to "none". + + Conditionally mandatory property: + - os : OS name, mandatory for types "kernel". Valid OS names are: + "openbsd", "netbsd", "freebsd", "4_4bsd", "linux", "svr4", "esix", + "solaris", "irix", "sco", "dell", "ncr", "lynxos", "vxworks", "psos", "qnx", + "u-boot", "rtems", "unity", "integrity". + - arch : Architecture name, mandatory for types: "standalone", "kernel", + "firmware", "ramdisk" and "fdt". Valid architecture names are: "alpha", + "arm", "i386", "ia64", "mips", "mips64", "ppc", "s390", "sh", "sparc", + "sparc64", "m68k", "microblaze", "nios2", "blackfin", "avr32", "st200", + "sandbox". + - entry : entry point address, address size is determined by + '#address-cells' property of the root node. + Mandatory for types: "firmware", and "kernel". + - load : load address, address size is determined by '#address-cells' + property of the root node. + Mandatory for types: "firmware", and "kernel". + - compatible : compatible method for loading image. + Mandatory for types: "fpga", and images that do not specify a load address. + To use the generic fpga loading routine, use "u-boot,fpga-legacy". + + Optional nodes: + - hash-1 : Each hash sub-node represents separate hash or checksum + calculated for node's data according to specified algorithm. + + +5) Hash nodes +------------- + +o hash-1 + |- algo = "hash or checksum algorithm name" + |- value = [hash or checksum value] + + Mandatory properties: + - algo : Algorithm name, supported are "crc32", "md5" and "sha1". + - value : Actual checksum or hash value, correspondingly 4, 16 or 20 bytes + long. + + +6) '/configurations' node +------------------------- + +The 'configurations' node creates convenient, labeled boot configurations, +which combine together kernel images with their ramdisks and fdt blobs. + +The 'configurations' node has has the following structure: + +o configurations + |- default = "default configuration sub-node unit name" + | + o config-1 {...} + o config-2 {...} + ... + + + Optional property: + - default : Selects one of the configuration sub-nodes as a default + configuration. + + Mandatory nodes: + - configuration-sub-node-unit-name : At least one of the configuration + sub-nodes is required. + + +7) Configuration nodes +---------------------- + +Each configuration has the following structure: + +o config-1 + |- description = "configuration description" + |- kernel = "kernel sub-node unit name" + |- fdt = "fdt sub-node unit-name" [, "fdt overlay sub-node unit-name", ...] + |- loadables = "loadables sub-node unit-name" + |- compatible = "vendor,board-style device tree compatible string" + + + Mandatory properties: + - description : Textual configuration description. + - kernel or firmware: Unit name of the corresponding kernel or firmware + (u-boot, op-tee, etc) image. If both "kernel" and "firmware" are specified, + control is passed to the firmware image. + + Optional properties: + - fdt : Unit name of the corresponding fdt blob (component image node of a + "fdt type"). Additional fdt overlay nodes can be supplied which signify + that the resulting device tree blob is generated by the first base fdt + blob with all subsequent overlays applied. + - fpga : Unit name of the corresponding fpga bitstream blob + (component image node of a "fpga type"). + - loadables : Unit name containing a list of additional binaries to be + loaded at their given locations. "loadables" is a comma-separated list + of strings. U-Boot will load each binary at its given start-address and + may optionally invoke additional post-processing steps on this binary based + on its component image node type. + - compatible : The root compatible string of the U-Boot device tree that + this configuration shall automatically match when CONFIG_FIT_BEST_MATCH is + enabled. If this property is not provided, the compatible string will be + extracted from the fdt blob instead. This is only possible if the fdt is + not compressed, so images with compressed fdts that want to use compatible + string matching must always provide this property. + +The FDT blob is required to properly boot FDT based kernel, so the minimal +configuration for 2.6 FDT kernel is (kernel, fdt) pair. + +Older, 2.4 kernel and 2.6 non-FDT kernel do not use FDT blob, in such cases +'struct bd_info' must be passed instead of FDT blob, thus fdt property *must +not* be specified in a configuration node. + + +8) External data +---------------- + +The above format shows a 'data' property which holds the data for each image. +It is also possible for this data to reside outside the FIT itself. This +allows the FIT to be quite small, so that it can be loaded and scanned +without loading a large amount of data. Then when an image is needed it can +be loaded from an external source. + +In this case the 'data' property is omitted. Instead you can use: + + - data-offset : offset of the data in a separate image store. The image + store is placed immediately after the last byte of the device tree binary, + aligned to a 4-byte boundary. + - data-size : size of the data in bytes + +The 'data-offset' property can be substituted with 'data-position', which +defines an absolute position or address as the offset. This is helpful when +booting U-Boot proper before performing relocation. Pass '-p [offset]' to +mkimage to enable 'data-position'. + +Normal kernel FIT image has data embedded within FIT structure. U-Boot image +for SPL boot has external data. Existence of 'data-offset' can be used to +identify which format is used. + +For FIT image with external data, it would be better to align each blob of data +to block(512 byte) for block device, so that we don't need to do the copy when +read the image data in SPL. Pass '-B 0x200' to mkimage to align the FIT +structure and data to 512 byte, other values available for other align size. + +9) Examples +----------- + +Please see doc/uImage.FIT/*.its for actual image source files. diff --git a/roms/u-boot/doc/uImage.FIT/uefi.its b/roms/u-boot/doc/uImage.FIT/uefi.its new file mode 100644 index 000000000..378ca4ed8 --- /dev/null +++ b/roms/u-boot/doc/uImage.FIT/uefi.its @@ -0,0 +1,67 @@ +/* + * Example FIT image description file demonstrating the usage of the + * bootm command to launch UEFI binaries. + * + * Two boot configurations are available to enable booting GRUB2 on QEMU, + * the former uses a FDT blob contained in the FIT image, while the later + * relies on the FDT provided by the board emulator. + */ + +/dts-v1/; + +/ { + description = "GRUB2 EFI and QEMU FDT blob"; + #address-cells = <1>; + + images { + efi-grub { + description = "GRUB EFI Firmware"; + data = /incbin/("bootarm.efi"); + type = "kernel_noload"; + arch = "arm"; + os = "efi"; + compression = "none"; + load = <0x0>; + entry = <0x0>; + hash-1 { + algo = "sha256"; + }; + }; + + fdt-qemu { + description = "QEMU DTB"; + data = /incbin/("qemu-arm.dtb"); + type = "flat_dt"; + arch = "arm"; + compression = "none"; + hash-1 { + algo = "sha256"; + }; + }; + }; + + configurations { + default = "config-grub-fdt"; + + config-grub-fdt { + description = "GRUB EFI Boot w/ FDT"; + kernel = "efi-grub"; + fdt = "fdt-qemu"; + signature-1 { + algo = "sha256,rsa2048"; + key-name-hint = "dev"; + sign-images = "kernel", "fdt"; + }; + }; + + config-grub-nofdt { + description = "GRUB EFI Boot w/o FDT"; + kernel = "efi-grub"; + signature-1 { + algo = "sha256,rsa2048"; + key-name-hint = "dev"; + sign-images = "kernel"; + }; + }; + }; +}; diff --git a/roms/u-boot/doc/uImage.FIT/update3.its b/roms/u-boot/doc/uImage.FIT/update3.its new file mode 100644 index 000000000..0659f2000 --- /dev/null +++ b/roms/u-boot/doc/uImage.FIT/update3.its @@ -0,0 +1,44 @@ +/* + * Example Automatic software update file. + */ + +/dts-v1/; + +/ { + description = "Automatic software updates: kernel, ramdisk, FDT"; + #address-cells = <1>; + + images { + update-1 { + description = "Linux kernel binary"; + data = /incbin/("./vmlinux.bin.gz"); + compression = "none"; + type = "firmware"; + load = <FF700000>; + hash-1 { + algo = "sha1"; + }; + }; + update-2 { + description = "Ramdisk image"; + data = /incbin/("./ramdisk_image.gz"); + compression = "none"; + type = "firmware"; + load = <FF8E0000>; + hash-1 { + algo = "sha1"; + }; + }; + + update-3 { + description = "FDT blob"; + data = /incbin/("./blob.fdt"); + compression = "none"; + type = "firmware"; + load = <FFAC0000>; + hash-1 { + algo = "sha1"; + }; + }; + }; +}; diff --git a/roms/u-boot/doc/uImage.FIT/update_uboot.its b/roms/u-boot/doc/uImage.FIT/update_uboot.its new file mode 100644 index 000000000..aec482600 --- /dev/null +++ b/roms/u-boot/doc/uImage.FIT/update_uboot.its @@ -0,0 +1,24 @@ +/* + * Automatic software update for U-Boot + * Make sure the flashing addresses ('load' prop) is correct for your board! + */ + +/dts-v1/; + +/ { + description = "Automatic U-Boot update"; + #address-cells = <1>; + + images { + update-1 { + description = "U-Boot binary"; + data = /incbin/("./u-boot.bin"); + compression = "none"; + type = "firmware"; + load = <0xFFFC0000>; + hash-1 { + algo = "sha1"; + }; + }; + }; +}; diff --git a/roms/u-boot/doc/uImage.FIT/verified-boot.txt b/roms/u-boot/doc/uImage.FIT/verified-boot.txt new file mode 100644 index 000000000..41c9fa9e0 --- /dev/null +++ b/roms/u-boot/doc/uImage.FIT/verified-boot.txt @@ -0,0 +1,104 @@ +U-Boot Verified Boot +==================== + +Introduction +------------ +Verified boot here means the verification of all software loaded into a +machine during the boot process to ensure that it is authorised and correct +for that machine. + +Verified boot extends from the moment of system reset to as far as you wish +into the boot process. An example might be loading U-Boot from read-only +memory, then loading a signed kernel, then using the kernel's dm-verity +driver to mount a signed root filesystem. + +A key point is that it is possible to field-upgrade the software on machines +which use verified boot. Since the machine will only run software that has +been correctly signed, it is safe to read software from an updatable medium. +It is also possible to add a secondary signed firmware image, in read-write +memory, so that firmware can easily be upgraded in a secure manner. + + +Signing +------- +Verified boot uses cryptographic algorithms to 'sign' software images. +Images are signed using a private key known only to the signer, but can +be verified using a public key. As its name suggests the public key can be +made available without risk to the verification process. The private and +public keys are mathematically related. For more information on how this +works look up "public key cryptography" and "RSA" (a particular algorithm). + +The signing and verification process looks something like this: + + + Signing Verification + ======= ============ + + +--------------+ * + | RSA key pair | * +---------------+ + | .key .crt | * | Public key in | + +--------------+ +------> public key ----->| trusted place | + | | * +---------------+ + | | * | + v | * v + +---------+ | * +--------------+ + | |----------+ * | | + | signer | * | U-Boot | + | |----------+ * | signature |--> yes/no + +---------+ | * | verification | + ^ | * | | + | | * +--------------+ + | | * ^ + +----------+ | * | + | Software | +----> signed image -------------+ + | image | * + +----------+ * + + +The signature algorithm relies only on the public key to do its work. Using +this key it checks the signature that it finds in the image. If it verifies +then we know that the image is OK. + +The public key from the signer allows us to verify and therefore trust +software from updatable memory. + +It is critical that the public key be secure and cannot be tampered with. +It can be stored in read-only memory, or perhaps protected by other on-chip +crypto provided by some modern SOCs. If the public key can be changed, then +the verification is worthless. + + +Chaining Images +--------------- +The above method works for a signer providing images to a run-time U-Boot. +It is also possible to extend this scheme to a second level, like this: + +1. Master private key is used by the signer to sign a first-stage image. +2. Master public key is placed in read-only memory. +2. Secondary private key is created and used to sign second-stage images. +3. Secondary public key is placed in first stage images +4. We use the master public key to verify the first-stage image. We then +use the secondary public key in the first-stage image to verify the second- +state image. +5. This chaining process can go on indefinitely. It is recommended to use a +different key at each stage, so that a compromise in one place will not +affect the whole change. + + +Flattened Image Tree (FIT) +-------------------------- +The FIT format is already widely used in U-Boot. It is a flattened device +tree (FDT) in a particular format, with images contained within. FITs +include hashes to verify images, so it is relatively straightforward to +add signatures as well. + +The public key can be stored in U-Boot's CONFIG_OF_CONTROL device tree in +a standard place. Then when a FIT is loaded it can be verified using that +public key. Multiple keys and multiple signatures are supported. + +See signature.txt for more information. + + +Simon Glass +sjg@chromium.org +1-1-13 diff --git a/roms/u-boot/doc/uImage.FIT/x86-fit-boot.txt b/roms/u-boot/doc/uImage.FIT/x86-fit-boot.txt new file mode 100644 index 000000000..88d3460a8 --- /dev/null +++ b/roms/u-boot/doc/uImage.FIT/x86-fit-boot.txt @@ -0,0 +1,272 @@ +Booting Linux on x86 with FIT +============================= + +Background +---------- + +(corrections to the text below are welcome) + +Generally Linux x86 uses its own very complex booting method. There is a setup +binary which contains all sorts of parameters and a compressed self-extracting +binary for the kernel itself, often with a small built-in serial driver to +display decompression progress. + +The x86 CPU has various processor modes. I am no expert on these, but my +understanding is that an x86 CPU (even a really new one) starts up in a 16-bit +'real' mode where only 1MB of memory is visible, moves to 32-bit 'protected' +mode where 4GB is visible (or more with special memory access techniques) and +then to 64-bit 'long' mode if 64-bit execution is required. + +Partly the self-extracting nature of Linux was introduced to cope with boot +loaders that were barely capable of loading anything. Even changing to 32-bit +mode was something of a challenge, so putting this logic in the kernel seemed +to make sense. + +Bit by bit more and more logic has been added to this post-boot pre-Linux +wrapper: + +- Changing to 32-bit mode +- Decompression +- Serial output (with drivers for various chips) +- Load address randomisation +- Elf loader complete with relocation (for the above) +- Random number generator via 3 methods (again for the above) +- Some sort of EFI mini-loader (1000+ glorious lines of code) +- Locating and tacking on a device tree and ramdisk + +To my mind, if you sit back and look at things from first principles, this +doesn't make a huge amount of sense. Any boot loader worth its salts already +has most of the above features and more besides. The boot loader already knows +the layout of memory, has a serial driver, can decompress things, includes an +ELF loader and supports device tree and ramdisks. The decision to duplicate +all these features in a Linux wrapper caters for the lowest common +denominator: a boot loader which consists of a BIOS call to load something off +disk, followed by a jmp instruction. + +(Aside: On ARM systems, we worry that the boot loader won't know where to load +the kernel. It might be easier to just provide that information in the image, +or in the boot loader rather than adding a self-relocator to put it in the +right place. Or just use ELF? + +As a result, the x86 kernel boot process is needlessly complex. The file +format is also complex, and obfuscates the contents to a degree that it is +quite a challenge to extract anything from it. This bzImage format has become +so prevalent that is actually isn't possible to produce the 'raw' kernel build +outputs with the standard Makefile (as it is on ARM for example, at least at +the time of writing). + +This document describes an alternative boot process which uses simple raw +images which are loaded into the right place by the boot loader and then +executed. + + +Build the kernel +---------------- + +Note: these instructions assume a 32-bit kernel. U-Boot also supports directly +booting a 64-bit kernel by jumping into 64-bit mode first (see below). + +You can build the kernel as normal with 'make'. This will create a file called +'vmlinux'. This is a standard ELF file and you can look at it if you like: + +$ objdump -h vmlinux + +vmlinux: file format elf32-i386 + +Sections: +Idx Name Size VMA LMA File off Algn + 0 .text 00416850 81000000 01000000 00001000 2**5 + CONTENTS, ALLOC, LOAD, RELOC, READONLY, CODE + 1 .notes 00000024 81416850 01416850 00417850 2**2 + CONTENTS, ALLOC, LOAD, READONLY, CODE + 2 __ex_table 00000c50 81416880 01416880 00417880 2**3 + CONTENTS, ALLOC, LOAD, RELOC, READONLY, DATA + 3 .rodata 00154b9e 81418000 01418000 00419000 2**5 + CONTENTS, ALLOC, LOAD, RELOC, READONLY, DATA + 4 __bug_table 0000597c 8156cba0 0156cba0 0056dba0 2**0 + CONTENTS, ALLOC, LOAD, RELOC, READONLY, DATA + 5 .pci_fixup 00001b80 8157251c 0157251c 0057351c 2**2 + CONTENTS, ALLOC, LOAD, RELOC, READONLY, DATA + 6 .tracedata 00000024 8157409c 0157409c 0057509c 2**0 + CONTENTS, ALLOC, LOAD, RELOC, READONLY, DATA + 7 __ksymtab 00007ec0 815740c0 015740c0 005750c0 2**2 + CONTENTS, ALLOC, LOAD, RELOC, READONLY, DATA + 8 __ksymtab_gpl 00004a28 8157bf80 0157bf80 0057cf80 2**2 + CONTENTS, ALLOC, LOAD, RELOC, READONLY, DATA + 9 __ksymtab_strings 0001d6fc 815809a8 015809a8 005819a8 2**0 + CONTENTS, ALLOC, LOAD, READONLY, DATA + 10 __init_rodata 00001c3c 8159e0a4 0159e0a4 0059f0a4 2**2 + CONTENTS, ALLOC, LOAD, RELOC, READONLY, DATA + 11 __param 00000ff0 8159fce0 0159fce0 005a0ce0 2**2 + CONTENTS, ALLOC, LOAD, RELOC, READONLY, DATA + 12 __modver 00000330 815a0cd0 015a0cd0 005a1cd0 2**2 + CONTENTS, ALLOC, LOAD, RELOC, READONLY, DATA + 13 .data 00063000 815a1000 015a1000 005a2000 2**12 + CONTENTS, ALLOC, LOAD, RELOC, DATA + 14 .init.text 0002f104 81604000 01604000 00605000 2**2 + CONTENTS, ALLOC, LOAD, RELOC, READONLY, CODE + 15 .init.data 00040cdc 81634000 01634000 00635000 2**12 + CONTENTS, ALLOC, LOAD, RELOC, DATA + 16 .x86_cpu_dev.init 0000001c 81674cdc 01674cdc 00675cdc 2**2 + CONTENTS, ALLOC, LOAD, RELOC, READONLY, DATA + 17 .altinstructions 0000267c 81674cf8 01674cf8 00675cf8 2**0 + CONTENTS, ALLOC, LOAD, RELOC, READONLY, DATA + 18 .altinstr_replacement 00000942 81677374 01677374 00678374 2**0 + CONTENTS, ALLOC, LOAD, READONLY, CODE + 19 .iommu_table 00000014 81677cb8 01677cb8 00678cb8 2**2 + CONTENTS, ALLOC, LOAD, RELOC, READONLY, DATA + 20 .apicdrivers 00000004 81677cd0 01677cd0 00678cd0 2**2 + CONTENTS, ALLOC, LOAD, RELOC, DATA + 21 .exit.text 00001a80 81677cd8 01677cd8 00678cd8 2**0 + CONTENTS, ALLOC, LOAD, RELOC, READONLY, CODE + 22 .data..percpu 00007880 8167a000 0167a000 0067b000 2**12 + CONTENTS, ALLOC, LOAD, RELOC, DATA + 23 .smp_locks 00003000 81682000 01682000 00683000 2**2 + CONTENTS, ALLOC, LOAD, RELOC, READONLY, DATA + 24 .bss 000a1000 81685000 01685000 00686000 2**12 + ALLOC + 25 .brk 00424000 81726000 01726000 00686000 2**0 + ALLOC + 26 .comment 00000049 00000000 00000000 00686000 2**0 + CONTENTS, READONLY + 27 .GCC.command.line 0003e055 00000000 00000000 00686049 2**0 + CONTENTS, READONLY + 28 .debug_aranges 0000f4c8 00000000 00000000 006c40a0 2**3 + CONTENTS, RELOC, READONLY, DEBUGGING + 29 .debug_info 0440b0df 00000000 00000000 006d3568 2**0 + CONTENTS, RELOC, READONLY, DEBUGGING + 30 .debug_abbrev 0022a83b 00000000 00000000 04ade647 2**0 + CONTENTS, READONLY, DEBUGGING + 31 .debug_line 004ead0d 00000000 00000000 04d08e82 2**0 + CONTENTS, RELOC, READONLY, DEBUGGING + 32 .debug_frame 0010a960 00000000 00000000 051f3b90 2**2 + CONTENTS, RELOC, READONLY, DEBUGGING + 33 .debug_str 001b442d 00000000 00000000 052fe4f0 2**0 + CONTENTS, READONLY, DEBUGGING + 34 .debug_loc 007c7fa9 00000000 00000000 054b291d 2**0 + CONTENTS, RELOC, READONLY, DEBUGGING + 35 .debug_ranges 00098828 00000000 00000000 05c7a8c8 2**3 + CONTENTS, RELOC, READONLY, DEBUGGING + +There is also the setup binary mentioned earlier. This is at +arch/x86/boot/setup.bin and is about 12KB in size. It includes the command +line and various settings need by the kernel. Arguably the boot loader should +provide all of this also, but setting it up is some complex that the kernel +helps by providing a head start. + +As you can see the code loads to address 0x01000000 and everything else +follows after that. We could load this image using the 'bootelf' command but +we would still need to provide the setup binary. This is not supported by +U-Boot although I suppose you could mostly script it. This would permit the +use of a relocatable kernel. + +All we need to boot is the vmlinux file and the setup.bin file. + + +Create a FIT +------------ + +To create a FIT you will need a source file describing what should go in the +FIT. See kernel.its for an example for x86 and also instructions on setting +the 'arch' value for booting 64-bit kernels if desired. Put this into a file +called image.its. + +Note that setup is loaded to the special address of 0x90000 (a special address +you just have to know) and the kernel is loaded to 0x01000000 (the address you +saw above). This means that you will need to load your FIT to a different +address so that U-Boot doesn't overwrite it when decompressing. Something like +0x02000000 will do so you can set CONFIG_SYS_LOAD_ADDR to that. + +In that example the kernel is compressed with lzo. Also we need to provide a +flat binary, not an ELF. So the steps needed to set things are are: + + # Create a flat binary + objcopy -O binary vmlinux vmlinux.bin + + # Compress it into LZO format + lzop vmlinux.bin + + # Build a FIT image + mkimage -f image.its image.fit + +(be careful to run the mkimage from your U-Boot tools directory since it +will have x86_setup support.) + +You can take a look at the resulting fit file if you like: + +$ dumpimage -l image.fit +FIT description: Simple image with single Linux kernel on x86 +Created: Tue Oct 7 10:57:24 2014 + Image 0 (kernel) + Description: Vanilla Linux kernel + Created: Tue Oct 7 10:57:24 2014 + Type: Kernel Image + Compression: lzo compressed + Data Size: 4591767 Bytes = 4484.15 kB = 4.38 MB + Architecture: Intel x86 + OS: Linux + Load Address: 0x01000000 + Entry Point: 0x00000000 + Hash algo: sha1 + Hash value: 446b5163ebfe0fb6ee20cbb7a8501b263cd92392 + Image 1 (setup) + Description: Linux setup.bin + Created: Tue Oct 7 10:57:24 2014 + Type: x86 setup.bin + Compression: uncompressed + Data Size: 12912 Bytes = 12.61 kB = 0.01 MB + Hash algo: sha1 + Hash value: a1f2099cf47ff9816236cd534c77af86e713faad + Default Configuration: 'config-1' + Configuration 0 (config-1) + Description: Boot Linux kernel + Kernel: kernel + + +Booting the FIT +--------------- + +To make it boot you need to load it and then use 'bootm' to boot it. A +suitable script to do this from a network server is: + + bootp + tftp image.fit + bootm + +This will load the image from the network and boot it. The command line (from +the 'bootargs' environment variable) will be passed to the kernel. + +If you want a ramdisk you can add it as normal with FIT. If you want a device +tree then x86 doesn't normally use those - it has ACPI instead. + + +Why Bother? +----------- + +1. It demystifies the process of booting an x86 kernel +2. It allows use of the standard U-Boot boot file format +3. It allows U-Boot to perform decompression - problems will provide an error +message and you are still in the boot loader. It is possible to investigate. +4. It avoids all the pre-loader code in the kernel which is quite complex to +follow +5. You can use verified/secure boot and other features which haven't yet been +added to the pre-Linux +6. It makes x86 more like other architectures in the way it boots a kernel. +You can potentially use the same file format for the kernel, and the same +procedure for building and packaging it. + + +References +---------- + +In the Linux kernel, Documentation/x86/boot.txt defines the boot protocol for +the kernel including the setup.bin format. This is handled in U-Boot in +arch/x86/lib/zimage.c and arch/x86/lib/bootm.c. + +Various files in the same directory as this file describe the FIT format. + + +-- +Simon Glass +sjg@chromium.org +7-Oct-2014 diff --git a/roms/u-boot/doc/usage/addrmap.rst b/roms/u-boot/doc/usage/addrmap.rst new file mode 100644 index 000000000..472fd547f --- /dev/null +++ b/roms/u-boot/doc/usage/addrmap.rst @@ -0,0 +1,41 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +addrmap command +=============== + +Synopsis +-------- + +:: + + addrmap + +Description +----------- + +The addrmap command is used to display non-identity virtual-physical memory +mappings for 32-bit CPUs. + +The output may look like: + +:: + + => addrmap + vaddr paddr size + ================ ================ ================ + e0000000 fe0000000 00100000 + 00000000 00000000 04000000 + 04000000 04000000 04000000 + 80000000 c00000000 10000000 + 90000000 c10000000 10000000 + a0000000 fe1000000 00010000 + +The first column indicates the virtual address. +The second column indicates the physical address. +The third column indicates the mapped size. + +Configuration +------------- + +To use the addrmap command you must specify CONFIG_CMD_ADDRMAP=y. +It is automatically turned on when CONFIG_ADDR_MAP is set. diff --git a/roms/u-boot/doc/usage/askenv.rst b/roms/u-boot/doc/usage/askenv.rst new file mode 100644 index 000000000..5c4ca35d4 --- /dev/null +++ b/roms/u-boot/doc/usage/askenv.rst @@ -0,0 +1,87 @@ +.. SPDX-License-Identifier: GPL-2.0+: + +askenv command +=============== + +Synopsis +-------- + +:: + + askenv name [message] [size] + +Description +----------- + +Display message and get environment variable name of max size characters +from stdin. + +name + name of the environment variable + +message + message is displayed while the command waits for the value to be + entered from stdin.if no message is specified,a default message + "Please enter name:" will be displayed. + +size + maximum number of characters that will be stored in environment + variable name.this is in decimal number format (unlike in + other commands where size values are in hexa-decimal). Default + value of size is 1023 (CONFIG_SYS_CBSIZE - 1). + +Example +------- + +Value of a environment variable env1 without message and size parameters: + +:: + + => askenv env1;echo $? + Please enter 'env1': val1 + 0 + => printenv env1 + env1=val1 + +Value of a environment variable env2 with message and size parameters: + +:: + + => askenv env2 Please type-in a value for env2: 10;echo $? + Please type-in a value for env2: 1234567890123 + 0 + => printenv env2 + env2=1234567890 + +Value of a environment variable env3 with size parameter only: + +:: + + => askenv env3 10;echo $? + Please enter 'env3': val3 + 0 + => printenv env3 + env3=val3 + +Return Value of askenv command, when used without any other arguments: + +:: + + => askenv;echo $? + askenv - get environment variables from stdin + + Usage: + askenv name [message] [size] + - display 'message' and get environment variable 'name' from stdin (max 'size' chars) + 1 + +Configuration +------------- + +The askenv command is only available if CMD_ASKENV=y + +Return value +------------ + +The return value $? is set to 0 (true). +If no other arguments are specified (along with askenv), it is set to 1 (false). diff --git a/roms/u-boot/doc/usage/base.rst b/roms/u-boot/doc/usage/base.rst new file mode 100644 index 000000000..db9cd4d97 --- /dev/null +++ b/roms/u-boot/doc/usage/base.rst @@ -0,0 +1,23 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +base command +============ + +Synopsis +-------- + +:: + + base [address] + +Description +----------- + +The *base* command sets or displays the address offset used by the memory +commands *cmp, cp, md, mdc, mm, ms, mw, mwc*. + +All other commands ignore the address defined by *base*. + +address + new base address as hexadecimal number. If no value is provided, the current + value is displayed. diff --git a/roms/u-boot/doc/usage/bootefi.rst b/roms/u-boot/doc/usage/bootefi.rst new file mode 100644 index 000000000..282f22aac --- /dev/null +++ b/roms/u-boot/doc/usage/bootefi.rst @@ -0,0 +1,135 @@ +.. SPDX-License-Identifier: GPL-2.0+ +.. Copyright 2020, Heinrich Schuchardt <xypron.glpk@gmx.de> + +bootefi command +=============== + +Synopsis +-------- + +:: + + bootefi [image_addr] [fdt_addr] + bootefi bootmgr [fdt_addr] + bootefi hello [fdt_addr] + bootefi selftest [fdt_addr] + +Description +----------- + +The *bootefi* command is used to launch a UEFI binary which can be either of + +* UEFI application +* UEFI boot services driver +* UEFI run-time services driver + +An operating system requires a hardware description which can either be +presented as ACPI table (CONFIG\_GENERATE\_ACPI\_TABLE=y) or as device-tree +The load address of the device-tree may be provided as parameter *fdt\_addr*. If +this address is not specified, the bootefi command will try to fall back in +sequence to: + +* the device-tree specified by environment variable *fdt\_addr* +* the device-tree specified by environment variable *fdtcontroladdr* + +The load address of the binary is specified by parameter *image_address*. A +command sequence to run a UEFI application might look like + +:: + + load mmc 0:2 $fdt_addr_r dtb + load mmc 0:1 $kernel_addr_r /EFI/grub/grubaa64.efi + bootefi $kernel_addr_r $fdt_addr_r + +The last file loaded defines the image file path in the loaded image protocol. +Hence the executable should always be loaded last. + +The value of the environment variable *bootargs* is converted from UTF-8 to +UTF-16 and passed as load options in the loaded image protocol to the UEFI +binary. + +Note + UEFI binaries that are contained in FIT images are launched via the + *bootm* command. + +UEFI boot manager +''''''''''''''''' + +The UEFI boot manager is invoked by the *bootefi bootmgr* sub-command. +Here boot options are defined by UEFI variables with a name consisting of the +letters *Boot* followed by a four digit hexadecimal number, e.g. *Boot0001* or +*BootA03E*. The boot variable defines a label, the device path of the binary to +execute as well as the load options passed in the loaded image protocol. + +If the UEFI variable *BootNext* is defined, it specifies the number of the boot +option to execute next. If no binary can be loaded via *BootNext* the variable +*BootOrder* specifies in which sequence boot options shalled be tried. + +The values of these variables can be managed using the U-Boot command +*efidebug*. + +UEFI hello world application +'''''''''''''''''''''''''''' + +U-Boot can be compiled with a hello world application that can be launched using +the *bootefi hello* sub-command. A session might look like + +:: + + => setenv bootargs 'Greetings to the world' + => bootefi hello + Booting /MemoryMapped(0x0,0x10001000,0x1000) + Hello, world! + Running on UEFI 2.8 + Have SMBIOS table + Have device tree + Load options: Greetings to the world + +UEFI selftest +''''''''''''' + +U-Boot can be compiled with UEFI unit tests. These unit tests are invoked using +the *bootefi selftest* sub-command. + +Which unit test is executed is controlled by the environment variable +*efi\_selftest*. If this variable is not set, all unit tests that are not marked +as 'on request' are executed. + +To show a list of the available unit tests the value *list* can be used + +:: + + => setenv efi_selftest list + => bootefi selftest + + Available tests: + 'block image transfer' - on request + 'block device' + 'configuration tables' + ... + +A single test is selected for execution by setting the *efi\_selftest* +environment variable to match one of the listed identifiers + +:: + + => setenv efi_selftest 'block image transfer' + => bootefi selftest + +Some of the tests execute the ExitBootServices() UEFI boot service and will not +return to the command line but require a board reset. + +Configuration +------------- + +To use the *bootefi* command you must specify CONFIG\_CMD\_BOOTEFI=y. +The *bootefi hello* sub-command requries CMD\_BOOTEFI\_HELLO=y. +The *bootefi selftest* sub-command depends on CMD\_BOOTEFI\_SELFTEST=y. + +See also +-------- + +* *bootm* for launching UEFI binaries packed in FIT images +* *booti*, *bootm*, *bootz* for launching a Linux kernel without using the + UEFI sub-system +* *efidebug* for setting UEFI boot variables diff --git a/roms/u-boot/doc/usage/booti.rst b/roms/u-boot/doc/usage/booti.rst new file mode 100644 index 000000000..d631fb571 --- /dev/null +++ b/roms/u-boot/doc/usage/booti.rst @@ -0,0 +1,114 @@ +.. SPDX-License-Identifier: GPL-2.0+: + +booti command +============= + +Synopsis +-------- + +:: + + booti [<addr> [<initrd>[:<size>]] [<fdt>]] + +Description +----------- + +The booti command is used to boot a Linux kernel in flat or compressed +'Image' format. Which compressed formats are supported is configurable. + +addr + address of kernel image, defaults to CONFIG_SYS_LOAD_ADDR. + +initrd + address of the initial RAM disk. Use '-' to boot a kernel with a device + tree but without an initial RAM disk. + +size + size of the initial RAM disk. This parameter must be specified for raw + initial RAM disks. + +fdt + address of the device tree. + +To support compressed Image files the following environment variables must be +set: + +kernel_comp_addr_r + start of memory area used for decompression + +kernel_comp_size + size of the compressed file. The value has to be at least the size of + loaded image for decompression to succeed. For the booti command the + maximum decompressed size is 10 times this value. + +Example +------- + +This is the boot log of an Odroid C2 board: + +:: + + => load mmc 0:1 $fdt_addr_r dtb-5.10.0-3-arm64 + 27530 bytes read in 7 ms (3.7 MiB/s) + => load mmc 0:1 $kernel_addr_r vmlinuz-5.10.0-3-arm64 + 26990448 bytes read in 1175 ms (21.9 MiB/s) + => load mmc 0:1 $ramdisk_addr_r initrd.img-5.10.0-3-arm64 + 27421776 bytes read in 1209 ms (21.6 MiB/s) + => booti $kernel_addr_r $ramdisk_addr_r:$filesize $fdt_addr_r + Moving Image from 0x8080000 to 0x8200000, end=9c60000 + ## Flattened Device Tree blob at 08008000 + Booting using the fdt blob at 0x8008000 + Loading Ramdisk to 7a52a000, end 7bf50c50 ... OK + Loading Device Tree to 000000007a520000, end 000000007a529b89 ... OK + + Starting kernel ... + +The kernel can be compressed with gzip: + +.. code-block:: bash + + cd /boot + gzip -k vmlinuz-5.10.0-3-arm64 + +Here is the boot log for the compressed kernel: + +:: + + => setenv kernel_comp_addr_r 0x50000000 + => setenv kernel_comp_size 0x04000000 + => load mmc 0:1 $fdt_addr_r dtb-5.10.0-3-arm64 + 27530 bytes read in 6 ms (4.4 MiB/s) + => load mmc 0:1 $kernel_addr_r vmlinuz-5.10.0-3-arm64.gz + 9267730 bytes read in 402 ms (22 MiB/s) + => load mmc 0:1 $ramdisk_addr_r initrd.img-5.10.0-3-arm64 + 27421776 bytes read in 1181 ms (22.1 MiB/s) + => booti $kernel_addr_r $ramdisk_addr_r:$filesize $fdt_addr_r + Uncompressing Kernel Image + Moving Image from 0x8080000 to 0x8200000, end=9c60000 + ## Flattened Device Tree blob at 08008000 + Booting using the fdt blob at 0x8008000 + Loading Ramdisk to 7a52a000, end 7bf50c50 ... OK + Loading Device Tree to 000000007a520000, end 000000007a529b89 ... OK + + Starting kernel ... + +Configuration +------------- + +The booti command is only available if CONFIG_CMD_BOOTI=y. + +Which compression types are supported depends on: + +* CONFIG_BZIP2 +* CONFIG_GZIP +* CONFIG_LZ4 +* CONFIG_LZMA +* CONFIG_LZO +* CONFIG_ZSTD + +Return value +------------ + +Normally this command does not return. If an error occurs, the return value $? +is set to 1 (false). If the operating system returns to U-Boot, the system is +reset. diff --git a/roms/u-boot/doc/usage/bootmenu.rst b/roms/u-boot/doc/usage/bootmenu.rst new file mode 100644 index 000000000..1f094ad6e --- /dev/null +++ b/roms/u-boot/doc/usage/bootmenu.rst @@ -0,0 +1,95 @@ +.. SPDX-License-Identifier: GPL-2.0+ +.. (C) Copyright 2011-2012 Pali Rohár <pali@kernel.org> + +bootmenu command +================ + +The "bootmenu" command uses U-Boot menu interfaces and provides +a simple mechanism for creating menus with different boot items. +The cursor keys "Up" and "Down" are used for navigation through +the items. Current active menu item is highlighted and can be +selected using the "Enter" key. The selection of the highlighted +menu entry invokes an U-Boot command (or a list of commands) +associated with this menu entry. + +The "bootmenu" command interprets ANSI escape sequencies, so +an ANSI terminal is required for proper menu rendering and item +selection. + +The assembling of the menu is done via a set of environment variables +"bootmenu_<num>" and "bootmenu_delay", i.e.:: + + bootmenu_delay=<delay> + bootmenu_<num>="<title>=<commands>" + +<delay> + is the autoboot delay in seconds, after which the first + menu entry will be selected automatically + +<num> + is the boot menu entry number, starting from zero + +<title> + is the text of the menu entry shown on the console + or on the boot screen + +<commands> + are commands which will be executed when a menu + entry is selected + +Title and commands are separated by the first appearance of a '=' +character in the value of the environment variable. + +The first (optional) argument of the "bootmenu" command is a delay specifier +and it overrides the delay value defined by "bootmenu_delay" environment +variable. If the environment variable "bootmenu_delay" is not set or if +the argument of the "bootmenu" command is not specified, the default delay +will be CONFIG_BOOTDELAY. If delay is 0, no menu entries will be shown on +the console (or on the screen) and the command of the first menu entry will +be called immediately. If delay is less then 0, bootmenu will be shown and +autoboot will be disabled. + +Bootmenu always adds menu entry "U-Boot console" at the end of all menu +entries specified by environment variables. When selecting this entry +the bootmenu terminates and the usual U-Boot command prompt is presented +to the user. + +Example environment:: + + setenv bootmenu_0 Boot 1. kernel=bootm 0x82000000 # Set first menu entry + setenv bootmenu_1 Boot 2. kernel=bootm 0x83000000 # Set second menu entry + setenv bootmenu_2 Reset board=reset # Set third menu entry + setenv bootmenu_3 U-Boot boot order=boot # Set fourth menu entry + bootmenu 20 # Run bootmenu with autoboot delay 20s + + +The above example will be rendered as below:: + + *** U-Boot Boot Menu *** + + Boot 1. kernel + Boot 2. kernel + Reset board + U-Boot boot order + U-Boot console + + Hit any key to stop autoboot: 20 + Press UP/DOWN to move, ENTER to select + +The selected menu entry will be highlighted - it will have inverted +background and text colors. + +The "bootmenu" cammand is enabled by:: + + CONFIG_CMD_BOOTMENU=y + +To run the bootmenu at startup add these additional settings:: + + CONFIG_AUTOBOOT_KEYED=y + CONFIG_BOOTDELAY=30 + CONFIG_AUTOBOOT_MENU_SHOW=y + +When you intend to use the bootmenu on a color frame buffer console, +make sure to additionally define:: + + CONFIG_CFB_CONSOLE_ANSI=y diff --git a/roms/u-boot/doc/usage/button.rst b/roms/u-boot/doc/usage/button.rst new file mode 100644 index 000000000..ea4176275 --- /dev/null +++ b/roms/u-boot/doc/usage/button.rst @@ -0,0 +1,64 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +button command +============== + +Synopsis +-------- + +:: + + button list + button <name> + +Description +----------- + +The button command is used to retrieve the status of a button. To show the +status of a button with name 'button1' you would issue the command + +:: + + button button1 + +The status of the button is both written to the console as *ON* or *OFF* and +set in the return value variable *$?* as 0 (true) or 1 (false). To retrieve +the status of a button with name *button1* and to write it to environment +variable *status1* you would execute the commands + +:: + + button button1 + setenv status1 $? + +A list of all available buttons and their status can be displayed using + +:: + + button list + +If a button device has not been probed yet, its status will be shown as +*<inactive>* in the list. + +Configuration +------------- + +To use the button command you must specify CONFIG_CMD_BUTTON=y and enable a +button driver. The available buttons are defined in the device-tree. + +Return value +------------ + +The variable *$?* takes the following values + ++---+-----------------------------+ +| 0 | ON, the button is pressed | ++---+-----------------------------+ +| 1 | OFF, the button is released | ++---+-----------------------------+ +| 0 | button list was shown | ++---+-----------------------------+ +| 1 | button not found | ++---+-----------------------------+ +| 1 | invalid arguments | ++---+-----------------------------+ diff --git a/roms/u-boot/doc/usage/conitrace.rst b/roms/u-boot/doc/usage/conitrace.rst new file mode 100644 index 000000000..d9916c865 --- /dev/null +++ b/roms/u-boot/doc/usage/conitrace.rst @@ -0,0 +1,54 @@ +conitrace command +================= + +Synopsis +-------- + +:: + + conitrace + +Description +----------- + +The conitrace command is used to test the correct function of the console input +driver. It is especially valuable for checking the support for special keys like +<F1> or <POS1>. + +To display escape sequences on a single line the output only advances to the +next line after detecting a pause of a few milliseconds. + +The output is hexadecimal. + +Examples +-------- + +Entering keys <B><SHIFT-B><CTRL-B><X> + +:: + + => conitrace + Waiting for your input + To terminate type 'x' + 62 + 42 + 02 + => + +Entering keys <F1><POS1><DEL><BACKSPACE><X> + +:: + + => conitrace + Waiting for your input + To terminate type 'x' + 1b 4f 50 + 1b 5b 48 + 1b 5b 33 7e + 7f + => + +Configuration +------------- + +The conitrace command is only available if CONFIG_CMD_CONITRACE=y. diff --git a/roms/u-boot/doc/usage/dfu.rst b/roms/u-boot/doc/usage/dfu.rst new file mode 100644 index 000000000..11c88072b --- /dev/null +++ b/roms/u-boot/doc/usage/dfu.rst @@ -0,0 +1,404 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +Device Firmware Upgrade (DFU) +============================= + +Overview +-------- + +The Device Firmware Upgrade (DFU) allows to download and upload firmware +to/from U-Boot connected over USB. + +U-boot follows the Universal Serial Bus Device Class Specification for +Device Firmware Upgrade Version 1.1 the USB forum (DFU v1.1 in www.usb.org). + +U-Boot implements this DFU capability (CONFIG_DFU) with the command dfu +(cmd/dfu.c / CONFIG_CMD_DFU) based on: + +- the DFU stack (common/dfu.c and common/spl/spl_dfu.c), based on the + USB DFU download gadget (drivers/usb/gadget/f_dfu.c) +- The access to mediums is done in DFU backends (driver/dfu) + +Today the supported DFU backends are: + +- MMC (RAW or FAT / EXT2 / EXT3 / EXT4 file system / SKIP / SCRIPT) +- NAND +- RAM +- SF (serial flash) +- MTD (all MTD device: NAND, SPI-NOR, SPI-NAND,...) +- virtual + +These DFU backends are also used by + +- the dfutftp (see README.dfutftp) +- the thordown command (cmd/thordown.c and gadget/f_thor.c) + +The "virtual" backend is a generic DFU backend to support a board specific +target (for example OTP), only based on the weak functions: + +- dfu_write_medium_virt +- dfu_get_medium_size_virt +- dfu_read_medium_virt + +Configuration Options +--------------------- + +The following configuration option are relevant for device firmware upgrade: + +* CONFIG_DFU +* CONFIG_DFU_OVER_USB +* CONFIG_DFU_MMC +* CONFIG_DFU_MTD +* CONFIG_DFU_NAND +* CONFIG_DFU_RAM +* CONFIG_DFU_SF +* CONFIG_DFU_SF_PART +* CONFIG_DFU_TIMEOUT +* CONFIG_DFU_VIRTUAL +* CONFIG_CMD_DFU + +Environment variables +--------------------- + +The dfu command uses 3 environments variables: + +dfu_alt_info + The DFU setting for the USB download gadget with a semicolon separated + string of information on each alternate:: + + dfu_alt_info="<alt1>;<alt2>;....;<altN>" + + When several devices are used, the format is: + + - <interface> <dev>'='alternate list (';' separated) + - each interface is separated by '&':: + + dfu_alt_info=\ + "<interface1> <dev1>=<alt1>;....;<altN>&"\ + "<interface2> <dev2>=<altN+1>;....;<altM>&"\ + ...\ + "<interfaceI> <devI>=<altY+1>;....;<altZ>&" + +dfu_bufsiz + size of the DFU buffer, when absent, defaults to + CONFIG_SYS_DFU_DATA_BUF_SIZE (8 MiB by default) + +dfu_hash_algo + name of the hash algorithm to use + +Commands +-------- + +dfu <USB_controller> [<interface> <dev>] list + list the alternate device defined in *dfu_alt_info* + +dfu <USB_controller> [<interface> <dev>] [<timeout>] + start the dfu stack on the USB instance with the selected medium + backend and use the *dfu_alt_info* variable to configure the + alternate setting and link each one with the medium + The dfu command continue until receive a ^C in console or + a DFU detach transaction from HOST. If CONFIG_DFU_TIMEOUT option + is enabled and <timeout> parameter is present in the command line, + the DFU operation will be aborted automatically after <timeout> + seconds of waiting remote to initiate DFU session. + +The possible values of <interface> are (with <USB controller> = 0 in the dfu +command example) + +mmc + for eMMC and SD card:: + + dfu 0 mmc <dev> + + each element in *dfu_alt_info* being + + * <name> raw <offset> <size> [mmcpart <num>] raw access to mmc device + * <name> part <dev> <part_id> [mmcpart <num>] raw access to partition + * <name> fat <dev> <part_id> [mmcpart <num>] file in FAT partition + * <name> ext4 <dev> <part_id> [mmcpart <num>] file in EXT4 partition + * <name> skip 0 0 ignore flashed data + * <name> script 0 0 execute commands in shell + + with + + partid + being the GPT or DOS partition index, + num + being the eMMC hardware partition number. + + A value of environment variable *dfu_alt_info* for eMMC could be:: + + u-boot raw 0x3e 0x800 mmcpart 1;bl2 raw 0x1e 0x1d mmcpart 1 + + A value of environment variable *dfu_alt_info* for SD card could be:: + + u-boot raw 0x80 0x800;uImage ext4 0 2 + + If don't want to flash given image file to storage, use "skip" type + entity. + + - It can be used to protect flashing wrong image for the specific board. + - Especailly, this layout will be useful when thor protocol is used, + which performs flashing in batch mode, where more than one file is + processed. + + For example, if one makes a single tar file with support for the two + boards with u-boot-<board1>.bin and u-boot-<board2>.bin files, one + can use it to flash a proper u-boot image on both without a failure:: + + u-boot-<board1>.bin raw 0x80 0x800; u-boot-<board2>.bin skip 0 0 + + When flashing new system image requires do some more complex things + than just writing data to the storage medium, one can use 'script' + type. Data written to such entity will be executed as a command list + in the u-boot's shell. This for example allows to re-create partition + layout and even set new *dfu_alt_info* for the newly created paritions. + Such script would look like:: + + setenv dfu_alt_info ... + setenv mbr_parts ... + mbr write ... + + Please note that this means that user will be able to execute any + arbitrary commands just like in the u-boot's shell. + +nand + raw slc nand device:: + + dfu 0 nand <dev> + + each element in *dfu_alt_info* being either of + + * <name> raw <offset> <size> raw access to mmc device + * <name> part <dev> <part_id> raw acces to partition + * <name> partubi <dev> <part_id> raw acces to ubi partition + + with + + partid + is the MTD partition index + +ram + raw access to ram:: + + dfu 0 ram <dev> + + dev + is not used for RAM target + + each element in *dfu_alt_info* being:: + + <name> ram <offset> <size> raw access to ram + +sf + serial flash : NOR:: + + cmd: dfu 0 sf <dev> + + each element in *dfu_alt_info* being either of: + + * <name> raw <offset> <size> raw access to sf device + * <name> part <dev> <part_id> raw acces to partition + * <name> partubi <dev> <part_id> raw acces to ubi partition + + with + + partid + is the MTD partition index + +mtd + all MTD device: NAND, SPI-NOR, SPI-NAND,...:: + + cmd: dfu 0 mtd <dev> + + with + + dev + the mtd identifier as defined in mtd command + (nand0, nor0, spi-nand0,...) + + each element in *dfu_alt_info* being either of: + + * <name> raw <offset> <size> forraw access to mtd device + * <name> part <dev> <part_id> for raw acces to partition + * <name> partubi <dev> <part_id> for raw acces to ubi partition + + with + + partid + is the MTD partition index + +virt + virtual flash back end for DFU + + :: + + cmd: dfu 0 virt <dev> + + each element in *dfu_alt_info* being: + + * <name> + +<interface> and <dev> are absent, the dfu command to use multiple devices:: + + cmd: dfu 0 list + cmd: dfu 0 + +*dfu_alt_info* variable provides the list of <interface> <dev> with +alternate list separated by '&' with the same format for each <alt>:: + + mmc <dev>=<alt1>;....;<altN> + nand <dev>=<alt1>;....;<altN> + ram <dev>=<alt1>;....;<altN> + sf <dev>=<alt1>;....;<altN> + mtd <dev>=<alt1>;....;<altN> + virt <dev>=<alt1>;....;<altN> + +Callbacks +--------- + +The weak callback functions can be implemented to manage specific behavior + +dfu_initiated_callback + called when the DFU transaction is started, used to initiase the device + +dfu_flush_callback + called at the end of the DFU write after DFU manifestation, used to manage + the device when DFU transaction is closed + +Host tools +---------- + +When U-Boot runs the dfu stack, the DFU host tools can be used +to send/receive firmwares on each configurated alternate. + +For example dfu-util is a host side implementation of the DFU 1.1 +specifications(http://dfu-util.sourceforge.net/) which works with U-Boot. + +Usage +----- + +Example 1: firmware located in eMMC or SD card, with: + +- alternate 1 (alt=1) for SPL partition (GPT partition 1) +- alternate 2 (alt=2) for U-Boot partition (GPT partition 2) + +The U-Boot configuration is:: + + U-Boot> env set dfu_alt_info "spl part 0 1;u-boot part 0 2" + + U-Boot> dfu 0 mmc 0 list + DFU alt settings list: + dev: eMMC alt: 0 name: spl layout: RAW_ADDR + dev: eMMC alt: 1 name: u-boot layout: RAW_ADDR + + Boot> dfu 0 mmc 0 + +On the Host side: + +list the available alternate setting:: + + $> dfu-util -l + dfu-util 0.9 + + Copyright 2005-2009 Weston Schmidt, Harald Welte and OpenMoko Inc. + Copyright 2010-2016 Tormod Volden and Stefan Schmidt + This program is Free Software and has ABSOLUTELY NO WARRANTY + Please report bugs to http://sourceforge.net/p/dfu-util/tickets/ + + Found DFU: [0483:5720] ver=0200, devnum=45, cfg=1, intf=0, path="3-1.3.1", \ + alt=1, name="u-boot", serial="003A00203438510D36383238" + Found DFU: [0483:5720] ver=0200, devnum=45, cfg=1, intf=0, path="3-1.3.1", \ + alt=0, name="spl", serial="003A00203438510D36383238" + + To download to U-Boot, use -D option + + $> dfu-util -a 0 -D u-boot-spl.bin + $> dfu-util -a 1 -D u-boot.bin + + To upload from U-Boot, use -U option + + $> dfu-util -a 0 -U u-boot-spl.bin + $> dfu-util -a 1 -U u-boot.bin + + To request a DFU detach and reset the USB connection: + $> dfu-util -a 0 -e -R + + +Example 2: firmware located in NOR (sf) and NAND, with: + +- alternate 1 (alt=1) for SPL partition (NOR GPT partition 1) +- alternate 2 (alt=2) for U-Boot partition (NOR GPT partition 2) +- alternate 3 (alt=3) for U-Boot-env partition (NOR GPT partition 3) +- alternate 4 (alt=4) for UBI partition (NAND GPT partition 1) + +:: + + U-Boot> env set dfu_alt_info \ + "sf 0:0:10000000:0=spl part 0 1;u-boot part 0 2; \ + u-boot-env part 0 3&nand 0=UBI partubi 0,1" + + U-Boot> dfu 0 list + + DFU alt settings list: + dev: SF alt: 0 name: spl layout: RAW_ADDR + dev: SF alt: 1 name: ssbl layout: RAW_ADDR + dev: SF alt: 2 name: u-boot-env layout: RAW_ADDR + dev: NAND alt: 3 name: UBI layout: RAW_ADDR + + U-Boot> dfu 0 + +:: + + $> dfu-util -l + Found DFU: [0483:5720] ver=9999, devnum=96, cfg=1,\ + intf=0, alt=3, name="UBI", serial="002700333338511934383330" + Found DFU: [0483:5720] ver=9999, devnum=96, cfg=1,\ + intf=0, alt=2, name="u-boot-env", serial="002700333338511934383330" + Found DFU: [0483:5720] ver=9999, devnum=96, cfg=1,\ + intf=0, alt=1, name="u-boot", serial="002700333338511934383330" + Found DFU: [0483:5720] ver=9999, devnum=96, cfg=1,\ + intf=0, alt=0, name="spl", serial="002700333338511934383330" + +Same example with MTD backend + +:: + + U-Boot> env set dfu_alt_info \ + "mtd nor0=spl part 1;u-boot part 2;u-boot-env part 3&"\ + "mtd nand0=UBI partubi 1" + + U-Boot> dfu 0 list + using id 'nor0,0' + using id 'nor0,1' + using id 'nor0,2' + using id 'nand0,0' + DFU alt settings list: + dev: MTD alt: 0 name: spl layout: RAW_ADDR + dev: MTD alt: 1 name: u-boot layout: RAW_ADDR + dev: MTD alt: 2 name: u-boot-env layout: RAW_ADDR + dev: MTD alt: 3 name: UBI layout: RAW_ADDR + +Example 3 + +firmware located in SD Card (mmc) and virtual partition on OTP and PMIC not +volatile memory + +- alternate 1 (alt=1) for scard +- alternate 2 (alt=2) for OTP (virtual) +- alternate 3 (alt=3) for PMIC NVM (virtual) + +:: + + U-Boot> env set dfu_alt_info \ + "mmc 0=sdcard raw 0 0x100000&"\ + "virt 0=otp" \ + "virt 1=pmic" + +:: + + U-Boot> dfu 0 list + DFU alt settings list: + dev: eMMC alt: 0 name: sdcard layout: RAW_ADDR + dev: VIRT alt: 1 name: otp layout: RAW_ADDR + dev: VIRT alt: 2 name: pmic layout: RAW_ADDR diff --git a/roms/u-boot/doc/usage/echo.rst b/roms/u-boot/doc/usage/echo.rst new file mode 100644 index 000000000..861abdfd1 --- /dev/null +++ b/roms/u-boot/doc/usage/echo.rst @@ -0,0 +1,65 @@ +echo command +============ + +Synopsis +-------- + +:: + + echo [-n] [args ...] + +Description +----------- + +The echo command prints its arguments to the console separated by spaces. + +-n + Do not print a line feed after the last argument. + +args + Arguments to be printed. The arguments are evaluated before being passed to + the command. + +Examples +-------- + +Strings are parsed before the arguments are passed to the echo command: + +:: + + => echo "a" 'b' c + a b c + => + +Observe how variables included in strings are handled: + +:: + + => setenv var X; echo "a)" ${var} 'b)' '${var}' c) ${var} + a) X b) ${var} c) X + => + + +-n suppresses the line feed: + +:: + + => echo -n 1 2 3; echo a b c + 1 2 3a b c + => echo -n 1 2 3 + 1 2 3=> + +A more complex example: + +:: + + => for i in a b c; do for j in 1 2 3; do echo -n "${i}${j}, "; done; echo; done; + a1, a2, a3, + b1, b2, b3, + c1, c2, c3, + => + +Return value +------------ + +The return value $? is always set to 0 (true). diff --git a/roms/u-boot/doc/usage/exception.rst b/roms/u-boot/doc/usage/exception.rst new file mode 100644 index 000000000..27df88bd5 --- /dev/null +++ b/roms/u-boot/doc/usage/exception.rst @@ -0,0 +1,66 @@ +exception command +================= + +Synopsis +-------- + +:: + + exception <type> + +Description +----------- + +The exception command is used to test the handling of exceptions like undefined +instructions, segmentation faults or alignment faults. + +type + type of exception to be generated. The available types are architecture + dependent. Use 'help exception' to determine which are available. + + **ARM:** + + breakpoint + prefetch abort + + unaligned + data abort + + undefined + undefined instruction + + **RISC-V:** + + ebreak + breakpoint exception + + unaligned + load address misaligned + + undefined + undefined instruction + + **Sandbox:** + + sigsegv + illegal memory access + + undefined + undefined instruction + + **x86:** + + undefined + undefined instruction + +Examples +-------- + +:: + + => exception undefined + + Illegal instruction + pc = 0x56076dd1a0f9, pc_reloc = 0x540f9 + + resetting ... diff --git a/roms/u-boot/doc/usage/exit.rst b/roms/u-boot/doc/usage/exit.rst new file mode 100644 index 000000000..769223c47 --- /dev/null +++ b/roms/u-boot/doc/usage/exit.rst @@ -0,0 +1,40 @@ +exit command +============ + +Synopsis +-------- + +:: + + exit + +Description +----------- + +The exit command terminates a script started via the run or source command. +If scripts are nested, only the innermost script is left. + +:: + + => setenv inner 'echo entry inner; exit; echo inner done' + => setenv outer 'echo entry outer; run inner; echo outer done' + => run outer + entry outer + entry inner + outer done + => + +When executed outside a script a warning is written. Following commands are not +executed. + +:: + + => echo first; exit; echo last + first + exit not allowed from main input shell. + => + +Return value +------------ + +$? is always set to 0 (true). diff --git a/roms/u-boot/doc/usage/extension.rst b/roms/u-boot/doc/usage/extension.rst new file mode 100644 index 000000000..2b88398b1 --- /dev/null +++ b/roms/u-boot/doc/usage/extension.rst @@ -0,0 +1,111 @@ +.. SPDX-License-Identifier: GPL-2.0+ +.. Copyright 2021, Kory Maincent <kory.maincent@bootlin.com> + +U-Boot extension board usage (CONFIG_EXTENSION) +=============================================== + +Synopsis +-------- + +:: + + extension scan + extension list + extension apply <extension number|all> + +Description +----------- + +The "extension" command proposes a generic U-Boot mechanism to detect +extension boards connected to the HW platform, and apply the appropriate +Device Tree overlays depending on the detected extension boards. + +The "extension" command comes with three sub-commands: + + - "extension scan" makes the generic code call the board-specific + extension_board_scan() function to retrieve the list of detected + extension boards. + + - "extension list" allows to list the detected extension boards. + + - "extension apply <number>|all" allows to apply the Device Tree + overlay(s) corresponding to one, or all, extension boards + +The latter requires two environment variables to exist: + + - extension_overlay_addr: the RAM address where to load the Device + Tree overlays + + - extension_overlay_cmd: the U-Boot command to load one overlay. + Indeed, the location and mechanism to load DT overlays is very setup + specific. + +In order to enable this mechanism, board-specific code must implement +the extension_board_scan() function that fills in a linked list of +"struct extension", each describing one extension board. In addition, +the board-specific code must select the SUPPORT_EXTENSION_SCAN Kconfig +boolean. + +Usage example +------------- + +1. Make sure your devicetree is loaded and set as the working fdt tree. + +:: + + => run loadfdt + => fdt addr $fdtaddr + +2. Prepare the environment variables + +:: + + => setenv extension_overlay_addr 0x88080000 + => setenv extension_overlay_cmd 'load mmc 0:1 ${extension_overlay_addr} /boot/${extension_overlay_name}' + +3. Detect the plugged extension board + +:: + + => extension scan + +4. List the plugged extension board information and the devicetree + overlay name + +:: + + => extension list + +5. Apply the appropriate devicetree overlay + +For apply the selected overlay: + +:: + + => extension apply 0 + +For apply all the overlays: + +:: + + => extension apply all + +Simple extension_board_scan function example +-------------------------------------------- + +.. code-block:: c + + int extension_board_scan(struct list_head *extension_list) + { + struct extension *extension; + + extension = calloc(1, sizeof(struct extension)); + snprintf(extension->overlay, sizeof(extension->overlay), "overlay.dtbo"); + snprintf(extension->name, sizeof(extension->name), "extension board"); + snprintf(extension->owner, sizeof(extension->owner), "sandbox"); + snprintf(extension->version, sizeof(extension->version), "1.1"); + snprintf(extension->other, sizeof(extension->other), "Extension board information"); + list_add_tail(&extension->list, extension_list); + + return 1; + } diff --git a/roms/u-boot/doc/usage/false.rst b/roms/u-boot/doc/usage/false.rst new file mode 100644 index 000000000..a17fe8602 --- /dev/null +++ b/roms/u-boot/doc/usage/false.rst @@ -0,0 +1,28 @@ +false command +============= + +Synopsis +-------- + +:: + + false + +Description +----------- + +The false command sets the return value $? to 1 (false). + +Example +------- + +:: + + => false; echo $? + 1 + => + +Configuration +------------- + +The false command is only available if CONFIG_HUSH_PARSER=y. diff --git a/roms/u-boot/doc/usage/fatinfo.rst b/roms/u-boot/doc/usage/fatinfo.rst new file mode 100644 index 000000000..af2eba434 --- /dev/null +++ b/roms/u-boot/doc/usage/fatinfo.rst @@ -0,0 +1,51 @@ +.. SPDX-License-Identifier: GPL-2.0+: + +fatinfo command +=============== + +Synopsis +-------- + +:: + + fatinfo <interface> <dev[:part]> + +Description +----------- + +The fatinfo command displays information about a FAT partition. + +interface + interface for accessing the block device (mmc, sata, scsi, usb, ....) + +dev + device number + +part + partition number, defaults to 1 + +Example +------- + +Here is the output for a partition on a 32 GB SD-Card: + +:: + + => fatinfo mmc 0:1 + Interface: MMC + Device 0: Vendor: Man 00001b Snr 97560602 Rev: 13.8 Prod: EB1QT0 + Type: Removable Hard Disk + Capacity: 30528.0 MB = 29.8 GB (62521344 x 512) + Filesystem: FAT32 "MYDISK " + => + +Configuration +------------- + +The fatinfo command is only available if CONFIG_CMD_FAT=y. + +Return value +------------ + +The return value $? is set to 0 (true) if the partition is a FAT partition. +Otherwise it is set to 1 (false). diff --git a/roms/u-boot/doc/usage/fdt_overlays.rst b/roms/u-boot/doc/usage/fdt_overlays.rst new file mode 100644 index 000000000..ea3971343 --- /dev/null +++ b/roms/u-boot/doc/usage/fdt_overlays.rst @@ -0,0 +1,134 @@ +.. SPDX-License-Identifier: GPL-2.0+ +.. Copyright (c) 2017, Pantelis Antoniou <pantelis.antoniou@konsulko.com> + +Device Tree Overlays +==================== + +Overlay Syntax +-------------- + +Device-tree overlays require a slightly different syntax compared to traditional +device-trees. Please refer to dt-object-internal.txt in the device-tree compiler +sources for information regarding the internal format of overlays: +https://git.kernel.org/pub/scm/utils/dtc/dtc.git/tree/Documentation/dt-object-internal.txt + +Building Overlays +----------------- + +In a nutshell overlays provides a means to manipulate a symbol a previous +device-tree or device-tree overlay has defined. It requires both the base +device-tree and all the overlays to be compiled with the *-@* command line +switch of the device-tree compiler so that symbol information is included. + +Note + Support for *-@* option can only be found in dtc version 1.4.4 or newer. + Only version 4.14 or higher of the Linux kernel includes a built in version + of dtc that meets this requirement. + +Building a binary device-tree overlay follows the same process as building a +traditional binary device-tree. For example: + +**base.dts** + +:: + + /dts-v1/; + / { + foo: foonode { + foo-property; + }; + }; + +.. code-block:: console + + $ dtc -@ -I dts -O dtb -o base.dtb base.dts + +**overlay.dts** + +:: + + /dts-v1/; + /plugin/; + / { + fragment@1 { + target = <&foo>; + __overlay__ { + overlay-1-property; + bar: barnode { + bar-property; + }; + }; + }; + }; + +.. code-block:: console + + $ dtc -@ -I dts -O dtb -o overlay.dtbo overlay.dts + +Ways to Utilize Overlays in U-Boot +---------------------------------- + +There are two ways to apply overlays in U-Boot. + +* Include and define overlays within a FIT image and have overlays + automatically applied. + +* Manually load and apply overlays + +The remainder of this document will discuss using overlays via the manual +approach. For information on using overlays as part of a FIT image please see: +doc/uImage.FIT/overlay-fdt-boot.txt + +Manually Loading and Applying Overlays +-------------------------------------- + +1. Figure out where to place both the base device tree blob and the + overlay. Make sure you have enough space to grow the base tree without + overlapping anything. + +:: + + => setenv fdtaddr 0x87f00000 + => setenv fdtovaddr 0x87fc0000 + +2. Load the base binary device-tree and the binary device-tree overlay. + +:: + + => load ${devtype} ${bootpart} ${fdtaddr} ${bootdir}/base.dtb + => load ${devtype} ${bootpart} ${fdtovaddr} ${bootdir}/overlay.dtbo + +3. Set the base binary device-tree as the working fdt tree. + +:: + + => fdtaddr $fdtaddr + +4. Grow it enough so it can encompass all applied overlays + +:: + + => fdt resize 8192 + +5. You are now ready to apply the overlay. + +:: + + => fdt apply $fdtovaddr + +6. Boot system like you would do with a traditional dtb. + +For bootm: + +:: + + => bootm ${kerneladdr} - ${fdtaddr} + +For bootz: + +:: + + => bootz ${kerneladdr} - ${fdtaddr} + +Please note that in case of an error, both the base and overlays are going +to be invalidated, so keep copies to avoid reloading. diff --git a/roms/u-boot/doc/usage/fit.rst b/roms/u-boot/doc/usage/fit.rst new file mode 100644 index 000000000..703743405 --- /dev/null +++ b/roms/u-boot/doc/usage/fit.rst @@ -0,0 +1,8 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +Flat Image Tree (FIT) +===================== + +U-Boot uses Flat Image Tree (FIT) as a standard file format for packaging +images that it it reads and boots. Documentation about FIT is available at +doc/uImage.FIT diff --git a/roms/u-boot/doc/usage/for.rst b/roms/u-boot/doc/usage/for.rst new file mode 100644 index 000000000..f9e504979 --- /dev/null +++ b/roms/u-boot/doc/usage/for.rst @@ -0,0 +1,65 @@ +for command +=========== + +Synopis +------- + +:: + + for <variable> in <items>; do <commands>; done + +Description +----------- + +The for command is used to loop over a list of values and execute a series of +commands for each of these. + +The counter variable of the loop is a shell variable. Please, keep in mind that +an environment variable takes precedence over a shell variable of the same name. + +variable + name of the counter variable + +items + space separated item list + +commands + commands to execute + +Example +------- + +:: + + => setenv c + => for c in 1 2 3; do echo item ${c}; done + item 1 + item 2 + item 3 + => echo ${c} + 3 + => setenv c x + => for c in 1 2 3; do echo item ${c}; done + item x + item x + item x + => + +The first line ensures that there is no environment variable *c*. Hence in the +first loop the shell variable *c* is printed. + +After defining an environment variable of name *c* it takes precedence over the +shell variable and the environment variable is printed. + +Return value +------------ + +The return value $? after the done statement is the return value of the last +statement executed in the loop. + +:: + + => for i in true false; do ${i}; done; echo $? + 1 + => for i in false true; do ${i}; done; echo $? + 0 diff --git a/roms/u-boot/doc/usage/index.rst b/roms/u-boot/doc/usage/index.rst new file mode 100644 index 000000000..40b796a3a --- /dev/null +++ b/roms/u-boot/doc/usage/index.rst @@ -0,0 +1,48 @@ +Use U-Boot +========== + +.. toctree:: + :maxdepth: 1 + + dfu + fdt_overlays + fit + netconsole + partitions + +Shell commands +-------------- + +.. toctree:: + :maxdepth: 1 + + addrmap + askenv + base + bootefi + booti + bootmenu + button + x86/cbsysinfo + conitrace + echo + exception + extension + exit + false + fatinfo + for + load + loady + mbr + md + mmc + pinmux + pstore + qfw + reset + sbi + scp03 + size + true + ums diff --git a/roms/u-boot/doc/usage/load.rst b/roms/u-boot/doc/usage/load.rst new file mode 100644 index 000000000..1efee7731 --- /dev/null +++ b/roms/u-boot/doc/usage/load.rst @@ -0,0 +1,74 @@ +.. SPDX-License-Identifier: GPL-2.0+: + +load command +============ + +Synopsis +-------- + +:: + + load <interface> [<dev[:part]> [<addr> [<filename> [bytes [pos]]]]] + +Description +----------- + +The load command is used to read a file from a filesystem into memory. + +The number of transferred bytes is saved in the environment variable filesize. +The load address is saved in the environment variable fileaddr. + +interface + interface for accessing the block device (mmc, sata, scsi, usb, ....) + +dev + device number + +part + partition number, defaults to 0 (whole device) + +addr + load address, defaults to environment variable loadaddr or if loadaddr is + not set to configuration variable CONFIG_SYS_LOAD_ADDR + +filename + path to file, defaults to environment variable bootfile + +bytes + maximum number of bytes to load + +pos + number of bytes to skip + +addr, bytes, pos are hexadecimal numbers. + +Example +------- + +:: + + => load mmc 0:1 ${kernel_addr_r} snp.efi + 149280 bytes read in 11 ms (12.9 MiB/s) + => + => load mmc 0:1 ${kernel_addr_r} snp.efi 1000000 + 149280 bytes read in 9 ms (15.8 MiB/s) + => + => load mmc 0:1 ${kernel_addr_r} snp.efi 1000000 100 + 149024 bytes read in 10 ms (14.2 MiB/s) + => + => load mmc 0:1 ${kernel_addr_r} snp.efi 10 + 16 bytes read in 1 ms (15.6 KiB/s) + => + +Configuration +------------- + +The load command is only available if CONFIG_CMD_FS_GENERIC=y. + +Return value +------------ + +The return value $? is set to 0 (true) if the file was successfully loaded +even if the number of bytes is less then the specified length. + +If an error occurs, the return value $? is set to 1 (false). diff --git a/roms/u-boot/doc/usage/loady.rst b/roms/u-boot/doc/usage/loady.rst new file mode 100644 index 000000000..2819cc72a --- /dev/null +++ b/roms/u-boot/doc/usage/loady.rst @@ -0,0 +1,67 @@ +.. SPDX-License-Identifier: GPL-2.0+: + +loady command +============= + +Synopsis +-------- + +:: + + loady [addr [baud]] + +Description +----------- + +The loady command is used to transfer a file to the device via the serial line +using the YMODEM protocol. + +The number of transferred bytes is saved in environment variable filesize. + +addr + load address, defaults to environment variable loadaddr or if loadaddr is + not set to configuration variable CONFIG_SYS_LOAD_ADDR + +baud + baud rate for the ymodem transmission. After the transmission the baud + rate is reset to the original value. + +Example +------- + +In the example below the terminal emulation program picocom was used to +transfer a file to the device. + +After entering the loady command the key sequence <CTRL-A><CTRL-S> is used to +let picocom prompt for the file name. Picocom invokes the program sz for the +file transfer. + +:: + + => loady 80064000 115200 + ## Ready for binary (ymodem) download to 0x80064000 at 115200 bps... + C + *** file: BOOTRISCV64.EFI + $ sz -b -vv BOOTRISCV64.EFI + Sending: BOOTRISCV64.EFI + Bytes Sent: 398976 BPS:7883 + Sending: + Ymodem sectors/kbytes sent: 0/ 0k + Transfer complete + + *** exit status: 0 *** + /1(CAN) packets, 4 retries + ## Total Size = 0x0006165f = 398943 Bytes + => echo ${filesize} + 6165f + => + +Configuration +------------- + +The command is only available if CONFIG_CMD_LOADB=y. + +Return value +------------ + +The return value $? is always 0 (true). diff --git a/roms/u-boot/doc/usage/mbr.rst b/roms/u-boot/doc/usage/mbr.rst new file mode 100644 index 000000000..bddf2f612 --- /dev/null +++ b/roms/u-boot/doc/usage/mbr.rst @@ -0,0 +1,94 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +mbr command +=========== + +Synopsis +-------- + +:: + + mbr verify [interface] [device no] [partition list] + mbr write [interface] [device no] [partition list] + +Description +----------- + +The mbr command lets users create or verify the MBR (Master Boot Record) +partition layout based on the provided text description. The partition +layout is alternatively read from the 'mbr_parts' environment variable. +This can be used in scripts to help system image flashing tools to ensure +proper partition layout. + +The syntax of the text description of the partition list is similar to +the one used by the 'gpt' command. + +Supported partition parameters are: + +* name (currently ignored) +* start (partition start offset in bytes) +* size (in bytes or '-' to expand it to the whole free area) +* bootable (boolean flag) +* id (MBR partition type) + +If one wants to create more than 4 partitions, an 'Extended' primary +partition (with 0x05 ID) has to be explicitly provided as a one of the +first 4 entries. + +Here is an example how to create a 6 partitions (3 on the 'extended +volume'), some of the predefined sizes: + +:: + + => setenv mbr_parts 'name=boot,start=4M,size=128M,bootable,id=0x0e; + name=rootfs,size=3072M,id=0x83; + name=system-data,size=512M,id=0x83; + name=[ext],size=-,id=0x05; + name=user,size=-,id=0x83; + name=modules,size=100M,id=0x83; + name=ramdisk,size=8M,id=0x83' + => mbr write mmc 0 + +To check if the layout on the MMC #0 storage device matches the provided +text description one has to issue following command (assuming that +mbr_parts environment variable is set): + +:: + + => mbr verify mmc 0 + +The verify sub-command is especially useful in the system update scripts: + +:: + + => if mbr verify mmc 0; then + echo MBR layout needs to be updated + ... + fi + +The 'mbr write' command returns 0 on success write or 1 on failure. + +The 'mbr verify' returns 0 if the layout matches the one on the storage +device or 1 if not. + +Configuration +------------- + +To use the mbr command you must specify CONFIG_CMD_MBR=y. + +Return value +------------ + +The variable *$?* takes the following values + ++---+------------------------------+ +| 0 | mbr write was succesful | ++---+------------------------------+ +| 1 | mbr write failed | ++---+------------------------------+ +| 0 | mbr verify was succesful | ++---+------------------------------+ +| 1 | mbr verify was not succesful | ++---+------------------------------+ +|-1 | invalid arguments | ++---+------------------------------+ diff --git a/roms/u-boot/doc/usage/md.rst b/roms/u-boot/doc/usage/md.rst new file mode 100644 index 000000000..4c1073ea3 --- /dev/null +++ b/roms/u-boot/doc/usage/md.rst @@ -0,0 +1,106 @@ +.. SPDX-License-Identifier: GPL-2.0+: + +md command +========== + +Synopis +------- + +:: + + md <address>[<data_size>] [<length>] + +Description +----------- + +The md command is used to dump the contents of memory. It uses a standard +format that includes the address, hex data and ASCII display. It supports +various data sizes and uses the endianness of the target. + +The specified data_size and length become the defaults for future memory +commands commands. + +address + start address to display + +data_size + size of each value to display (defaults to .l): + + ========= =================== + data_size Output size + ========= =================== + .b byte + .w word (16 bits) + .l long (32 bits) + .q quadword (64 bits) + ========= =================== + +length + number of values to dump. Defaults to 40 (0d64). Note that this is not + the same as the number of bytes, unless .b is used. + +Note that the format of 'md.b' can be emulated from linux with:: + + # This works but requires using sed to get the extra spaces + # <addr> is the address, <f> is the filename + xxd -o <addr> -g1 <f> |sed 's/ / /' >bad + + # This uses a single tool but the offset always starts at 0 + # <f> is the filename + hexdump -v -e '"%08.8_ax: " 16/1 "%02x " " "' -e '16/1 "%_p" "\n" ' <f> + + +Example +------- + +:: + + => md 10000 + 00010000: 00010000 00000000 f0f30f00 00005596 .............U.. + 00010010: 10011010 00000000 10011010 00000000 ................ + 00010020: 10011050 00000000 b96d4cd8 00007fff P........Lm..... + 00010030: 00000000 00000000 f0f30f18 00005596 .............U.. + 00010040: 10011040 00000000 10011040 00000000 @.......@....... + 00010050: b96d4cd8 00007fff 10011020 00000000 .Lm..... ....... + 00010060: 00000003 000000c3 00000000 00000000 ................ + 00010070: 00000000 00000000 f0e892f3 00005596 .............U.. + 00010080: 00000000 000000a1 00000000 00000000 ................ + 00010090: 00000000 00000000 f0e38aa6 00005596 .............U.. + 000100a0: 00000000 000000a6 00000022 00000000 ........"....... + 000100b0: 00000001 00000000 f0e38aa1 00005596 .............U.. + 000100c0: 00000000 000000be 00000000 00000000 ................ + 000100d0: 00000000 00000000 00000000 00000000 ................ + 000100e0: 00000000 00000000 00000000 00000000 ................ + 000100f0: 00000000 00000000 00000000 00000000 ................ + => md.b 10000 + 00010000: 00 00 01 00 00 00 00 00 00 0f f3 f0 96 55 00 00 .............U.. + 00010010: 10 10 01 10 00 00 00 00 10 10 01 10 00 00 00 00 ................ + 00010020: 50 10 01 10 00 00 00 00 d8 4c 6d b9 ff 7f 00 00 P........Lm..... + 00010030: 00 00 00 00 00 00 00 00 18 0f f3 f0 96 55 00 00 .............U.. + => md.b 10000 10 + 00010000: 00 00 01 00 00 00 00 00 00 0f f3 f0 96 55 00 00 .............U.. + => + 00010010: 10 10 01 10 00 00 00 00 10 10 01 10 00 00 00 00 ................ + => + 00010020: 50 10 01 10 00 00 00 00 d8 4c 6d b9 ff 7f 00 00 P........Lm..... + => + => md.q 10000 + 00010000: 0000000000010000 00005596f0f30f00 .............U.. + 00010010: 0000000010011010 0000000010011010 ................ + 00010020: 0000000010011050 00007fffb96d4cd8 P........Lm..... + 00010030: 0000000000000000 00005596f0f30f18 .............U.. + 00010040: 0000000010011040 0000000010011040 @.......@....... + 00010050: 00007fffb96d4cd8 0000000010011020 .Lm..... ....... + 00010060: 000000c300000003 0000000000000000 ................ + 00010070: 0000000000000000 00005596f0e892f3 .............U.. + +The empty commands cause a 'repeat', so that md shows the next available data +in the same format as before. + + +Return value +------------ + +The return value $? is always 0 (true). + + diff --git a/roms/u-boot/doc/usage/mmc.rst b/roms/u-boot/doc/usage/mmc.rst new file mode 100644 index 000000000..f20efe3d7 --- /dev/null +++ b/roms/u-boot/doc/usage/mmc.rst @@ -0,0 +1,215 @@ +.. SPDX-License-Identifier: GPL-2.0+: + +mmc command +============ + +Synopsis +-------- + +:: + + mmc info + mmc read addr blk# cnt + mmc write addr blk# cnt + mmc erase blk# cnt + mmc rescan + mmc part + mmc dev [dev] [part] + mmc list + mmc wp + mmc bootbus <dev> <boot_bus_width> <reset_boot_bus_width> <boot_mode> + mmc bootpart-resize <dev> <dev part size MB> <RPMB part size MB> + mmc partconf <dev> [[varname] | [<boot_ack> <boot_partition> <partition_access>]] + mmc rst-function <dev> <value> + +Description +----------- + +The mmc command is used to control MMC(eMMC/SD) device. + +The 'mmc info' command displays information (Manufacturer ID, OEM, Name, Bus Speed, Mode, ...) of MMC device. + +The 'mmc read' command reads raw data to memory address from MMC device with block offset and count. + +The 'mmc write' command writes raw data to MMC device from memory address with block offset and count. + + addr + memory address + blk# + start block offset + cnt + block count + +The 'mmc erase' command erases *cnt* blocks on the MMC device starting at block *blk#*. + + blk# + start block offset + cnt + block count + +The 'mmc rescan' command scans the available MMC device. + +The 'mmc part' command displays the list available partition on current mmc device. + +The 'mmc dev' command shows or set current mmc device. + + dev + device number to change + part + partition number to change + +The 'mmc list' command displays the list available devices. + +The 'mmc wp' command enables "power on write protect" function for boot partitions. + +The 'mmc bootbus' command sets the BOOT_BUS_WIDTH field. (*Refer to eMMC specification*) + + boot_bus_width + 0x0 + x1 (sdr) or x4(ddr) buswidth in boot operation mode (default) + 0x1 + x4 (sdr/ddr) buswidth in boot operation mode + 0x2 + x8 (sdr/ddr) buswidth in boot operation mode + 0x3 + Reserved + + reset_boot_bus_width + 0x0 + Reset buswidth to x1, Single data reate and backward compatible timing after boot operation (default) + 0x1 + Retain BOOT_BUS_WIDTH and BOOT_MODE value after boot operation. This is relevant to Push-pull mode operation only + + boot_mode + 0x0 + Use single data rate + backward compatible timing in boot operation (default) + 0x1 + Use single data rate + High Speed timing in boot operation mode + 0x2 + Use dual data rate in boot operation + 0x3 + Reserved + +The 'mmc partconf' command shows or changes PARTITION_CONFIG field. + + varname + When showing the PARTITION_CONFIG, an optional environment variable to store the current boot_partition value into. + boot_ack + boot acknowledge value + boot_partition + boot partition to enable for boot + 0x0 + Device not boot enabled(default) + 0x1 + Boot partition1 enabled for boot + 0x2 + Boot partition2 enabled for boot + 0x7 + User area enabled for boot + others + Reserved + partition_access + partitions to access + +The 'mmc bootpart-resize' command changes sizes of boot and RPMB partitions. + + dev + device number + boot part size MB + target size of boot partition + RPMB part size MB + target size of RPMB partition + +The 'mmc rst-function' command changes the RST_n_FUNCTION field. +**WARNING** : This is a write-once field. (*Refer to eMMC specification*) + + value + 0x0 + RST_n signal is temporarily disabled (default) + 0x1 + RST_n signal is permanently enabled + 0x2 + RST_n signal is permanently disabled + 0x3 + Reserved + + +Examples +-------- + +The 'mmc info' command displays device's capabilities: +:: + + => mmc info + Device: EXYNOS DWMMC + Manufacturer ID: 45 + OEM: 100 + Name: SDW16 + Bus Speed: 52000000 + Mode: MMC DDR52 (52MHz) + Rd Block Len: 512 + MMC version 5.0 + High Capacity: Yes + Capacity: 14.7 GiB + Bus Width: 8-bit DDR + Erase Group Size: 512 KiB + HC WP Group Size: 8 MiB + User Capacity: 14.7 GiB WRREL + Boot Capacity: 4 MiB ENH + RPMB Capacity: 4 MiB ENH + Boot area 0 is not write protected + Boot area 1 is not write protected + +The raw data can be read/written via 'mmc read/write' command: +:: + + => mmc read 0x40000000 0x5000 0x100 + MMC read: dev # 0, block # 20480, count 256 ... 256 blocks read: OK + + => mmc write 0x40000000 0x5000 0x10 + MMC write: dev # 0, block # 20480, count 256 ... 256 blocks written: OK + +The partition list can be shown via 'mmc part' command: +:: + + => mmc part + Partition Map for MMC device 0 -- Partition Type: DOS + + Part Start Sector Num Sectors UUID Type + 1 8192 131072 dff8751a-01 0e Boot + 2 139264 6291456 dff8751a-02 83 + 3 6430720 1048576 dff8751a-03 83 + 4 7479296 23298048 dff8751a-04 05 Extd + 5 7481344 307200 dff8751a-05 83 + 6 7790592 65536 dff8751a-06 83 + 7 7858176 16384 dff8751a-07 83 + 8 7876608 22900736 dff8751a-08 83 + +The current device can be shown or set via 'mmc dev' command: +:: + + => mmc dev + switch to partitions #0, OK + mmc0(part0) is current device + => mmc dev 2 0 + switch to partitions #0, OK + mmc2 is current device + +The list of available devices can be shown via 'mmc list' command: +:: + + => mmc list + mmc list + EXYNOS DWMMC: 0 (eMMC) + EXYNOS DWMMC: 2 (SD) + +Configuration +------------- + +The mmc command is only available if CONFIG_CMD_MMC=y. +Some commands need to enable more configuration. + +write, erase + CONFIG_MMC_WRITE +bootbus, bootpart-resize, partconf, rst-function + CONFIG_SUPPORT_EMMC_BOOT=y diff --git a/roms/u-boot/doc/usage/netconsole.rst b/roms/u-boot/doc/usage/netconsole.rst new file mode 100644 index 000000000..0156f0212 --- /dev/null +++ b/roms/u-boot/doc/usage/netconsole.rst @@ -0,0 +1,109 @@ +Network console +=============== + +In U-Boot, we implemented the networked console via the standard +"devices" mechanism, which means that you can switch between the +serial and network input/output devices by adjusting the 'stdin' and +'stdout' environment variables. To switch to the networked console, +set either of these variables to "nc". Input and output can be +switched independently. + +The default buffer size can be overridden by setting +CONFIG_NETCONSOLE_BUFFER_SIZE. + +We use an environment variable 'ncip' to set the IP address and the +port of the destination. The format is <ip_addr>:<port>. If <port> is +omitted, the value of 6666 is used. If the env var doesn't exist, the +broadcast address and port 6666 are used. If it is set to an IP +address of 0 (or 0.0.0.0) then no messages are sent to the network. +The source / listening port can be configured separately by setting +the 'ncinport' environment variable and the destination port can be +configured by setting the 'ncoutport' environment variable. + +For example, if your server IP is 192.168.1.1, you could use:: + + => setenv nc 'setenv stdout nc;setenv stdin nc' + => setenv ncip 192.168.1.1 + => saveenv + => run nc + +On the host side, please use this script to access the console + +.. code-block:: bash + + tools/netconsole <ip> [port] + +The script uses netcat to talk to the board over UDP. It requires you to +specify the target IP address (or host name, assuming DNS is working). The +script can be interrupted by pressing ^T (CTRL-T). + +Be aware that in some distributives (Fedora Core 5 at least) +usage of nc has been changed and -l and -p options are considered +as mutually exclusive. If nc complains about options provided, +you can just remove the -p option from the script. + +It turns out that 'netcat' cannot be used to listen to broadcast +packets. We developed our own tool 'ncb' (see tools directory) that +listens to broadcast packets on a given port and dumps them to the +standard output. It will be built when compiling for a board which +has CONFIG_NETCONSOLE defined. If the netconsole script can find it +in PATH or in the same directory, it will be used instead. + +For Linux, the network-based console needs special configuration. +Minimally, the host IP address needs to be specified. This can be +done either via the kernel command line, or by passing parameters +while loading the netconsole.o module (when used in a loadable module +configuration). Please refer to Documentation/networking/logging.txt +file for the original Ingo Molnar's documentation on how to pass +parameters to the loadable module. + +The format of the kernel command line parameter (for the static +configuration) is as follows + +.. code-block:: bash + + netconsole=[src-port]@[src-ip]/[<dev>],[tgt-port]@<tgt-ip>/[tgt-macaddr] + +where + +src-port + source for UDP packets (defaults to 6665) + +src-ip + source IP to use (defaults to the interface's address) + +dev + network interface (defaults to eth0) + +tgt-port + port for logging agent (defaults to 6666) + +tgt-ip + IP address for logging agent (this is the required parameter) + +tgt-macaddr + ethernet MAC address for logging agent (defaults to broadcast) + +Examples + +.. code-block:: bash + + netconsole=4444@10.0.0.1/eth1,9353@10.0.0.2/12:34:56:78:9a:bc + netconsole=@/,@192.168.3.1/ + +Please note that for the Linux networked console to work, the +ethernet interface has to be up by the time the netconsole driver is +initialized. This means that in case of static kernel configuration, +the respective Ethernet interface has to be brought up using the "IP +Autoconfiguration" kernel feature, which is usually done by defaults +in the ELDK-NFS-based environment. + +To browse the Linux network console output, use the 'netcat' tool invoked +as follows: + +.. code-block:: bash + + nc -u -l -p 6666 + +Note that unlike the U-Boot implementation the Linux netconsole is +unidirectional, i. e. you have console output only in Linux. diff --git a/roms/u-boot/doc/usage/partitions.rst b/roms/u-boot/doc/usage/partitions.rst new file mode 100644 index 000000000..2c1a12b6b --- /dev/null +++ b/roms/u-boot/doc/usage/partitions.rst @@ -0,0 +1,80 @@ +.. SPDX-License-Identifier: GPL-2.0+ +.. _partitions: + +Partitions +========== + +Synopsis +-------- + +:: + + <command> <interface> [devnum][.hwpartnum][:partnum|#partname] + +Description +----------- + +Many U-Boot commands allow specifying partitions (or whole disks) using a +generic syntax. + +interface + The interface used to access the partition's device, like ``mmc`` or + ``scsi``. For a full list of supported interfaces, consult the + ``if_typename_str`` array in ``drivers/block/blk-uclass.c`` + +devnum + The device number. This defaults to 0. + +hwpartnum + The hardware partition number. All devices have at least one hardware + partition. On most devices, hardware partition 0 specifies the whole + device. On eMMC devices, hardware partition 0 is the user partition, + hardware partitions 1 and 2 are the boot partitions, hardware partition + 3 is the RPMB partition, and further partitions are general-purpose + user-created partitions. The default hardware partition number is 0. + +partnum + The partition number, starting from 1. The partition number 0 specifies + that the whole device is to be used as one "partition." + +partname + The partition name. This is the partition label for GPT partitions. For + MBR partitions, the following syntax is used:: + + <devtype><devletter><partnum> + + devtype + A device type like ``mmcsd`` or ``hd``. See the + ``part_set_generic_name`` function in ``disk/part.c`` for a + complete list. + + devletter + The device number as an offset from ``a``. For example, device + number 2 would have a device letter of ``c``. + + partnum + The partition number. This is the same as above. + +If neither ``partname`` nor ``partnum`` is specified and there is a partition +table, then partition 1 is used. If there is no partition table, then the whole +device is used as one "partition." If none of ``devnum``, ``hwpartnum``, +``partnum``, or ``partname`` is specified, or only ``-`` is specified, then +``devnum`` defaults to the value of the ``bootdevice`` environmental variable. + +Examples +-------- + +List the root directory contents on MMC device 2, hardware partition 1, +and partition number 3:: + + ls mmc 2.1:3 / + +Load ``/kernel.itb`` to address ``0x80000000`` from SCSI device 0, hardware partition +0, and the partition labeled ``boot``:: + + load scsi #boot 0x80000000 /kernel.itb + +Print the partition UUID of the SATA device ``$bootdevice``, hardware partition +0, and partition number 0:: + + part uuid sata - diff --git a/roms/u-boot/doc/usage/pinmux.rst b/roms/u-boot/doc/usage/pinmux.rst new file mode 100644 index 000000000..9f4392cd0 --- /dev/null +++ b/roms/u-boot/doc/usage/pinmux.rst @@ -0,0 +1,95 @@ +.. SPDX-License-Identifier: GPL-2.0+: + +pinmux command +============== + +Synopsis +-------- + +:: + + pinmux list + pinmux dev [pincontroller-name] + pinmux status [-a | pin-name] + +Description +----------- + +The pinmux command is used to show the pin-controller muxing. + +The 'pinmux list' command diplays the available pin-controller. + +The 'pinmux dev' command selects the pin-controller for next commands. + + pincontroller-name + name of the pin-controller to select + +The 'pinmux status' command displays the pin muxing information. + + \-a + display pin muxing of all pin-controllers. + pin-name + name of the pin to display + +Example +------- + +:: + + => pinmux list + | Device | Driver | Parent + | pinctrl-gpio | sandbox_pinctrl_gpio | root_driver + | pinctrl | sandbox_pinctrl | root_driver + => + => pinmux dev pinctrl + dev: pinctrl + => + => pinmux status + P0 : UART TX. + P1 : UART RX. + P2 : I2S SCK. + P3 : I2S SD. + P4 : I2S WS. + P5 : GPIO0 bias-pull-up input-disable. + P6 : GPIO1 drive-open-drain. + P7 : GPIO2 bias-pull-down input-enable. + P8 : GPIO3 bias-disable. + => + => pinmux status P0 + P0 : UART TX. + => + => pinmux status -a + -------------------------- + pinctrl-gpio: + a0 : gpio input . + a1 : gpio input . + a2 : gpio input . + a3 : gpio input . + a4 : gpio input . + a5 : gpio output . + a6 : gpio output . + a7 : gpio input . + a8 : gpio input . + a9 : gpio input . + -------------------------- + pinctrl: + P0 : UART TX. + P1 : UART RX. + P2 : I2S SCK. + P3 : I2S SD. + P4 : I2S WS. + P5 : GPIO0 bias-pull-up input-disable. + P6 : GPIO1 drive-open-drain. + P7 : GPIO2 bias-pull-down input-enable. + P8 : GPIO3 bias-disable. + +Configuration +------------- + +The pinmux command is only available if CONFIG_CMD_PINMUX=y. + +Return value +------------ + +The return value $? is set to 0 (true) if the command succeded and to 1 (false) +otherwise. diff --git a/roms/u-boot/doc/usage/pstore.rst b/roms/u-boot/doc/usage/pstore.rst new file mode 100644 index 000000000..1c8374513 --- /dev/null +++ b/roms/u-boot/doc/usage/pstore.rst @@ -0,0 +1,93 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +pstore command +============== + +Synopsis +-------- + +:: + + pstore set <addr> <len> [record-size] [console-size] [ftrace-size] [pmsg_size] [ecc-size] + pstore display [record-type] [nb] + pstore save <interface> <dev[:part]> <directory-path> + +Design +------ + +Linux PStore and Ramoops modules (Linux config options PSTORE and PSTORE_RAM) +allow to use memory to pass data from the dying breath of a crashing kernel to +its successor. This command allows to read those records from U-Boot command +line. + +Ramoops is an oops/panic logger that writes its logs to RAM before the system +crashes. It works by logging oopses and panics in a circular buffer. Ramoops +needs a system with persistent RAM so that the content of that area can survive +after a restart. + +Ramoops uses a predefined memory area to store the dump. + +Ramoops parameters can be passed as kernel parameters or through Device Tree, +i.e.:: + + ramoops.mem_address=0x30000000 ramoops.mem_size=0x100000 ramoops.record_size=0x2000 ramoops.console_size=0x2000 memmap=0x100000$0x30000000 + +The same values should be set in U-Boot to be able to retrieve the records. +This values can be set at build time in U-Boot configuration file, or at runtime. +U-Boot automatically patches the Device Tree to pass the Ramoops parameters to +the kernel. + +The PStore configuration parameters are: + +======================= ========== + Name Default +======================= ========== +CMD_PSTORE_MEM_ADDR +CMD_PSTORE_MEM_SIZE 0x10000 +CMD_PSTORE_RECORD_SIZE 0x1000 +CMD_PSTORE_CONSOLE_SIZE 0x1000 +CMD_PSTORE_FTRACE_SIZE 0x1000 +CMD_PSTORE_PMSG_SIZE 0x1000 +CMD_PSTORE_ECC_SIZE 0 +======================= ========== + +Records sizes should be a power of 2. +The memory size and the record/console size must be non-zero. + +Multiple 'dump' records can be stored in the memory reserved for PStore. +The memory size has to be larger than the sum of the record sizes, i.e.:: + + MEM_SIZE >= RECORD_SIZE * n + CONSOLE_SIZE + FTRACE_SIZE + PMSG_SIZE + +Usage +----- + +Generate kernel crash +~~~~~~~~~~~~~~~~~~~~~ + +For test purpose, you can generate a kernel crash by setting reboot timeout to +10 seconds and trigger a panic + +.. code-block:: console + + $ sudo sh -c "echo 1 > /proc/sys/kernel/sysrq" + $ sudo sh -c "echo 10 > /proc/sys/kernel/panic" + $ sudo sh -c "echo c > /proc/sysrq-trigger" + +Retrieve logs in U-Boot +~~~~~~~~~~~~~~~~~~~~~~~ + +First of all, unless PStore parameters as been set during U-Boot configuration +and match kernel ramoops parameters, it needs to be set using 'pstore set', e.g.:: + + => pstore set 0x30000000 0x100000 0x2000 0x2000 + +Then all available dumps can be displayed +using:: + + => pstore display + +Or saved to an existing directory in an Ext2 or Ext4 partition, e.g. on root +directory of 1st partition of the 2nd MMC:: + + => pstore save mmc 1:1 / diff --git a/roms/u-boot/doc/usage/qfw.rst b/roms/u-boot/doc/usage/qfw.rst new file mode 100644 index 000000000..87463e1e5 --- /dev/null +++ b/roms/u-boot/doc/usage/qfw.rst @@ -0,0 +1,89 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +qfw command +=========== + +Synopsis +-------- + +:: + + qfw list + qfw cpus + qfw load [kernel_addr [initrd_addr]] + +Description +----------- + +The *qfw* command is used to retrieve information form the QEMU firmware. + +The *qfw list* sub-command displays the QEMU firmware files. + +The *qfw cpus* sub-command displays the available CPUs. + +The *qfw load* command is used to load a kernel and an initial RAM disk. + +kernel_addr + address to which the file specified by the -kernel parameter of QEMU shall + be loaded. Defaults to environment variable *loadaddr* and further to + the value of *CONFIG_LOADADDR*. + +initrd_addr + address to which the file specified by the -initrd parameter of QEMU shall + be loaded. Defaults to environment variable *ramdiskaddr* and further to + the value of *CONFIG_RAMDISK_ADDR*. + +Examples +-------- + +QEMU firmware files are listed via the *qfw list* command: + +:: + + => qfw list + etc/boot-fail-wait + etc/smbios/smbios-tables + etc/smbios/smbios-anchor + etc/e820 + genroms/kvmvapic.bin + genroms/linuxboot.bin + etc/system-states + etc/acpi/tables + etc/table-loader + etc/tpm/log + etc/acpi/rsdp + bootorder + +The available CPUs can be shown via the *qfw cpus* command: + +:: + + => qfw cpu + 2 cpu(s) online + +The *-kernel* and *-initrd* parameters allow to specify a kernel and an +initial RAM disk for QEMU: + +.. code-block:: bash + + $ qemu-system-x86_64 -machine pc-i440fx-2.5 -bios u-boot.rom -m 1G \ + -nographic -kernel vmlinuz -initrd initrd + +Now the kernel and the initial RAM disk can be loaded to the U-Boot memory via +the *qfw load* command and booted thereafter. + +:: + + => qfw load ${kernel_addr_r} ${ramdisk_addr_r} + loading kernel to address 0000000001000000 size 5048f0 initrd 0000000004000000 size 3c94891 + => zboot 1000000 5048f0 4000000 3c94891 + Valid Boot Flag + Magic signature found + Linux kernel version 4.19.0-14-amd64 (debian-kernel@lists.debian.org) #1 SMP Debian 4.19.171-2 (2021-01-30) + Building boot_params at 0x00090000 + Loading bzImage at address 100000 (5260160 bytes) + +Configuration +------------- + +The qfw command is only available if CONFIG_CMD_QFW=y. diff --git a/roms/u-boot/doc/usage/reset.rst b/roms/u-boot/doc/usage/reset.rst new file mode 100644 index 000000000..384d5d60f --- /dev/null +++ b/roms/u-boot/doc/usage/reset.rst @@ -0,0 +1,26 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +reset command +============= + +Synopsis +-------- + +:: + + reset [-w] + +Description +----------- + +Perform reset of the CPU. By default does COLD reset, which resets CPU, +DDR and peripherals, on some boards also resets external PMIC. + +-w + Do warm WARM, reset CPU but keep peripheral/DDR/PMIC active. + + +Return value +------------ + +The return value $? is always set to 0 (true). diff --git a/roms/u-boot/doc/usage/sbi.rst b/roms/u-boot/doc/usage/sbi.rst new file mode 100644 index 000000000..96d886105 --- /dev/null +++ b/roms/u-boot/doc/usage/sbi.rst @@ -0,0 +1,49 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +sbi command +=========== + +Synopsis +-------- + +:: + + sbi + +Description +----------- + +The sbi command is used to display information about the SBI (Supervisor Binary +Interface) implementation on RISC-V systems. + +The output may look like: + +:: + + => sbi + SBI 0.2 + OpenSBI + Extensions: + sbi_set_timer + sbi_console_putchar + sbi_console_getchar + sbi_clear_ipi + sbi_send_ipi + sbi_remote_fence_i + sbi_remote_sfence_vma + sbi_remote_sfence_vma_asid + sbi_shutdown + SBI Base Functionality + Timer Extension + IPI Extension + RFENCE Extension + Hart State Management Extension + +The first line indicates the version of the RISC-V SBI specification. +The second line indicates the implementation. +The further lines enumerate the implemented extensions. + +Configuration +------------- + +To use the sbi command you must specify CONFIG_CMD_SBI=y. diff --git a/roms/u-boot/doc/usage/scp03.rst b/roms/u-boot/doc/usage/scp03.rst new file mode 100644 index 000000000..7ff87ed85 --- /dev/null +++ b/roms/u-boot/doc/usage/scp03.rst @@ -0,0 +1,33 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +scp03 command +============= + +Synopsis +-------- + +:: + + scp03 enable + scp03 provision + +Description +----------- + +The *scp03* command calls into a Trusted Application executing in a +Trusted Execution Environment to enable (if present) the Secure +Channel Protocol 03 stablished between the processor and the secure +element. + +This protocol encrypts all the communication between the processor and +the secure element using a set of pre-defined keys. These keys can be +rotated (provisioned) using the *provision* request. + +See also +-------- + +For some information on the internals implemented in the TEE, please +check the GlobalPlatform documentation on `Secure Channel Protocol '03'`_ + +.. _Secure Channel Protocol '03': + https://globalplatform.org/wp-content/uploads/2014/07/GPC_2.3_D_SCP03_v1.1.2_PublicRelease.pdf diff --git a/roms/u-boot/doc/usage/size.rst b/roms/u-boot/doc/usage/size.rst new file mode 100644 index 000000000..f0c35e482 --- /dev/null +++ b/roms/u-boot/doc/usage/size.rst @@ -0,0 +1,40 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +size command +============ + +Synopsis +-------- + +:: + + size <interface> <dev[:part]> <filename> + +Description +----------- + +The size command determines the size of a file and sets the environment variable +filesize to this value. If filename points to a directory, the value is set to +zero. + +If the command fails, the filesize environment variable is not changed. + +dev + device number + +part + partition number, defaults to 1 + +filename + path to file + +Configuration +------------- + +The size command is only available if CONFIG_CMD_FS_GENERIC=y. + +Return value +------------ + +The return value $? is set to 0 (true) if the command succeded and to 1 (false) +otherwise. diff --git a/roms/u-boot/doc/usage/true.rst b/roms/u-boot/doc/usage/true.rst new file mode 100644 index 000000000..f9ef71b2d --- /dev/null +++ b/roms/u-boot/doc/usage/true.rst @@ -0,0 +1,28 @@ +true command +============ + +Synopsis +-------- + +:: + + true + +Description +----------- + +The true command sets the return value $? to 0 (true). + +Example +------- + +:: + + => true; echo $? + 0 + => + +Configuration +------------- + +The true command is only available if CONFIG_HUSH_PARSER=y. diff --git a/roms/u-boot/doc/usage/ums.rst b/roms/u-boot/doc/usage/ums.rst new file mode 100644 index 000000000..3cde5fa1f --- /dev/null +++ b/roms/u-boot/doc/usage/ums.rst @@ -0,0 +1,57 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +ums command +=========== + +Synopsis +-------- + +:: + + ums <dev> [<interface>] <devnum[:partnum]> + +Description +----------- + +Use the USB Mass Storage class (also known as UMS) to make accessible an U-Boot +block device (fully or with :ref:`U-Boot's partition syntax <partitions>`) +to a USB host and to enable file transfers. U-Boot, the USB device, acts as a +simple external hard drive plugged on the host USB port. + +This command "ums" stays in the USB's treatment loop until user enters Ctrl-C. + +dev + USB gadget device number + +interface + interface for accessing the block device (mmc, sata, scsi, usb, ....) + defaults is "mmc" + +devnum + device number for selected interface + +partnum + partition number or 0 to expose all partitions, defaults to 0 + +Example +------- + +:: + + => ums 0 mmc 0 + => ums 0 usb 1:2 + +Configuration +------------- + +The ums command is only available if CONFIG_CMD_USB_MASS_STORAGE=y +and depends on CONFIG_USB_USB_GADGET and CONFIG_BLK. + +Return value +------------ + +The return value $? is set to 0 (true) when the USB stack was successfully +started and interrupted, with Ctrl-C or after USB cable issue (detection +timeout or cable removal). + +If an error occurs, the return value $? is set to 1 (false). diff --git a/roms/u-boot/doc/usage/x86/cbsysinfo.rst b/roms/u-boot/doc/usage/x86/cbsysinfo.rst new file mode 100644 index 000000000..8c03a8516 --- /dev/null +++ b/roms/u-boot/doc/usage/x86/cbsysinfo.rst @@ -0,0 +1,25 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +cbsysinfo +========= + +Synopis +------- + +:: + + cbsysinfo + + +Description +----------- + +This displays information obtained from the coreboot sysinfo table. It is only +useful when booting U-Boot from coreboot. + +Example +------- + +:: + + => cbsysinfo |