
                                   Targets


                              Johannes Schlatow

Goa supports different targets for executing a system scenario. A target is
selected by setting the config _target_ variable or by providing the *--target*
argument on the command line. By default, Goa uses the _linux_ target for
*goa run*.

AVAILABLE TARGETS
#################

linux
=====

This target uses base-linux to execute the project on top of the running Linux
kernel. The _linux_ target evaluates the following services mentioned in
the _runtime_ file's _requires_ node:

:event:
  Any required _Event_ service is routed to a nitpicker component.

:capture:
  Any required _Capture_ service is routed to a nitpicker component.

:gui:
  Any required _Gui_ service is routed to a nitpicker component.

:timer:
  Any required _Timer_ service is routed to a timer component.

:rm:
  Any required _RM_ service is routed to core.

:trace:
  Any required _TRACE_ service is routed to core.

:rtc:
  Any required _Rtc_ service is routed to a linux_rtc component.

:fs <name> | writeable: no:
  If <name> equals "fonts", a _File_system" requirement is routed to a
  fonts_fs component.
  For any other required _File_system_ a separate lx_fs component is added to
  the runtime and configured to provide access to the host directory
  _var/projects/<project_name>/fs/<name>_.

:nic <name>:
  For every required _Nic_ service, a linux_slirp_nic and nic_router is
  added to the runtime. The Nic router acts as a DHCP client on its uplink
  interface, which is connected to linux_slirp_nic, and as a DHCP server for
  its default domain. Each Nic router will use a distinct subnet for its
  default domain, starting from 10.0.10.0/24 and ending at 10.0.255.0/24.

  A _nic_ node may contain an arbitrary number of _tcp-forward_ and
  _udp-forward_ nodes, which are added to the Nic router's uplink domain.
  Any additional _policy_ and _domain_ nodes are added to the Nic router's.
  config.

  The provided forwarding rules are also applied to linux_slirp_nic so that the
  corresponding port on the host system is forwarded to the uplink interface
  of the Nic router.

  If a _tap_name_ attribute is present for the _nic_ node, the _Nic_ service
  is tied to tap device on the host by using linux_nic (instead of
  linux_slirp_nic). The linux_nic is configured to use the tap device
  _<tap_name>_.

  For every distinct tap device in use, only a single pair of linux_nic and
  nic_router will be instantiated.

:gpu:
  Any required _Gpu_ service is routed to a black-hole component.

:rom mesa_gpu.lib.so:
  The _mesa_gpu.lib.so_ _ROM_ requirement is routed to the
  _mesa_gpu-softpipe.lib_ ROM module.

:rom clipboard:
  The clipboard _ROM_ requirement is routed to a report_rom component.

:report <name>:
  If <name> equals "clipboard", a _Report_ requirement is routed to a report_rom
  component. For any other name, the Report service is routed to a black-hole
  component.

:audio_in and audio_out:
  Any required _Audio_in_ and _Audio_out_ service is routed to a black-hole
  component. Note: These services are deprecated since 24.04 and will be removed
  in the future.

:play and record:
  Any required _Play_ and _Record_ service is routed to a black-hole
  component.

:usb:
  Any required _Usb_ service is routed to a black-hole component.

:uplink:
  Any required _Uplink_ service is routed to a black-hole component.


sculpt
======

This target uses a (remotely) running Sculpt OS to execute the project in a
particularly crafted subsystem. The target system is expected to run a
webdav-capable HTTP server and a Telnet server. The HTTP server allows Goa to
upload the run directory whereas Goa receives the log output via the Telnet
server. A blueprint for such a subsystem is provided by
jschlatow/pkg/goa_testbed.

The _sculpt_ target evaluates the following target-specific variables that you
may set in your goarc file or provide as command-line arguments
*--target-opt-<name>*:

:target_opt(sculpt-server):
  Specifies the hostname or IP address of the target system
  (Mandatory, no default value).

:target_opt(sculpt-port-http):
  Specifies the port of the HTTP server (Default: 80).

:target_opt(sculpt-port-telnet):
  Specifies the port of the Telnet server (Default: 23).

:target_opt(sculpt-port-gdb):
  Specifies the port of the Telnet server (Default: 9999).

:target_opt(sculpt-kernel):
  Sets the kernel used by the remote system (e.g. "nova"). By default, the
  remote system routes any ld.lib.so request to the Sculpt-provided library.
  For debugging purposes, you may want to replace this library with a local
  version. If the kernel is set, Goa makes the corresponding base-* archive
  (including debug symbols) available and re-labels the ld.lib.so routes to
  ld.lib.so.local so that these ROM requests can be routed to the uploaded
  ld.lib.so library instead.

:target_opt(sculpt-cmd):
  Specifies a command to be executed (e.g. starting a VNC client) before
  establishing the telnet connection. The command will be executed using the
  default shell with the environment variable _SERVER_ set to the value of
  _target_opt(sculpt-server)_.

The _sculpt_ target routes all runtime-required services to the parent except
for the following:

:fs fonts:
  This requirement is routed to a dedicates fonts_fs component.


ADDING A CUSTOM TARGET TO GOA
#############################

A custom run target is added by creating a file _share/goa/lib/run/<target>.tcl_.
The file must implement the following procedures:

:base_archives:
  Returns a list of those depot archives that are always needed.

:parent_services:
  Returns a list of services provided by the parent.

:bind_required_services:
  Gets an array of required services as argument. The array entries are named
  after the lower-case service type. Each entry is a node object representing
  the corresponding node from the _runtime_ file. The procedure is supposed to
  unset the array entries or remove individual list items to indicate to the
  caller that these requirements have been processed. Note that the procedure
  must use 'upvar' to access the array:

  ! proc bind_required_services { services_arr } {
  !  upvar 1 $services_arr services
  !  ...
  ! }

:bind_provided_services:
  Same as _bind_required_services_ but called with the services found in the
  _<provides>_ node of the _runtime_ file.

:run_genode:
  Is called after the run_dir has been prepared and the scenario is ready to be
  executed.

:cpu_route:
  Returns the route to the CPU service in HID syntax (typically "+ parent").

:log_route:
  Returns the route to the LOG service in HID syntax (typically "+ parent").

:pd_route:
  Returns the route to the PD service in HID syntax (typically "+ parent").

:rom_route:
  Returns the route to the ROM service in HID syntax (typically "+ parent").


SEE ALSO
########

add-depot-user, api, artifacts, build-systems, config, import, index, runtime, overview
