From: Aurelien Jacquiot a-jacquiot@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@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...