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

[Roland Hieber <rhi@pengutronix.de>]

Hmm. It still applies here cleanly on next. Do you want it on master
instead? I don't mind having it in next, and if you applied this series
on master instead, the conflicts with next will probably be the other
way around for the next release.

 - Roland

On Thu, Dec 13, 2018 at 07:57:58AM +0100, Sascha Hauer wrote:
> 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 |
> 

-- 
Roland Hieber                     | r.hieber@pengutronix.de     |
Pengutronix e.K.                  | https://www.pengutronix.de/ |
Peiner Str. 6-8, 31137 Hildesheim | Phone: +49-5121-206917-5086 |
Amtsgericht Hildesheim, HRA 2686  | Fax:   +49-5121-206917-5555 |

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