             sw-load-elf (libloader.la :: loader_component_library)

Synopsis:

   This component loads ELF files from the host filesystem into simulated
   memory.

     ----------------------------------------------------------------------

Functionality:

  Modelling:

   This component helps to simulate a process environment by impersonating an
   OS loader.

   +-------------------------------------------------+
   |                    Behaviors                    |
   |-------------------------------------------------|
   | configuration | The "file" attribute stores the |
   |               | name of a file to attempt to    |
   |               | load. The "verbose?" attribute, |
   |               | when set, encourages this       |
   |               | component to provide            |
   |               | informative messages to cout    |
   |               | during loading.                 |
   |---------------+---------------------------------|
   |       loading | When the load! pin is driven,   |
   |               | this component will attempt to  |
   |               | load an ELF file from the host  |
   |               | filesystem. The loadable parts  |
   |               | of the file are sent one byte   |
   |               | at a time through an accessor.  |
   |               | During the process, the         |
   |               | starting PC and the program     |
   |               | endianness are signalled by     |
   |               | driving the values onto the     |
   |               | start-pc-set and endian-set     |
   |               | output pins. The endianness     |
   |               | value is 0/1/2 for              |
   |               | unknown/big/little.             |
   |               |                                 |
   |               | If the file cannot be found or  |
   |               | if it has other errors, a       |
   |               | message is sent to cerr and the |
   |               | loading process is stopped. The |
   |               | error output pin is driven in   |
   |               | this case.                      |
   |               |                                 |
   |               | Like operating system loaders,  |
   |               | sw-load-elf uses the ELF        |
   |               | "program header" to identify    |
   |               | the bytes to load into memory.  |
   |               | It does not use the "section    |
   |               | header". This means that it     |
   |               | tends to load more bytes than   |
   |               | gdb would.                      |
   +-------------------------------------------------+

   +-------------------------------------------------+
   |                 SID Conventions                 |
   |-------------------------------------------------|
   |          functional | supported         | -     |
   |---------------------+-------------------+-------|
   |        save/restore | supported         | -     |
   |---------------------+-------------------+-------|
   |       triggerpoints | not supported     | -     |
   |---------------------+-------------------+-------|
   |     limit-recursion | not supported     | -     |
   |---------------------+-------------------+-------|
   |            settings | supported         | -     |
   +-------------------------------------------------+

     ----------------------------------------------------------------------

Environment:

   Related components

   This component can be used as an initialization sequencer in a scenario
   with ordering dependencies. See this configuration fragment:

         new hw-glue-sequence-8 reset-manager
         new CPU-OF-SOME-TYPE cpu
         new sw-load-elf loader
         new mapper bus
         connect-pin reset-manager input <- main starting
         connect-pin reset-manager output-1 -> loader load!
         connect-bus loader load-accessor-insn bus access-port
         connect-bus loader load-accessor-data bus access-port
         set cpu-loader file "/foo/bar.x"
         set loader verbose? 1
         connect-pin loader start-pc-set -> cpu start-pc-set!
         connect-pin loader endian-set -> cpu endian-set!
         connect-pin loader error -> main stop!

     ----------------------------------------------------------------------

Component Reference:

  Component: sw-load-elf

   +-------------------------------------------------+
   |                      pins                       |
   |-------------------------------------------------|
   |     name     |direction |legalvalues |behaviors |
   |--------------+----------+------------+----------|
   |load!         |in        |any         |loading   |
   |--------------+----------+------------+----------|
   |start-pc-set  |out       |any         |loading   |
   |--------------+----------+------------+----------|
   |endian-set    |out       |0/1/2       |loading   |
   |--------------+----------+------------+----------|
   |error         |out       |any         |loading   |
   +-------------------------------------------------+

   +---------------------------------------------------------+
   |                       attributes                        |
   |---------------------------------------------------------|
   |     name     |category|legal |  default  |  behaviors  ||
   |              |        |values|   value   |             ||
   |--------------+--------+------+-----------+-------------||
   |state-snapshot|-       |opaque|-          |save/restore ||
   |              |        |string|           |             ||
   |--------------+--------+------+-----------+-------------||
   |file          |setting |file  |"/dev/null"|configuration||
   |              |        |name  |           |             ||
   |--------------+--------+------+-----------+-------------||
   |verbose?      |setting |1/0   |0          |configuration||
   +---------------------------------------------------------+

   +-------------------------------------------------+
   |                    accessors                    |
   |-------------------------------------------------|
   |        name        |    accesses    | behaviors |
   |--------------------+----------------+-----------|
   | load-accessor-insn | write          | loading   |
   |                    | little_int_1   |           |
   |--------------------+----------------+-----------|
   | load-accessor-data | write          | loading   |
   |                    | little_int_1   |           |
   +-------------------------------------------------+
