corrected extension

README.md

+# Ezynq 
+Ezynq project is started to create a bootloader for systems based on the Xilinx Zynq SoC without
+the inconvenience of the non-free tools and/or files.
+The goal is not just to "free" the code, but to provide users with the higher degree of flexibi-
+lity in fine-tuning of the configuration parameters.
+
+Initial release includes configuration for the MicroZed board we used for this software develop-
+ment, we plan to add support for more boards, including Elphel NC393 camera - the reason we
+started this project.
+
+Ezynq partially duplicates functionality of Xilinx proprietary tools - bootgen and fsbl (first
+stage boot loader). It does not support secure boot functionality (that we have no interest in)
+and loading the FPGA (PL) part with the bitstream - we plan to do that under control of the
+operating system as we did in our earlier products, if needed this feature can be implemented
+using U-boot.
+
+This software consists of Python program that processes data from U-boot configuration files
+(configuration parameters start with CONFIG_EZYNQ_ prefix) that are collected in
+include/autoconf.mk (it is generated by "make include/autoconf.mk") and generates several output
+files:
+
+1. the header file (default name boot_head.bin) formatted for the Zynq ROM Boot Loader (RBL)
+according to section 6.3.2 of Xilinx UG585 -"Zynq-7000 AP SoC Technical Reference Manual". This
+file uses RBL register initialization feature to set registers (MIO, DDR) that can be written
+before system clocks and DDR memory are initialized - that requires polling status information
+and waiting for particular states are reached.
+
+2. *ezynq.c* file to be compiled and linked with other U-boot files. All ezynq-specific code is
+called by a modified version of the arch_cpu_init() function - the only difference from the
+U-boot version for Xilinx Zynq designed to be used with the proprietary FSBL program. This code
+finishes register initialization (contrary to RBL it can wait for certain states are reached)
+and performs relocation of the code from the on-chip memory (OCM) to the main system memory,
+U-boot takes over from there. Optionally the debug code is generated that controls the LED state
+at different stages of the boot process and outputs register states to the serial port.
+
+3. html output file (default name u-boot.html) that lists the configuration parameters used
+(specified and calculated from others), used PLLs and clocks, configured interfaces and their
+usage of the MIO pins. It then lists all the registers written by RBL and written/tested during
+execution of the arch_cpu_init(). Most of the registers are listed in the same sequence as they
+are set in hardware, the very last ones show registers that may be set/tested multiple times (as
+related to UART debug data output). The software keeps track of the register data writes and
+uses the default values provided in UG585, so when only some bit fields of the whole register
+need to be modified, software relies on the calculated previous value and does not perform read
+operations on the actual registers before writing the modified data back.
+
+The U-boot version designed to be used with FSBL relied on it to initialize registers, clocks
+and DRAM memory, load U-boot image to DRAM at address 0x4000000 and pass control there. FSBL
+itself was loaded by RBL into on-chip memory (OCM) at address 0, having 192K of the total 256K
+mapped to 0x0..0x2ffff and the remaining 64K - to the upper 0xffff0000..0xffffffff, the same
+mapping is passed to U-boot that uses the high OCM memory for stack initially and later remaps
+all of the OCM to 0xfffc0000.0xffffffff. Starting from 0x4000000 U-boot relocates itself to
+address zero and runs there.
+
+When using Ezynq the size of the U-boot image is limited to 192K - it is all what Zynq RBL can
+load by itself. It is quite a lot (192K is just for code, data uses DRAM and is not limited by
+the OCM) so U-boot can be loaded in a simple one-stage process without the need of the SPL when
+first a mini-version of U-boot is loaded, and that version later loads the full U-boot to DRAM.
+
+Generated *arch_cpu_init()* starts running in OCM, initializes DRAM, copies itself (first 192K
+OCM) to DRAM to 0x4000000.0x402ffff (using just C, not assembly code) and than adds 0x4000000 to
+the program counter. In this state it is possible to map DRAM to the 0x0.0x2ffff instead of the
+OCM and copy 0x4000000.0x402ffff back to 0x0.0x2ffff and so return from the function
+arch_cpu_init() gets the execution to the same low address where it started, but now it is in
+the DRAM, not in the OCM. U-boot relocation functionality nicely skips actual relocation (as
+the source and destination addresses are the same) and the data memory is initialized when 192K
+OCM limit is not in effect anymore. 
+
+
+## INSTALLATION (see below for testing without U-boot installation)
+
+When Ezynq repository is cloned, there is install_uboot.sh script in the top directory. Running
+this script clones u-boot-xlnx and then adds links to the files in Ezynq sub-directory
+u-boot-tree from the corresponding directories of the u-boot-xlnx, that allows to update Ezynq
+project files by "git pull".
+
+These links created by install_uboot.sh add new configuration files and replace 3 files in the
+  u-boot-xlnx:
+
+* boards.cfg - adding zynq-microzed there
+* arch/arm/cpu/armv7/zynq/cpu.c - disabling arch_cpu_init() there if configuration was made for
+  Ezynq
+* arch/arm/cpu/armv7/zynq/Makefile - to add autogenerated (not in the repository)
+  arch/arm/cpu/armv7/zynq/ezynq.c
+
+New files include:
+
+* *include/configs/zynq_microzed.h* configuration parameters for U-boot features, described in
+  U-boot README file
+* *include/configs/ezynq/ezynq_MT41K256M16RE125.h* - Ezynq configuration parameters containing
+  Micron DDR3 memory datasheet for the memory used by MicroZed board
+* *include/configs/ezynq/ezynq_XC7Z010_1CLG400.h* - Ezynq configuration parameters containing
+  Xilinx Zynq datasheet data for the SoC used by MicroZed board
+* *include/configs/ezynq/ezynq_XC7Z010_1CLG400.h* - Ezynq configuration parameters containing
+  Xilinx Zynq datasheet data for the SoC used by MicroZed board
+* include/configs/ezynq/zed_ezynq.h - rest of the Ezynq configuration parameters (it has the
+  include lines for the 2 datasheet files listed above)
+* *makeuboot* - script that configures U-boot for the microzed board, creates include/autoconf.mk,
+  runs ezynqcfg.py to create Ezynq code (RBL header and ezynq.c), builds and links U-boot
+  generating u-boot.bin, reruns ezynqcfg.py to include the length of the u-boot.bin into
+  boot_head.bin and then combines boot_head.bin and u-boot.bin into boot.bin with a simple
+  'cat' command.
+ 
+## Testing without u-boot and cross-compiler toolchain
+ 
+ It is possible to try just the ezynqcfg.py script without building u-boot, no ARM toolchain
+ is required  
+ ./ezynqcfg.py -c test.mk --html test.html --html-mask 0x3ff --lowlevel ezynq.c
+ This command uses a demo test.mk that mimics include/autoconf.mk and generates test.html and
+ ezynq.c files  
+ 
+## Useful links
+* [Ezynq wiki page](http://wiki.elphel.com/index.php?title=Ezynq)
+* [meta-ezynq](https://sourceforge.net/p/elphel/meta-ezynq) - recipes for Yocto Poky
+
+## Known issues
+1. USB does not work yet.
+2. Ethernet is not tested (on the board we have it does not work with provided images, so we
+   suspect a hardware problem.
+3. Bitstream loading is not tested, current code does not enable level shifters - it may be
+   more appropriate to do just before loading of the bitstream.
\ No newline at end of file