
                                   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.

:<file_system label="<label>" writeable="no"/>:
  If <label> 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/<label>_.

:<nic label="<label>" tap_name="<tap_name>"/>:
  Required _Nic_ services are tied to a tap device on the host by adding a
  linux_nic and a nic_router to the runtime. The linux_nic is configured
  to use the tap device _<tap_name>_ (if provided, otherwise _tap0_) and
  connects to the uplink domain of the Nic router. The latter is configured as a
  DHCP client for its uplink interface 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. For every distinct tap
  device in use, only a single pair of linux_nic and nic_router will be
  instantiated.

  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.

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

:<rom label="mesa_gpu.lib.so"/>:
  The _mesa_gpu.lib.so_ _ROM_ requirement is routed to the
  _mesa_gpu-softpipe.lib_ ROM module.

:<rom label="clipboard"/>:
  The clipboard _ROM_ requirement is routed to a report_rom component.

:<report label="<label>"/>:
  If <label> equals "clipboard", a _Report_ requirement is routed to a report_rom
  component. For any other label, 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.


The _linux_ target evaluates the following services mentioned in
the _runtime_ file's <provides> node:

:<uplink label="<tap-name>"/>:
  For the first provided _Uplink_ service a linux_nic component is added to
  the runtime and configured to use the tap device <tap-name>.


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:

:<file_system label="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
