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

[Henning Schild <henning.schild@siemens.com>]

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 
> >   
>