diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/README.log | 214 | ||||
| -rw-r--r-- | doc/README.rockchip | 10 | ||||
| -rw-r--r-- | doc/device-tree-bindings/clock/snps,hsdk-cgu.txt | 35 | ||||
| -rw-r--r-- | doc/device-tree-bindings/config.txt | 6 | ||||
| -rw-r--r-- | doc/device-tree-bindings/fpga/altera-socfpga-a10-fpga-mgr.txt | 19 | ||||
| -rw-r--r-- | doc/device-tree-bindings/regulator/regulator.txt | 16 | ||||
| -rw-r--r-- | doc/device-tree-bindings/spi/spi-atcspi200.txt | 37 | ||||
| -rw-r--r-- | doc/device-tree-bindings/timer/atcpit100_timer.txt | 31 | ||||
| -rw-r--r-- | doc/git-mailrc | 1 | ||||
| -rw-r--r-- | doc/uImage.FIT/source_file_format.txt | 3 |
10 files changed, 364 insertions, 8 deletions
diff --git a/doc/README.log b/doc/README.log new file mode 100644 index 0000000000..f653fe7d79 --- /dev/null +++ b/doc/README.log @@ -0,0 +1,214 @@ +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, in increasing order of verbosity: + + LOGL_EMERG - Printed before U-Boot halts + LOGL_ALERT - Indicates action must be taken immediate or U-Boot will crash + LOGL_CRIT - Indicates a critical error that will cause boot failure + LOGL_ERR - Indicates an error that may cause boot failure + LOGL_WARNING - Warning about an unexpected condition + LOGL_NOTE - Important information about progress + LOGL_INFO - Information about normal boot progress + LOGL_DEBUG - Debug information (useful for debugging a driver or subsystem) + LOGL_DEBUG_CONTENT - Debug message showing full message content + LOGL_DEBUG_IO - Debug message showing hardware I/O access + + +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. + +The following main categories are defined: + + LOGC_NONE - Unknown category (e.g. a debug() statement) + UCLASS_... - Related to a particular uclass (e.g. UCLASS_USB) + LOGC_ARCH - Related to architecture-specific code + LOGC_BOARD - Related to board-specific code + LOGC_CORE - Related to core driver-model support + LOGC_DT - Related to device tree control + + +Enabling logging +---------------- + +The following options are used to enable logging at compile time: + + CONFIG_LOG - Enables the logging system + CONFIG_MAX_LOG_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 versions also, e.g. CONFIG_SPL_MAX_LOG_LEVEL. + + +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 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 + + +Filters +------- + +Filters are attached to log drivers to control what those drivers emit. Only +records that pass through the filter make it to the driver. + +Filters can be based on several criteria: + + - 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_LOG_MAX_LEVEL. + + +Logging statements +------------------ + +The main logging function is: + + 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. + + +Code size +--------- + +Code size impact depends largely on what is enabled. The following numbers are +for snow, which is a Thumb-2 board: + +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/py/tests/test_log.py + +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 + +Convenience functions to support a category defined for a single file, for +example: + + #define LOG_CATEGORY UCLASS_USB + +all of these can use LOG_CATEGORY as the category, and a log level +corresponding to the function name: + + logc(level, format_string, ...) + +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 a 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() + +Figure out what to do with assert() + +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 filters + +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 + +Add a command-line option to sandbox to set the default logging level + +Convert core driver model code to use logging + +Convert uclasses to use logging with the correct category + +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 + +Enhance the log console driver to show level / category / file / line +information + +Add a command to add new log records and delete existing records. + +Provide additional log() functions - e.g. logc() to specify the category + +-- +Simon Glass <sjg@chromium.org> +15-Sep-17 diff --git a/doc/README.rockchip b/doc/README.rockchip index da99f301ff..597f068aca 100644 --- a/doc/README.rockchip +++ b/doc/README.rockchip @@ -176,17 +176,17 @@ 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. +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 -cat tpl/u-boot-tpl.bin > tplspl.bin -truncate -s 1020 tplspl.bin -cat spl/u-boot-spl.bin >> tplspl.bin -tools/mkimage -n rk3188 -T rksd -d tplspl.bin out +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 diff --git a/doc/device-tree-bindings/clock/snps,hsdk-cgu.txt b/doc/device-tree-bindings/clock/snps,hsdk-cgu.txt new file mode 100644 index 0000000000..82fe1dd83c --- /dev/null +++ b/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/doc/device-tree-bindings/config.txt b/doc/device-tree-bindings/config.txt index 15e4349c19..6cdc16da5b 100644 --- a/doc/device-tree-bindings/config.txt +++ b/doc/device-tree-bindings/config.txt @@ -46,3 +46,9 @@ 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/doc/device-tree-bindings/fpga/altera-socfpga-a10-fpga-mgr.txt b/doc/device-tree-bindings/fpga/altera-socfpga-a10-fpga-mgr.txt new file mode 100644 index 0000000000..2fd8e7a847 --- /dev/null +++ b/doc/device-tree-bindings/fpga/altera-socfpga-a10-fpga-mgr.txt @@ -0,0 +1,19 @@ +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. + +Example: + + fpga_mgr: fpga-mgr@ffd03000 { + compatible = "altr,socfpga-a10-fpga-mgr"; + reg = <0xffd03000 0x100 + 0xffcfe400 0x20>; + clocks = <&l4_mp_clk>; + resets = <&rst FPGAMGR_RESET>; + }; diff --git a/doc/device-tree-bindings/regulator/regulator.txt b/doc/device-tree-bindings/regulator/regulator.txt index 918711eb4d..65b69c4278 100644 --- a/doc/device-tree-bindings/regulator/regulator.txt +++ b/doc/device-tree-bindings/regulator/regulator.txt @@ -2,7 +2,8 @@ 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. Usually the pmic I/O driver will provide +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: @@ -15,8 +16,19 @@ For the node name e.g.: "prefix[:alpha:]num { ... }": 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 +- 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 diff --git a/doc/device-tree-bindings/spi/spi-atcspi200.txt b/doc/device-tree-bindings/spi/spi-atcspi200.txt new file mode 100644 index 0000000000..9c0630b500 --- /dev/null +++ b/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 = "spi-flash"; + spi-max-frequency = <50000000>; + reg = <0>; + spi-cpol; + spi-cpha; + }; + }; diff --git a/doc/device-tree-bindings/timer/atcpit100_timer.txt b/doc/device-tree-bindings/timer/atcpit100_timer.txt new file mode 100644 index 0000000000..620814e948 --- /dev/null +++ b/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/doc/git-mailrc b/doc/git-mailrc index 556db0a818..5a365cddd9 100644 --- a/doc/git-mailrc +++ b/doc/git-mailrc @@ -133,6 +133,7 @@ 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 diff --git a/doc/uImage.FIT/source_file_format.txt b/doc/uImage.FIT/source_file_format.txt index 6f727a1e8a..88663a161d 100644 --- a/doc/uImage.FIT/source_file_format.txt +++ b/doc/uImage.FIT/source_file_format.txt @@ -288,7 +288,8 @@ In this case the 'data' property is omitted. Instead you can use: 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. +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 |