[PATCH] doc: add a section on flashing images

[PATCH] doc: add a section on flashing images

[Henning Schild]

Signed-off-by: Henning Schild <henning.schild@siemens.com>
---
 doc/user_manual.md | 8 ++++++++
 1 file changed, 8 insertions(+)

diff --git a/doc/user_manual.md b/doc/user_manual.md
index 70cf20a74828..e1d7166911e2 100644
--- a/doc/user_manual.md
+++ b/doc/user_manual.md
@@ -232,6 +232,14 @@ qemu-system-x86_64 -m 256M -nographic -bios edk2/Build/OvmfX64/RELEASE_*/FV/OVMF
 qemu-system-i386 -m 256M -nographic -hda tmp/deploy/images/qemui386/isar-image-base-debian-buster-qemui386.wic.img
 ```
 
+#### Flashing such images to a physical device
+
+wic images can be flashed in multiple ways. The most generic and easy way is probably with [ etcher ](https://etcher.io). That works on many operating systems and is relatively easy to use. On top it can decompress images on the fly, should they be compressed. It also offers some sort of protection so you do not write to the wrong device and maybe break your machine.
+
+If you have a unix shell there are other ways. Make sure to always double check the target device, those tools will not warn if you choose the wrong target.
+
+`dd` is the most generic option, available pretty much everywhere. For large images that contain a lot of empty space `dd` might be a little slow because it writes all that empty space. In that case `bmaptool` can be used instead.
+
 ### Generate container image with root filesystem
 
 A runnable container image is generated if you set IMAGE_TYPE to 
-- 
2.26.3

Re: [PATCH] doc: add a section on flashing images

[Jan Kiszka]

On 08.04.21 11:19, Henning Schild wrote:
> Signed-off-by: Henning Schild <henning.schild@siemens.com>
> ---
>  doc/user_manual.md | 8 ++++++++
>  1 file changed, 8 insertions(+)
> 
> diff --git a/doc/user_manual.md b/doc/user_manual.md
> index 70cf20a74828..e1d7166911e2 100644
> --- a/doc/user_manual.md
> +++ b/doc/user_manual.md
> @@ -232,6 +232,14 @@ qemu-system-x86_64 -m 256M -nographic -bios edk2/Build/OvmfX64/RELEASE_*/FV/OVMF
>  qemu-system-i386 -m 256M -nographic -hda tmp/deploy/images/qemui386/isar-image-base-debian-buster-qemui386.wic.img
>  ```
>  
> +#### Flashing such images to a physical device
> +
> +wic images can be flashed in multiple ways. The most generic and easy way is probably with [ etcher ](https://etcher.io). That works on many operating systems and is relatively easy to use. On top it can decompress images on the fly, should they be compressed. It also offers some sort of protection so you do not write to the wrong device and maybe break your machine.
> +
> +If you have a unix shell there are other ways. Make sure to always double check the target device, those tools will not warn if you choose the wrong target.
> +
> +`dd` is the most generic option, available pretty much everywhere. For large images that contain a lot of empty space `dd` might be a little slow because it writes all that empty space. In that case `bmaptool` can be used instead.

It's "bmap-tools" officially, a link to it would be good
(https://github.com/intel/bmap-tools). Some distros like Debian call the
package bmaptool. In general, would put it before mentioning dd, also
because "bmaptool copy" checks if the target device is mounted before
writing - which can be quite a mess if you didn't notice this. We
recommend it therefore in most of our end-user facing layers.

Jan

> +
>  ### Generate container image with root filesystem
>  
>  A runnable container image is generated if you set IMAGE_TYPE to 
> 

-- 
Siemens AG, T RDA IOT
Corporate Competence Center Embedded Linux

Re: [PATCH] doc: add a section on flashing images

[Henning Schild]

Am Mon, 12 Apr 2021 18:51:28 +0200
schrieb Jan Kiszka <jan.kiszka@siemens.com>:

> On 08.04.21 11:19, Henning Schild wrote:
> > Signed-off-by: Henning Schild <henning.schild@siemens.com>
> > ---
> >  doc/user_manual.md | 8 ++++++++
> >  1 file changed, 8 insertions(+)
> > 
> > diff --git a/doc/user_manual.md b/doc/user_manual.md
> > index 70cf20a74828..e1d7166911e2 100644
> > --- a/doc/user_manual.md
> > +++ b/doc/user_manual.md
> > @@ -232,6 +232,14 @@ qemu-system-x86_64 -m 256M -nographic -bios
> > edk2/Build/OvmfX64/RELEASE_*/FV/OVMF qemu-system-i386 -m 256M
> > -nographic -hda
> > tmp/deploy/images/qemui386/isar-image-base-debian-buster-qemui386.wic.img
> > ``` +#### Flashing such images to a physical device
> > +
> > +wic images can be flashed in multiple ways. The most generic and
> > easy way is probably with [ etcher ](https://etcher.io). That works
> > on many operating systems and is relatively easy to use. On top it
> > can decompress images on the fly, should they be compressed. It
> > also offers some sort of protection so you do not write to the
> > wrong device and maybe break your machine. + +If you have a unix
> > shell there are other ways. Make sure to always double check the
> > target device, those tools will not warn if you choose the wrong
> > target. + +`dd` is the most generic option, available pretty much
> > everywhere. For large images that contain a lot of empty space `dd`
> > might be a little slow because it writes all that empty space. In
> > that case `bmaptool` can be used instead.  
> 
> It's "bmap-tools" officially, a link to it would be good
> (https://github.com/intel/bmap-tools). Some distros like Debian call
> the package bmaptool. 

Still the tool itself will be called "bmaptool", this is not a
documentation on where the command may be coming from. It is like "dd"
probably not coming from a package called "d-d" or whatever ...

> In general, would put it before mentioning dd,
> also because "bmaptool copy" checks if the target device is mounted
> before writing - which can be quite a mess if you didn't notice this.
> We recommend it therefore in most of our end-user facing layers.

I could reorder them, but "bmaptool" has an availability issue, it is
simply not as readily available as "dd". That is why i ordered entries
like i did, still recommending "bmaptool" where available. Maybe that
mounting is another benefit of "bmaptool" over "dd".

I will change the order to say "bmaptool" where available, "dd" as
fallback. Reasons being speed and mount-check.

Henning



> Jan
> 
> > +
> >  ### Generate container image with root filesystem
> >  
> >  A runnable container image is generated if you set IMAGE_TYPE to 
> >   
>