README-SDCard-write

This folder contains a collection of scripts to write images to (SD)cards. A
simple GUI was implemented to make selections easy. This GUI is based on
'dialog' [1] which should be part of common packages in most distros.


There are three type of scripts:

1. card-part: This type of scripts create partitions on the card as the
   bootloaders expect them. This type of scripts are necessary only for
   machines whose board support layer still builds images in 'old-school'
   way e.g rootfs as *.tar.bz2).
2. card-write: This type of scripts write complete images (bootloader/
   devicetrees/kernel/rootfs) onto card.
   Machine defaults can be overriden by setting variables 
   'Machine' / 'FindString' - see include/card-helpers.inc
   function StartCardWrite.
3. card-kernel-write: This family of scripts just overwrites kernel, devicetrees
   and kernel modules on cards with image installed.
   These scripts are very helpful for testing kernel/devicetree modifications
   or just for updating kernel on precious (precious=many settings applied /
   full of userdata) images.
   Machine defaults can be overriden by setting variables 
   'Machine' / 'KernelImageType' / 'FindString' - see include/card-helpers.inc
   function StartCardKernelWrite.

To reduce the GUI-dialogs displayed or avoid them completely all scripts can be
called with the following parameters
1. Card device path e.g '/dev/sdc'
2. Source file to be written (either rootfs or kernel link with abiversion)
3. su / sudo selection: Pass '1' for su or '2' for sudo


Script structure:

1. include/*helper.inc: These script snippets are included by other scripts and
   contain useful functions to be re-used by other scripts.
2. include/machine-*.inc: All machine specific definitions and function
   overrides are found in these files.
   The following variables should be set within them:
   * DEFAULT_MACHINE_FAMILY: This variable is used to find machine specific
     deploy-dir containing kernel/rootfs...
     o Example contents are: '*imx*' / 'raspberrypi*'. 
     o Defaults can be overriden by calling scripts with:
       Machine=<override> <script>
   * DEFAULT_FIND_ROOTFS: This string is passed to the call of 'find' and
     reduces find result for file selection dialog on files containing rootfs
     only.
     o Example contents: '-name *.rpi-sdimg -type l' / 'raspberrypi*'.
     o Defaults can be overriden by calling card-write scripts with:
       FindString=<override> <script>
   * DEFAULT_KERNEL_IMAGE_TYPE: This variable is mandatory to be set for
     operating card-kernel script. The value depends on the kernel image format
     machine's board support package prefers.
     o Example contents: 'Image' / 'uImage' / 'zImage'.
     o Defaults can be overriden by overwriting value after including
       machine-*.inc - see ti-old-omap-card-kernel-write-overo.sh
3. <soc>-card-<operation>[-board].sh: These are the scripts to be executed.
   They typically just contain necessary includes and one call for desired
   operation: StartCardWrite / StartCardKernelWrite. Sligly tailored variants
   are found in ti-old-omap-card-part.sh / ti-old-omap-card-kernel-write-overo.sh


Howto create scripts for other socs/machines:

1. Read above
2. Create a machine/soc header include/machine-<your-machine>.inc containing
   variables for defaults and function overrides.
3. Create <soc>-card-<operation>[-board].sh scripts which include necessary
   scripts and call either StartCardWrite or StartCardKernelWrite