1.. SPDX-License-Identifier: GPL-2.0+
2.. Copyright (C) 2013, Miao Yan <miao.yan@windriver.com>
3.. Copyright (C) 2015-2018, Bin Meng <bmeng.cn@gmail.com>
4.. Copyright (C) 2019, Lihua Zhao <lihua.zhao@windriver.com>
5
6VxWorks
7=======
8
9This document describes the information about U-Boot loading VxWorks kernel.
10
11Status
12------
13U-Boot supports loading VxWorks kernels via 'bootvx' and 'bootm' commands.
14For booting old kernels (6.9.x) on PowerPC and ARM, and all kernel versions
15on other architectures, 'bootvx' shall be used. For booting VxWorks 7 kernels
16on PowerPC/ARM/RISC-V, 'bootm' shall be used.
17
18With CONFIG_EFI_LOADER option, it's possible to chain load a VxWorks x86 kernel
19via the UEFI boot loader application for VxWorks loaded by 'bootefi' command.
20
21VxWorks 7 on PowerPC/ARM/RISC-V
22-------------------------------
23From VxWorks 7, VxWorks starts adopting device tree as its hardware description
24mechanism (for PowerPC and ARM), thus requiring boot interface changes.
25This section will describe the new interface.
26
27Since VxWorks 7 SR0640 release, VxWorks starts using Linux compatible standard
28DTB for some boards. With that, the exact same bootm flow as used by Linux is
29used, which includes board-specific DTB fix up. To keep backward compatibility,
30only when the least significant bit of flags in bootargs is set, the standard
31DTB will be used. Otherwise it falls back to the legacy bootm flow.
32
33For legacy bootm flow, make sure the least significant bit of flags in bootargs
34is cleared. The calling convention is described below:
35
36For PowerPC, the calling convention of the new VxWorks entry point conforms to
37the ePAPR standard, which is shown below (see ePAPR for more details):
38
39.. code-block:: c
40
41    void (*kernel_entry)(fdt_addr, 0, 0, EPAPR_MAGIC, boot_IMA, 0, 0)
42
43For ARM, the calling convention is shown below:
44
45.. code-block:: c
46
47    void (*kernel_entry)(void *fdt_addr)
48
49When using the Linux compatible standard DTB, the calling convention of VxWorks
50entry point is exactly the same as the Linux kernel.
51
52For RISC-V, there is no legacy bootm flow as VxWorks always uses the same boot
53interface as the Linux kernel, with the calling convention below::
54
55    void (*kernel_entry)(unsigned long hartid, void *fdt_addr)
56
57When booting a VxWorks 7 kernel (uImage format), the parameters passed to bootm
58is like below::
59
60    bootm <kernel image address> - <device tree address>
61
62VxWorks bootline
63----------------
64When using 'bootvx', the kernel bootline must be prepared by U-Boot at a
65board-specific address before loading VxWorks. U-Boot supplies its address
66via "bootaddr" environment variable. To check where the bootline should be
67for a specific board, go to the VxWorks BSP for that board, and look for a
68parameter called BOOT_LINE_ADRS. Assign its value to "bootaddr". A typical
69value for "bootaddr" on an x86 board is 0x101200.
70
71If a "bootargs" variable is defined, its content will be copied to the memory
72location pointed by "bootaddr" as the kernel bootline. If "bootargs" is not
73there, command 'bootvx' can construct a valid bootline using the following
74environments variables: bootdev, bootfile, ipaddr, netmask, serverip,
75gatewayip, hostname, othbootargs.
76
77When using 'bootm', just define "bootargs" in the environment and U-Boot will
78handle bootline fix up for the kernel dtb automatically.
79
80When using 'bootefi' to chain load an x86 kernel, the UEFI boot loader
81application for VxWorks takes care of the kernel bootline preparation.
82
83Serial console
84--------------
85It's very common that VxWorks BSPs configure a different baud rate for the
86serial console from what is being used by U-Boot. For example, VxWorks tends
87to use 9600 as the default baud rate on all x86 BSPs while U-Boot uses 115200.
88Please configure both U-Boot and VxWorks to use the same baud rate, or it may
89look like VxWorks hangs somewhere as nothing outputs on the serial console.
90
91x86-specific information
92------------------------
93Before direct loading an x86 kernel via 'bootvx', one additional environment
94variable need to be provided. This is "vx_phys_mem_base", which represent the
95physical memory base address of VxWorks.
96
97Check VxWorks kernel configuration to look for LOCAL_MEM_LOCAL_ADRS. For
98VxWorks 7, this is normally a virtual address and you need find out its
99corresponding physical address and assign its value to "vx_phys_mem_base".
100
101For boards on which ACPI is not supported by U-Boot yet, VxWorks kernel must
102be configured to use MP table and virtual wire interrupt mode. This requires
103INCLUDE_MPTABLE_BOOT_OP and INCLUDE_VIRTUAL_WIRE_MODE to be included in a
104VxWorks kernel configuration.
105
106Both 32-bit x86 and 64-bit x64 kernels can be loaded.
107
108There are two types of graphics console drivers in VxWorks. One is the 80x25
109VGA text mode driver. The other one is the EFI console bitmapped graphics mode
110driver. To make these drivers function, U-Boot needs to load and run the VGA
111BIOS of the graphics card first.
112
113    - If the kernel is configured with 80x25 VGA text mode driver,
114      CONFIG_FRAMEBUFFER_SET_VESA_MODE must be unset in U-Boot.
115    - If the kernel is configured with bitmapped graphics mode driver,
116      CONFIG_FRAMEBUFFER_SET_VESA_MODE need remain set but care must be taken
117      at which VESA mode is to be set. The supported pixel format is 32-bit
118      RGBA, hence the available VESA mode can only be one of the following:
119
120        * FRAMEBUFFER_VESA_MODE_10F
121        * FRAMEBUFFER_VESA_MODE_112
122        * FRAMEBUFFER_VESA_MODE_115
123        * FRAMEBUFFER_VESA_MODE_118
124        * FRAMEBUFFER_VESA_MODE_11B
125