[v9,8/8] docs: Add a generic loader explanation document

Signed-off-by: Alistair Francis <alistair.francis@xilinx.com>
---
V9:
 - Clarify the image loading options
V8:
 - Improve documentation
V6:
 - Fixup documentation
V4:
 - Re-write to be more comprehensive

 docs/generic-loader.txt | 63 +++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 63 insertions(+)
 create mode 100644 docs/generic-loader.txt

On 14 July 2016 at 01:03, Alistair Francis <alistair.francis@xilinx.com> wrote:
> Signed-off-by: Alistair Francis <alistair.francis@xilinx.com>
> ---
> V9:
>  - Clarify the image loading options
> V8:
>  - Improve documentation
> V6:
>  - Fixup documentation
> V4:
>  - Re-write to be more comprehensive
>
>  docs/generic-loader.txt | 63 +++++++++++++++++++++++++++++++++++++++++++++++++
>  1 file changed, 63 insertions(+)
>  create mode 100644 docs/generic-loader.txt
>
> diff --git a/docs/generic-loader.txt b/docs/generic-loader.txt
> new file mode 100644
> index 0000000..16c11ee
> --- /dev/null
> +++ b/docs/generic-loader.txt
> @@ -0,0 +1,63 @@
> +Copyright (c) 2016 Xilinx Inc.
> +
> +This work is licensed under the terms of the GNU GPL, version 2 or later.  See
> +the COPYING file in the top-level directory.
> +
> +
> +The 'loader' device allows the user to load multiple images or values into
> +QEMU at startup.
> +
> +Loading Memory Values
> +---------------------
> +The loader device allows memory values to be set from the command line. This
> +can be done by following the syntax below:
> +
> +    -device loader,addr=<addr>,data=<data>,data-len=<len>
> +    -device loader,addr=<addr>,cpu-num=<cpu-num>
> +
> +    <addr>      - The address to store the data or the value to use as the
> +                  CPU's PC.
> +    <data>      - The value to be written to the address. The maximum size of
> +                  the data is 8 bytes.
> +    <data-len>  - The length of the data in bytes. This argument must be
> +                  included if the data argument is.
> +    <data-be>   - Set to true if the data to be stored on the guest should be
> +                  written as big endian data. The default is to write little
> +                  endian data.
> +    <cpu-num>   - This will cause the CPU to be reset and the PC to be set to
> +                  the value of addr.
> +
> +For all values both hex and decimal values are allowed. By default the values
> +will be parsed as decimal. To use hex values the user should prefix the number
> +with a '0x'.
> +
> +An example of loading value 0x8000000e to address 0xfd1a0104 is:
> +    -device loader,addr=0xfd1a0104,data=0x8000000e,data-len=4
> +
> +Loading Files
> +-------------
> +The loader device also allows files to be loaded into memory. This can be done
> +similarly to setting memory values. The syntax is shown below:
> +
> +    -device loader,file=<file>,addr=<addr>,cpu-num=<cpu-num>,force-raw=<raw>
> +
> +    <file>      - A file to be loaded into memory
> +    <addr>      - The addr in memory that the file should be loaded. This is
> +                  ignored if you are using an ELF (unless force-raw is true).
> +                  This is required if you aren't loading an ELF.
> +    <cpu-num>   - This specifies the CPU that should be used. This is an
> +                  optional argument and will cause the CPU's PC to be set to
> +                  where the image is stored or in the case of an ELF file to
> +                  the value in the header. This option should only be used
> +                  for the boot image.
> +                  This will also cause the image to be written to the specified
> +                  CPUs address space.
> +    <force-raw> - Forces the file to be treated as a raw image. This can be
> +                  used to specify the load address of ELF files.
> +
> +For all values both hex and decimal values are allowed. By default the values
> +will be parsed as decimal. To use hex values the user should prefix the number
> +with a '0x'.
> +
> +An example of loading an ELF file which CPU0 will boot is shown below:
> +    -device loader,file=./images/boot.elf,cpu-num=0

With this interface, you can specify a file to be loaded to CPU 2's
address space (via file=whatever,cpu-num=2) but you can't specify
a data value to be loaded to CPU 2's address space (because
addr=a,data=x,data-len=y,cpu-num=2 isn't valid). I think we could
usefully make that syntax do that.

This is probably most clearly documented by completely splitting
 -device loader,addr=<addr>,cpu-num=<cpu-num>
   (set the PC)

from
 -device loader,addr=<addr>,data=<data>,data-len=<data-len>[,data-be=<data-be>][,cpu-num=<cpu-num>]
   (load raw data values)

in the documentation in the same way that loader,file is split.

(I have a feeling we've been circling around on this option syntax
over the last few revisions so apologies if I've been inconsistent.)

You also can't specify a file to be loaded which doesn't set the
CPU PC, but I'm not sure how important that is. We can always add
it later with a no-set-pc option flag if we need it I guess.

thanks
-- PMM

On Fri, Jul 29, 2016 at 10:55 AM, Peter Maydell
<peter.maydell@linaro.org> wrote:
> On 14 July 2016 at 01:03, Alistair Francis <alistair.francis@xilinx.com> wrote:
>> Signed-off-by: Alistair Francis <alistair.francis@xilinx.com>
>> ---
>> V9:
>>  - Clarify the image loading options
>> V8:
>>  - Improve documentation
>> V6:
>>  - Fixup documentation
>> V4:
>>  - Re-write to be more comprehensive
>>
>>  docs/generic-loader.txt | 63 +++++++++++++++++++++++++++++++++++++++++++++++++
>>  1 file changed, 63 insertions(+)
>>  create mode 100644 docs/generic-loader.txt
>>
>> diff --git a/docs/generic-loader.txt b/docs/generic-loader.txt
>> new file mode 100644
>> index 0000000..16c11ee
>> --- /dev/null
>> +++ b/docs/generic-loader.txt
>> @@ -0,0 +1,63 @@
>> +Copyright (c) 2016 Xilinx Inc.
>> +
>> +This work is licensed under the terms of the GNU GPL, version 2 or later.  See
>> +the COPYING file in the top-level directory.
>> +
>> +
>> +The 'loader' device allows the user to load multiple images or values into
>> +QEMU at startup.
>> +
>> +Loading Memory Values
>> +---------------------
>> +The loader device allows memory values to be set from the command line. This
>> +can be done by following the syntax below:
>> +
>> +    -device loader,addr=<addr>,data=<data>,data-len=<len>
>> +    -device loader,addr=<addr>,cpu-num=<cpu-num>
>> +
>> +    <addr>      - The address to store the data or the value to use as the
>> +                  CPU's PC.
>> +    <data>      - The value to be written to the address. The maximum size of
>> +                  the data is 8 bytes.
>> +    <data-len>  - The length of the data in bytes. This argument must be
>> +                  included if the data argument is.
>> +    <data-be>   - Set to true if the data to be stored on the guest should be
>> +                  written as big endian data. The default is to write little
>> +                  endian data.
>> +    <cpu-num>   - This will cause the CPU to be reset and the PC to be set to
>> +                  the value of addr.
>> +
>> +For all values both hex and decimal values are allowed. By default the values
>> +will be parsed as decimal. To use hex values the user should prefix the number
>> +with a '0x'.
>> +
>> +An example of loading value 0x8000000e to address 0xfd1a0104 is:
>> +    -device loader,addr=0xfd1a0104,data=0x8000000e,data-len=4
>> +
>> +Loading Files
>> +-------------
>> +The loader device also allows files to be loaded into memory. This can be done
>> +similarly to setting memory values. The syntax is shown below:
>> +
>> +    -device loader,file=<file>,addr=<addr>,cpu-num=<cpu-num>,force-raw=<raw>
>> +
>> +    <file>      - A file to be loaded into memory
>> +    <addr>      - The addr in memory that the file should be loaded. This is
>> +                  ignored if you are using an ELF (unless force-raw is true).
>> +                  This is required if you aren't loading an ELF.
>> +    <cpu-num>   - This specifies the CPU that should be used. This is an
>> +                  optional argument and will cause the CPU's PC to be set to
>> +                  where the image is stored or in the case of an ELF file to
>> +                  the value in the header. This option should only be used
>> +                  for the boot image.
>> +                  This will also cause the image to be written to the specified
>> +                  CPUs address space.
>> +    <force-raw> - Forces the file to be treated as a raw image. This can be
>> +                  used to specify the load address of ELF files.
>> +
>> +For all values both hex and decimal values are allowed. By default the values
>> +will be parsed as decimal. To use hex values the user should prefix the number
>> +with a '0x'.
>> +
>> +An example of loading an ELF file which CPU0 will boot is shown below:
>> +    -device loader,file=./images/boot.elf,cpu-num=0
>
> With this interface, you can specify a file to be loaded to CPU 2's
> address space (via file=whatever,cpu-num=2) but you can't specify
> a data value to be loaded to CPU 2's address space (because
> addr=a,data=x,data-len=y,cpu-num=2 isn't valid). I think we could
> usefully make that syntax do that.
>
> This is probably most clearly documented by completely splitting
>  -device loader,addr=<addr>,cpu-num=<cpu-num>
>    (set the PC)
>
> from
>  -device loader,addr=<addr>,data=<data>,data-len=<data-len>[,data-be=<data-be>][,cpu-num=<cpu-num>]
>    (load raw data values)
>
> in the documentation in the same way that loader,file is split.

Ok, I have split these two up. There is now a new variable in the
device loader that keeps track of if the PC should be set or not.

At the moment it is not exposed at all to the user, but in the future
we can make it user forceable.

>
> (I have a feeling we've been circling around on this option syntax
> over the last few revisions so apologies if I've been inconsistent.)

I think we have, but it's ok. I just want this in.

>
> You also can't specify a file to be loaded which doesn't set the
> CPU PC, but I'm not sure how important that is. We can always add
> it later with a no-set-pc option flag if we need it I guess.

Agreed!

Thanks,

Alistair

>
> thanks
> -- PMM
>