[U-Boot] [PATCH 3/4] rapidio: add documentation for RapidIO boot
jacquiot.aurelien at gmail.com
jacquiot.aurelien at gmail.com
Tue Nov 10 13:13:40 CET 2015
From: Aurelien Jacquiot <a-jacquiot at ti.com>
This commit adds the RapidIO boot functionality documentation.
Its explains what RapidIO boot feature does, how to use it and the
basic API that must be provided by a RapidIO hw controller driver.
Signed-off-by: Aurelien Jacquiot <a-jacquiot at ti.com>
---
doc/README.rapidio | 158 ++++++++++++++++++++++++++++++++++++++++++++++++++++
1 files changed, 158 insertions(+), 0 deletions(-)
create mode 100644 doc/README.rapidio
diff --git a/doc/README.rapidio b/doc/README.rapidio
new file mode 100644
index 0000000..e360a7f
--- /dev/null
+++ b/doc/README.rapidio
@@ -0,0 +1,158 @@
+ RapidIO support for TI KeyStone devices
+ =======================================
+
+
+This feature allows to boot a device through RapidIO using DirectI/O (DIO).
+A new set of commands is added to U-Boot for this purpose.
+
+This feature is today designed to work with Texas Instruments KeyStone devices
+but may be easily extended to be used on different architectures.
+
+How it works
+------------
+
+This booting mechanism uses the DirectI/O functionality which allows a
+remote devices to directly read and write into the device address space
+(so basically here into the DDR or any mapped memory such as MSM).
+
+The boot sequence is pretty simple. The RIO boot initializes the RapidIO
+controller then the link partner needs to push the various images (kernel,
+fdt, ...). When images are loaded into their respective locations by the peer,
+U-Boot can start the images normally like with any other boot mechanismes.
+
+It is the link partner responsability to push the various images in the device
+memory then signaling U-Boot that images have been loaded.
+
+for that purpose, the simpler way is to use the 'mwait' U-Boot command which
+allows to wait a defined value in memory. The link partner has only to write
+the expected value at a given address when it has pushed all images.
+
+Basically the sequence should be the following (A is the device to be booted, B
+is the link partner device which pushes the images to boot):
+
+ [B]: board is up and booted, RapidIO controller is initialized but not the link
+ [A]: board is powered on, entering U-Boot
+ [A]: the 'rio init' command is called
+ [A]: U-Boot configures the local RapidIO controller and hardware waits the link
+ establishement
+ [B]: Linux kernel starts the RapidIO link configuration and eventually the
+ RapidIO enumeration/discovery process (see Linux kernel RapidIO subsytem
+ driver for more information)
+ [AB]: RapidIO link is now established between the both link partners
+ [A]: the 'mwait 0x80000000 0xbadface' command is called
+ [A]: U-Boot reads the first word at beginning of the DDR in loop and waits
+ until it is set to 0xbadface
+ [B]: system pushes the kernel image using DIO
+ [B]: system pushes the dtb image using DIO
+ [B]: system pushes the skern image using DIO
+ [B]: system set the 0xbadface value at the first word of the remote DDR
+ [A]: U-Boot detects that first DDR word has changed to 0xbadface and exits the
+ mwait command
+ [A]: skern, fdt and kernel can be installed and started normally with the
+ 'mon_install' and 'bootm' U-Boot commands
+
+RapidIO subsystem commands
+--------------------------
+
+ - rio init [dev_id] [id_size] [port_mask] [pathmode] [baudrate]:
+ This command is used to initialize the RapidIO controller. Optional
+ parameters are used to define the RapidIO configuration.
+ Note that environment variables can be instead of parameters.
+
+ 1) dev_id ('riohdid' environment variable) to set the host device Id.
+ By default if not specified it is set to -1.
+
+ 2) id_size ('riosize' environment variable) to indicate the Ids size
+ (0 for small, 1 for big). By default it is set to 0 (small Ids).
+
+ 3) port_mask ('rioports' environment variable) is a bitmask of ports to use.
+ By default it is set to 0x1 (port 0).
+
+ 4) pathmode ('riopathmode' environment variable) defines the port path mode
+ (mapping of ports over lanes). The default mode is 0 (4 independent ports
+ in 1x).
+
+ 5) baudrate ('riobaudrate' environment variable) defines the port speed:
+ 0 for 1.25Gbps, 1 for 2.5Gbps, 2 for 3.125Gbps, 3 for 5Gbps and 4 for
+ 6.25Gpbs (if supported). It is set by default to 2 (2.5Gbps).
+
+ - rio shutdown: It disables the RapidIO controller.
+
+ - rio r port dev_id hopcount offset: This command allows to read the remote
+ RapidIO configuration space by performing a maintenance read request.
+
+ - rio w port dev_id hopcount offset value: This command allows to write into
+ the remote RapidIO configuration space by performing a maintenance write
+ request.
+
+ - rio lr offset: This performs a local RapidIO configuration space read.
+
+ - rio lw offset value: This performs a local RapidIO configuration space write.
+
+Device support
+--------------
+
+The RapidIO controller of the KeyStone devices is supported through the
+drivers/rapidio/keystone_rio.c device driver.
+
+The RapidIO driver must export the following functions (see include/rio.h for
+full prototypes).
+
+ - rio_init() : initialize RapidIO controller
+ - rio_shutdown(): shutdown RapidIO controller
+ - rio_config_read(): perform a RapidIO maintenance read transaction
+ - rio_config_write(): perform a RapidIO maintenance read transaction
+ - rio_local_config_read(): local configuration space read
+ - rio_local_config_write(): local configuration space write
+
+Booting with RapidIO
+--------------------
+
+Example of RapidIO booting with U-Boot:
+
+K2HK EVM # rio init -1 0 0x1 4 3
+rioboot: waiting for link up ...
+KeyStone RapidIO driver v1.1, hdid=-1
+RIO: initializing 5.00 Gbps interface with port configuration 4
+RIO: port RIO0 ready
+K2HK EVM # mwait 0x80000000 0xbadface
+waiting 0xbadface at 0x80000000...
+K2HK EVM # mon_install ${addr_mon}
+## installed monitor, freq [200000000], status 0
+K2HK EVM # bootm ${addr_kern} ${addr_uninitrd} ${addr_fdt}
+## Booting kernel from Legacy Image at 88000000 ...
+ Image Name: Linux-3.8.4
+ Created: 2014-01-27 17:48:10 UTC
+ Image Type: ARM Linux Kernel Image (uncompressed)
+ Data Size: 3990680 Bytes = 3.8 MiB
+ Load Address: 80008000
+ Entry Point: 80008000
+ Verifying Checksum ... OK
+
+-----
+
+Here is an example under Linux using the riodio utility and the riodev feature
+of the booting of a remote device which uses U-Boot RapidIO booting mechanism
+(like the example above):
+
+# riodio -f uImage /dev/rio0.1 0x88000000
+# riodio -f k2hk-evm.dtb /dev/rio0.1 0x87000000
+# riodio -f skern-keystone-evm.bin /dev/rio0.1 0xc5f0000
+# riodio -v 0xbadface /dev/rio0.1 0x80000000
+
+This will push the various images and notify U-Boot.
+
+-----
+
+Example of (local and remote) read/write commands:
+
+K2HK EVM # rio r 0 -1 1 0x0
+00000000: b9810030 0...
+K2HK EVM # rio r 0 -1 1 0x4
+00000004: 00000000 ....
+K2HK EVM # rio r 0 -1 1 0x8
+00000008: 00000030 0...
+K2HK EVM # rio lr 0
+00000000: b9810030 0...
+K2HK EVM # rio lr 8
+00000008: 00000030 0...
--
1.6.2.1
More information about the U-Boot
mailing list