Re: [PATCH 1/3] Documentation: i.MX: improve wording, add markup and missing articles

[Sascha Hauer <s.hauer@pengutronix.de>]

Hi Roland,

This one doesn't apply. Could you rebase?

Sascha

On Mon, Dec 10, 2018 at 04:55:09PM +0100, Roland Hieber wrote:
> Signed-off-by: Roland Hieber <rhi@pengutronix.de>
> ---
>  Documentation/boards/imx.rst | 102 +++++++++++++++++++----------------
>  1 file changed, 57 insertions(+), 45 deletions(-)
> 
> diff --git a/Documentation/boards/imx.rst b/Documentation/boards/imx.rst
> index 35a180b0dd..2e6a30fd2f 100644
> --- a/Documentation/boards/imx.rst
> +++ b/Documentation/boards/imx.rst
> @@ -32,114 +32,126 @@ Normally it's not necessary to call this tool manually, it is executed
>  automatically at the end of the build process.
>  
>  The images generated by the build process can be directly written to an
>  SD card:
>  
>  .. code-block:: sh
>  
>    # with Multi Image support:
>    cat images/barebox-freescale-imx51-babbage.img > /dev/sdd
>    # otherwise:
>    cat barebox-flash-image > /dev/sdd
>  
>  The above will overwrite the MBR (and consequently the partition table)
>  on the destination SD card. To preserve the MBR while writing the rest
> -of the image to the card, use::
> +of the image to the card, use:
> +
> +.. code-block:: sh
>  
>    dd if=images/barebox-freescale-imx51-babbage.img of=/dev/sdd bs=1024 skip=1 seek=1
>  
> -NOTE: MaskROM on i.MX8 expects image to start at +33KiB mark, so the
> +Note that MaskROM on i.MX8 expects the image to start at the +33KiB mark, so the
>  following command has to be used instead:
>  
> +.. code-block:: sh
> +
>    dd if=images/barebox-nxp-imx8mq-evk.img of=/dev/sdd bs=1024 skip=33 seek=33
>  
>  Or, in case of NAND:
>  
> +.. code-block:: sh
> +
>    dd if=images/barebox-nxp-imx8mq-evk.img of=/dev/nand bs=1024 skip=33 seek=1
>  
> -The images can also always be started second stage::
> +The images can also always be started as second stage on the target:
> +
> +.. code-block:: console
>  
> -  bootm /mnt/tftp/barebox-freescale-imx51-babbage.img
> +  barebox@Board Name:/ bootm /mnt/tftp/barebox-freescale-imx51-babbage.img
>  
>  Using GPT on i.MX
>  ^^^^^^^^^^^^^^^^^
>  
> -For i.MX SoCs that place vendor specific header at +1KiB mark of a
> -boot medium, special care needs to be taken when parition that medium
> -with GPT. In order to make room for i.MX boot header GPT Partition
> +For i.MX SoCs that place a vendor specific header at the +1KiB mark of a
> +boot medium, special care needs to be taken when partitioning that medium
> +with GPT. In order to make room for the i.MX boot header, the GPT Partition
>  Entry Array needs to be moved from its typical location, LBA 2, to an
>  offset past vendor specific information. One way to do this would be
> -to use ``-j`` or ``--adjust-main-table`` option of ``sgdisk``. For
> -example, the following sequence:
> +to use the ``-j`` or ``--adjust-main-table`` option of ``sgdisk``. For
> +example, the following sequence
> +
> +.. code-block:: sh
>  
>    sgdisk -Z <block device>
>    sgdisk -o -j 2048 -n 1:8192:+100M <block device>
>  
>  will create a single GPT partition starting at LBA 8192 and would
> -place Partition Entry Array starting at LBA 2048 which should leave
> -enough room for Barebox/i.MX boot header. Once that is done ``dd``
> +place the Partition Entry Array starting at LBA 2048, which should leave
> +enough room for the Barebox/i.MX boot header. Once that is done, the ``dd``
>  command above can be used to place Barebox on the same medium.
>  
>  Information about the ``imx-image`` tool
>  ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
>  
>  The imx-image tool can be used to generate imximages from raw binaries.
>  It requires an configuration file describing how to setup the SDRAM on
>  a particular board. This mainly consists of a poke table. The recognized
>  options in this file are:
>  
>  Header:
>  
> -+----------------+--------------------------------------------------------------+
> -| soc <soctype>  |soctype can be one of imx35, imx51, imx53, imx6, imx7, vf610, |
> -|                |                             imx8mq                           |
> -+----------------+--------------------------------------------------------------+
> -| loadaddr <adr> |     The address the binary is uploaded to                    |
> -+----------------+--------------------------------------------------------------+
> -| dcdofs <ofs>   | The offset of the image header in the image. This should be: |
> -|                | * ``0x400``:  MMC/SD, NAND, serial ROM, PATA, SATA           |
> -|                | * ``0x1000``: NOR Flash                                      |
> -|                | * ``0x100``: OneNAND                                         |
> -+----------------+--------------------------------------------------------------+
> ++--------------------+--------------------------------------------------------------+
> +| ``soc <soctype>``  | soctype can be one of imx35, imx51, imx53, imx6, imx7, vf610,|
> +|                    |                             imx8mq                           |
> ++--------------------+--------------------------------------------------------------+
> +| ``loadaddr <adr>`` |     The address the binary is uploaded to                    |
> ++--------------------+--------------------------------------------------------------+
> +| ``dcdofs <ofs>``   | The offset of the image header in the image. This should be: |
> +|                    |                                                              |
> +|                    | * ``0x400``:  MMC/SD, NAND, serial ROM, PATA, SATA           |
> +|                    | * ``0x1000``: NOR Flash                                      |
> +|                    | * ``0x100``: OneNAND                                         |
> ++--------------------+--------------------------------------------------------------+
>  
>  Memory manipulation:
>  
> -+------------------------------------+-----------------------------------------+
> -| wm 8 <addr> <value>                | write <value> into byte <addr>          |
> -+------------------------------------+-----------------------------------------+
> -| wm 16 <addr> <value>               | write <value> into short <addr>         |
> -+------------------------------------+-----------------------------------------+
> -| wm 32 <addr> <value>               | write <value> into word <addr>          |
> -+------------------------------------+-----------------------------------------+
> -| set_bits <width> <addr> <value>    | set set bits in <value> in <addr>       |
> -+------------------------------------+-----------------------------------------+
> -| clear_bits <width> <addr> <value>  | clear set bits in <value> in <addr>     |
> -+------------------------------------+-----------------------------------------+
> -| nop                                | do nothing (just waste time)            |
> -+------------------------------------+-----------------------------------------+
> -
> -<width> can be of 8, 16 or 32.
> ++----------------------------------------+-------------------------------------------------+
> +| ``wm 8 <addr> <value>``                | write ``<value>`` into byte ``<addr>``          |
> ++----------------------------------------+-------------------------------------------------+
> +| ``wm 16 <addr> <value>``               | write ``<value>`` into short ``<addr>``         |
> ++----------------------------------------+-------------------------------------------------+
> +| ``wm 32 <addr> <value>``               | write ``<value>`` into word ``<addr>``          |
> ++----------------------------------------+-------------------------------------------------+
> +| ``set_bits <width> <addr> <value>``    | set set bits in ``<value>`` in ``<addr>``       |
> ++----------------------------------------+-------------------------------------------------+
> +| ``clear_bits <width> <addr> <value>``  | clear set bits in ``<value>`` in ``<addr>``     |
> ++----------------------------------------+-------------------------------------------------+
> +| ``nop``                                | do nothing (just waste time)                    |
> ++----------------------------------------+-------------------------------------------------+
> +
> +``<width>`` can be one of 8, 16 or 32.
>  
>  Checking conditions:
>  
> -+------------------------------------+-----------------------------------------+
> -| check <width> <cond> <addr> <mask> | Poll until condition becomes true.      |
> -|                                    | with <cond> being one of:               |
> -|                                    | * ``until_all_bits_clear``              |
> -|                                    | * ``until_all_bits_set``                |
> -|                                    | * ``until_any_bit_clear``               |
> -|                                    | * ``until_any_bit_set``                 |
> -+------------------------------------+-----------------------------------------+
> ++----------------------------------------+-----------------------------------------+
> +| ``check <width> <cond> <addr> <mask>`` | Poll until condition becomes true.      |
> +|                                        | with ``<cond>`` being one of:           |
> +|                                        |                                         |
> +|                                        | * ``until_all_bits_clear``              |
> +|                                        | * ``until_all_bits_set``                |
> +|                                        | * ``until_any_bit_clear``               |
> +|                                        | * ``until_any_bit_set``                 |
> ++----------------------------------------+-----------------------------------------+
>  
>  Some notes about the mentioned *conditions*.
>  
>   - ``until_all_bits_clear`` waits until ``(*addr & mask) == 0`` is true
>   - ``until_all_bits_set`` waits until ``(*addr & mask) == mask`` is true
>   - ``until_any_bit_clear`` waits until ``(*addr & mask) != mask`` is true
>   - ``until_any_bit_set`` waits until ``(*addr & mask) != 0`` is true.
>  
>  USB Boot
>  ^^^^^^^^
>  
>  Most boards can be explicitly configured for USB Boot Mode or fall back
>  to USB Boot when no other medium can be found. The barebox repository
>  contains a USB upload tool. As it depends on the libusb development headers,
> -- 
> 2.19.1
> 
> 
> _______________________________________________
> barebox mailing list
> barebox@lists.infradead.org
> http://lists.infradead.org/mailman/listinfo/barebox
> 

-- 
Pengutronix e.K.                           |                             |
Industrial Linux Solutions                 | http://www.pengutronix.de/  |
Peiner Str. 6-8, 31137 Hildesheim, Germany | Phone: +49-5121-206917-0    |
Amtsgericht Hildesheim, HRA 2686           | Fax:   +49-5121-206917-5555 |

_______________________________________________
barebox mailing list
barebox@lists.infradead.org
http://lists.infradead.org/mailman/listinfo/barebox