             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.        |
   |                |                                |
   |                | When the configure! is set,    |
   |                | the new value is interpreted   |
   |                | as a configuration spec. The   |
   |                | spec is a colon-separated list |
   |                | of items, each of which is     |
   |                | passed in turn to the          |
   |                | 'configure' method for         |
   |                | interpretation and possible    |
   |                | action.                        |
   |----------------+--------------------------------|
   |        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.                     |
   |----------------+--------------------------------|
   | error checking | All read requests coming in    |
   |                | though the "probe-upstream"    |
   |                | bus are checked against known  |
   |                | code segments and, for each    |
   |                | attempt to write to a code     |
   |                | segment, the                   |
   |                | write-to-code-address pin is   |
   |                | driven with the address of the |
   |                | write attempt. All reads and   |
   |                | writes coming in through the   |
   |                | probe-upstream bus are passed  |
   |                | on to the probe-downstream     |
   |                | accessor. In addition,         |
   |                | addresses driven on the        |
   |                | "probe" pin are checked in the |
   |                | same way.                      |
   +-------------------------------------------------+

   +-------------------------------------------------+
   |                 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   |
   |-----------------------+-----------+-------------+---------------|
   |function-address?      |in         |address      |configuration  |
   |-----------------------+-----------+-------------+---------------|
   |load!                  |in         |any          |loading        |
   |-----------------------+-----------+-------------+---------------|
   |start-pc-set           |out        |any          |loading        |
   |-----------------------+-----------+-------------+---------------|
   |endian-set             |out        |0/1/2        |loading        |
   |-----------------------+-----------+-------------+---------------|
   |error                  |out        |any          |loading        |
   |-----------------------+-----------+-------------+---------------|
   |write-to-code-address  |out        |any address  |error checking |
   |-----------------------+-----------+-------------+---------------|
   |probe                  |in         |any address  |error checking |
   +-----------------------------------------------------------------+

   +-----------------------------------------------------+
   |                        buses                        |
   |-----------------------------------------------------|
   |      name      | addresses |  accesses  | behaviors |
   |----------------+-----------+------------+-----------|
   |probe-upstream  |-          |read/write  |error      |
   |                |           |            |checking   |
   +-----------------------------------------------------+

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

   +-------------------------------------------------+
   |                    accessors                    |
   |-------------------------------------------------|
   |        name        |   accesses    | behaviors  |
   |--------------------+---------------+------------|
   | load-accessor-insn | write         | loading    |
   |                    | little_int_1  |            |
   |--------------------+---------------+------------|
   | load-accessor-data | write         | loading    |
   |                    | little_int_1  |            |
   |--------------------+---------------+------------|
   | probe-downstream   | read/write    | error      |
   |                    |               | checking   |
   +-------------------------------------------------+
