Harmonize place and reservations handling with environment file

[dwagenk]

I've struggeld a bit with the handling of labgrid places and reservations when using an environment configuration file. This is an attempt to find a consensus of what the handling should be so it can be adapted in the implementation and added to the documentation.

---

Suggestion 1:

Current situation:

• Several Issues show that the distinction between roles and places leads to confusion (-p/--place is silently ignored by acquire/release when -c env.yaml is also given #1868, Structuring multiple boards in environment config #1194). When getting started with labgrid I initially tried to group all related boards in a single yaml file before and have since observed multiple colleagues new to labgrid doing the same. The locking behaviour changed with remote/client: make acquire/release operate on all RemotePlaces in env #1748 which adds to the confusion.
• a full test suite run might need access to all targets in an environment file, but running only some of the tests or using labgrid-client commands it might be enough to lock only the main target
• Using labgrid-client might require an environment file for interacting with a device, e.g. to configure a DigitalOutputPowerDriver. IMO it's good practice to reuse the same environment file for both tests and developers using labgrid-client

With an environment file configured (LG_ENV variable or -c flag) labgrid-client lock and related actions operate on

• LG_PLACE=*|all -> all targets listed in the environment configuration (default behaviour since remote/client: make acquire/release operate on all RemotePlaces in env #1748)
• LG_PLACE= (emtpy or unset) -> target main (default behaviour prior to remote/client: make acquire/release operate on all RemotePlaces in env #1748)
• LG_PLACE=someplacename -> the target with matching RemotePlace
• LG_PLACE=+ -> the target with RemotePlace matching the device reservation from LG_TOKEN

For labgrid-client actions interacting with a single device (power, io) the LG_PLACE=*|all is treated the same as LG_PLACE= using the main target from the environment file. More complex usages are possible from python and inside tests by using a specific target from the environment configuration.

Since no release containing #1748 was made yet I would not consider this a breaking change.

---

Suggestion 2:

Current situation:

• External scripts need to assemble the place tags for a labgrid-client reserve call and can then be used in combination with an LG_PLACE=+ and an environment config like this:

  targets:
    main:
      resources:
        RemotePlace:
          name: !template $LG_PLACE

• Combining the correct set of reserve arguments and environment files (and possibly also test suites to run) is cumbersome

Integrate reservation handling with the environment configuration file. My goal is to replace the custom handling of the reservation with

export LG_ENV=/path/to/env.yaml
export LG_PLACE=+
source <(labgrid-client reserve --shell --wait)
labgrid-client lock
# run tests e.g. pytest --lg-env $LG_ENV tests
labgrid-client unlock

To archieve this I'd suggest allowing more versatile matching in RemotePlace by allowing a dictionary of place tags and values instead of only name. Following the example in https://labgrid.readthedocs.io/en/latest/usage.html#place-scheduling a environment configuration compatible with any place tagged board=imx6-foo would be:

targets:
  main:
    resources:
      RemotePlace:
        board: imx6-foo

and labgrid-client -c /path/to/env.yaml reserve without any key=value pairs (or explicitely with a flag?) would take the board=imx6-foo from the environment configuration.

For environment configuration files with multiple targets the LG_PLACE handling outlined in suggestion 1 would be taken into account, with

• LG_PLACE='*'|all -> one reservation per target in the environment file is created, --wait would wait until all of them are available
• LG_PLACE= (emtpy or unset) -> reservation for target main
• LG_PLACE=someplacename -> reservation for the target with matching RemotePlace (only works if at least one target sets RemotePlace: {name: someplacename}
• LG_PLACE=+ -> error or treated identical to empty LG_PLACE

---

If we agree that this would be an overall improvement I'd continue my work on a proof of concept for this