<p>pespin <strong>submitted</strong> this change.</p><p><a href="https://gerrit.osmocom.org/c/osmo-gsm-tester/+/18215">View Change</a></p><div style="white-space:pre-wrap">Approvals:
pespin: Looks good to me, approved
Jenkins Builder: Verified
</div><pre style="font-family: monospace,monospace; white-space: pre-wrap;">doc/manuals: Swap order of schemas and config files<br><br>First explain the different config files and directories, later describe<br>the schemas used in each of them.<br><br>Change-Id: Iaf31808a655a5c77a1dfaa155e86d42585130820<br>---<br>M doc/manuals/chapters/config.adoc<br>1 file changed, 211 insertions(+), 211 deletions(-)<br><br></pre><pre style="font-family: monospace,monospace; white-space: pre-wrap;"><span>diff --git a/doc/manuals/chapters/config.adoc b/doc/manuals/chapters/config.adoc</span><br><span>index c302cd6..fec5c87 100644</span><br><span>--- a/doc/manuals/chapters/config.adoc</span><br><span>+++ b/doc/manuals/chapters/config.adoc</span><br><span>@@ -1,216 +1,5 @@</span><br><span> == Configuration</span><br><span> </span><br><span style="color: hsl(0, 100%, 40%);">-=== Schemas</span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span style="color: hsl(0, 100%, 40%);">-All configuration attributes in {app-name} are stored and provided as YAML</span><br><span style="color: hsl(0, 100%, 40%);">-files, which are handled internally mostly as sets of dictionaries, lists and</span><br><span style="color: hsl(0, 100%, 40%);">-scalars. Each of these configurations have a known format (set of keys and</span><br><span style="color: hsl(0, 100%, 40%);">-values), which is called 'schema'. Each provided configuration is validated</span><br><span style="color: hsl(0, 100%, 40%);">-against its 'schema' at parse time. Hence, 'schemas' can be seen as a namespace</span><br><span style="color: hsl(0, 100%, 40%);">-containing a structured tree of configuration attributes. Each attribute has a</span><br><span style="color: hsl(0, 100%, 40%);">-schema type assigned which constrains the type of value it can hold.</span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span style="color: hsl(0, 100%, 40%);">-There are several well-known schemas used across {app-name}, and they are</span><br><span style="color: hsl(0, 100%, 40%);">-described in following sub-sections.</span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span style="color: hsl(0, 100%, 40%);">-[[schema_main_cfg]]</span><br><span style="color: hsl(0, 100%, 40%);">-==== Schema 'main config'</span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span style="color: hsl(0, 100%, 40%);">-This schema defines all the attributes available in {app-name} the main</span><br><span style="color: hsl(0, 100%, 40%);">-configuration file <<main_conf,main.conf>>, and it is used to validate it.</span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span style="color: hsl(0, 100%, 40%);">-[[schema_resources]]</span><br><span style="color: hsl(0, 100%, 40%);">-==== Schema 'resources'</span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span style="color: hsl(0, 100%, 40%);">-This schema defines all the attributes which can be assigned to</span><br><span style="color: hsl(0, 100%, 40%);">-a _resource_, and it is used to validate the <<resources_conf,resources.conf>></span><br><span style="color: hsl(0, 100%, 40%);">-file. Hence, the <<resources_conf,resources.conf>> contains a list of elements</span><br><span style="color: hsl(0, 100%, 40%);">-for each resource type. This schema is also used and extended by the</span><br><span style="color: hsl(0, 100%, 40%);">-<<schema_want,'want' schema>>.</span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span style="color: hsl(0, 100%, 40%);">-It is important to understand that the content in this schema refers to a list of</span><br><span style="color: hsl(0, 100%, 40%);">-resources for each resource class. Since a list is ordered by definition, it</span><br><span style="color: hsl(0, 100%, 40%);">-clearly identifies specific resources by order. This is important when applying</span><br><span style="color: hsl(0, 100%, 40%);">-filters or modifiers, since they are applied per-resource in the list. One can</span><br><span style="color: hsl(0, 100%, 40%);">-for instance apply attribute A to first resource of class C, while not applying</span><br><span style="color: hsl(0, 100%, 40%);">-it or applying another attribute B to second resources of the same class. As a</span><br><span style="color: hsl(0, 100%, 40%);">-result, complex forms can be used to filter and modify a list of resources</span><br><span style="color: hsl(0, 100%, 40%);">-required by a testsuite.</span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span style="color: hsl(0, 100%, 40%);">-On the other hand, it's also important to note that lists for simple or scalar</span><br><span style="color: hsl(0, 100%, 40%);">-types are currently being treated as unordered sets, which mean combination of</span><br><span style="color: hsl(0, 100%, 40%);">-filters or modifiers apply differently. In the future, it may be possible to</span><br><span style="color: hsl(0, 100%, 40%);">-have both behaviors for scalar/simple types by using also the YAML 'set' type in</span><br><span style="color: hsl(0, 100%, 40%);">-{app-name}.</span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span style="color: hsl(0, 100%, 40%);">-//TODO: update this list and use a table for each resource type in its own object section</span><br><span style="color: hsl(0, 100%, 40%);">-////</span><br><span style="color: hsl(0, 100%, 40%);">-These kinds of resources and their attributes are known:</span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span style="color: hsl(0, 100%, 40%);">-'ip_address'::</span><br><span style="color: hsl(0, 100%, 40%);">- List of IP addresses to run osmo-nitb instances on. The main unit</span><br><span style="color: hsl(0, 100%, 40%);">- typically has a limited number of such IP addresses configured, which</span><br><span style="color: hsl(0, 100%, 40%);">- the connected BTS models can see on their network.</span><br><span style="color: hsl(0, 100%, 40%);">- 'addr':::</span><br><span style="color: hsl(0, 100%, 40%);">- IPv4 address of the local interface.</span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span style="color: hsl(0, 100%, 40%);">-'bts'::</span><br><span style="color: hsl(0, 100%, 40%);">- List of available BTS hardware.</span><br><span style="color: hsl(0, 100%, 40%);">- 'label':::</span><br><span style="color: hsl(0, 100%, 40%);">- human readable label for your own reference</span><br><span style="color: hsl(0, 100%, 40%);">- 'type':::</span><br><span style="color: hsl(0, 100%, 40%);">- which way to launch this BTS, one of</span><br><span style="color: hsl(0, 100%, 40%);">- - 'osmo-bts-sysmo'</span><br><span style="color: hsl(0, 100%, 40%);">- - 'osmo-bts-trx'</span><br><span style="color: hsl(0, 100%, 40%);">- - 'osmo-bts-octphy'</span><br><span style="color: hsl(0, 100%, 40%);">- - 'ipa-nanobts'</span><br><span style="color: hsl(0, 100%, 40%);">- 'ipa_unit_id':::</span><br><span style="color: hsl(0, 100%, 40%);">- ip.access unit id to be used by the BTS, written into BTS and BSC config.</span><br><span style="color: hsl(0, 100%, 40%);">- 'addr':::</span><br><span style="color: hsl(0, 100%, 40%);">- Remote IP address of the BTS for BTS like sysmoBTS, and local IP address</span><br><span style="color: hsl(0, 100%, 40%);">- to bind to for locally run BTS such as osmo-bts-trx.</span><br><span style="color: hsl(0, 100%, 40%);">- 'band':::</span><br><span style="color: hsl(0, 100%, 40%);">- GSM band that this BTS shoud use (*TODO*: allow multiple bands). One of:</span><br><span style="color: hsl(0, 100%, 40%);">- - 'GSM-1800'</span><br><span style="color: hsl(0, 100%, 40%);">- - 'GSM-1900'</span><br><span style="color: hsl(0, 100%, 40%);">- - (*TODO*: more bands)</span><br><span style="color: hsl(0, 100%, 40%);">- 'trx_list':::</span><br><span style="color: hsl(0, 100%, 40%);">- Specific TRX configurations for this BTS. There should be as many of</span><br><span style="color: hsl(0, 100%, 40%);">- these as the BTS has TRXes. (*TODO*: a way to define >1 TRX without</span><br><span style="color: hsl(0, 100%, 40%);">- special configuration for them.)</span><br><span style="color: hsl(0, 100%, 40%);">- 'hw_addr'::::</span><br><span style="color: hsl(0, 100%, 40%);">- Hardware (MAC) address of the TRX in the form of '11:22:33:44:55:66',</span><br><span style="color: hsl(0, 100%, 40%);">- only used for osmo-bts-octphy. (*TODO*: and nanobts??)</span><br><span style="color: hsl(0, 100%, 40%);">- 'net_device'::::</span><br><span style="color: hsl(0, 100%, 40%);">- Local network device to reach the TRX's 'hw_addr' at, only used for</span><br><span style="color: hsl(0, 100%, 40%);">- osmo-bts-octphy. Example: 'eth0'.</span><br><span style="color: hsl(0, 100%, 40%);">- 'nominal_power'::::</span><br><span style="color: hsl(0, 100%, 40%);">- Nominal power to be used by the TRX.</span><br><span style="color: hsl(0, 100%, 40%);">- 'max_power_red'::::</span><br><span style="color: hsl(0, 100%, 40%);">- Max power reduction to apply to the nominal power of the TRX.</span><br><span style="color: hsl(0, 100%, 40%);">-'arfcn'::</span><br><span style="color: hsl(0, 100%, 40%);">- List of ARFCNs to use for running BTSes, which defines the actual RF</span><br><span style="color: hsl(0, 100%, 40%);">- frequency bands used.</span><br><span style="color: hsl(0, 100%, 40%);">- 'arfcn':::</span><br><span style="color: hsl(0, 100%, 40%);">- ARFCN number, see e.g.</span><br><span style="color: hsl(0, 100%, 40%);">- https://en.wikipedia.org/wiki/Absolute_radio-frequency_channel_number</span><br><span style="color: hsl(0, 100%, 40%);">- (note that the resource type 'arfcn' contains an item trait also named</span><br><span style="color: hsl(0, 100%, 40%);">- 'arfcn').</span><br><span style="color: hsl(0, 100%, 40%);">- 'band':::</span><br><span style="color: hsl(0, 100%, 40%);">- GSM band name to use this ARFCN for, same as for 'bts:band' above.</span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span style="color: hsl(0, 100%, 40%);">-'modem'::</span><br><span style="color: hsl(0, 100%, 40%);">- List of modems reachable via ofono and information on the inserted SIM</span><br><span style="color: hsl(0, 100%, 40%);">- card. (Note: the MSISDN is allocated dynamically in test scripts).</span><br><span style="color: hsl(0, 100%, 40%);">- 'label':::</span><br><span style="color: hsl(0, 100%, 40%);">- Human readable label for your own reference, which also appears in logs.</span><br><span style="color: hsl(0, 100%, 40%);">- 'path':::</span><br><span style="color: hsl(0, 100%, 40%);">- Ofono's path for this modem, like '/modemkind_99'.</span><br><span style="color: hsl(0, 100%, 40%);">- 'imsi':::</span><br><span style="color: hsl(0, 100%, 40%);">- IMSI of the inserted SIM card, like '"123456789012345"'.</span><br><span style="color: hsl(0, 100%, 40%);">- 'ki':::</span><br><span style="color: hsl(0, 100%, 40%);">- 16 byte authentication/encryption KI of the inserted SIM card, in</span><br><span style="color: hsl(0, 100%, 40%);">- hexadecimal notation (32 characters) like +</span><br><span style="color: hsl(0, 100%, 40%);">- '"00112233445566778899aabbccddeeff"'.</span><br><span style="color: hsl(0, 100%, 40%);">- 'auth_algo':::</span><br><span style="color: hsl(0, 100%, 40%);">- Authentication algorithm to be used with the SIM card. One of:</span><br><span style="color: hsl(0, 100%, 40%);">- - 'none'</span><br><span style="color: hsl(0, 100%, 40%);">- - 'xor'</span><br><span style="color: hsl(0, 100%, 40%);">- - 'comp128v1'</span><br><span style="color: hsl(0, 100%, 40%);">- 'ciphers':::</span><br><span style="color: hsl(0, 100%, 40%);">- List of ciphers that this modem supports, used to match</span><br><span style="color: hsl(0, 100%, 40%);">- requirements in suites or scenarios. Any combination of:</span><br><span style="color: hsl(0, 100%, 40%);">- - 'a5_0'</span><br><span style="color: hsl(0, 100%, 40%);">- - 'a5_1'</span><br><span style="color: hsl(0, 100%, 40%);">- - 'a5_2'</span><br><span style="color: hsl(0, 100%, 40%);">- - 'a5_3'</span><br><span style="color: hsl(0, 100%, 40%);">- - 'a5_4'</span><br><span style="color: hsl(0, 100%, 40%);">- - 'a5_5'</span><br><span style="color: hsl(0, 100%, 40%);">- - 'a5_6'</span><br><span style="color: hsl(0, 100%, 40%);">- - 'a5_7'</span><br><span style="color: hsl(0, 100%, 40%);">- 'features':::</span><br><span style="color: hsl(0, 100%, 40%);">- List of features that this modem supports, used to match requirements in</span><br><span style="color: hsl(0, 100%, 40%);">- suites or scenarios. Any combination of:</span><br><span style="color: hsl(0, 100%, 40%);">- - 'sms'</span><br><span style="color: hsl(0, 100%, 40%);">- - 'gprs'</span><br><span style="color: hsl(0, 100%, 40%);">- - 'voice'</span><br><span style="color: hsl(0, 100%, 40%);">- - 'ussd'</span><br><span style="color: hsl(0, 100%, 40%);">-////</span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span style="color: hsl(0, 100%, 40%);">-[[schema_want]]</span><br><span style="color: hsl(0, 100%, 40%);">-==== Schema 'want'</span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span style="color: hsl(0, 100%, 40%);">-This schema is basically the same as the <<schema_resources,resources>> one, but</span><br><span style="color: hsl(0, 100%, 40%);">-with an extra 'times' attribute for each resource item. All 'times' attributes</span><br><span style="color: hsl(0, 100%, 40%);">-are expanded before matching. For example, if a 'suite.conf' requests two BTS,</span><br><span style="color: hsl(0, 100%, 40%);">-one may enforce that both BTS should be of type 'osmo-bts-sysmo' in these ways:</span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span>-----</span><br><span style="color: hsl(0, 100%, 40%);">-resources:</span><br><span style="color: hsl(0, 100%, 40%);">- bts:</span><br><span style="color: hsl(0, 100%, 40%);">- - type: osmo-bts-sysmo</span><br><span style="color: hsl(0, 100%, 40%);">- - type: osmo-bts-sysmo</span><br><span>-----</span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span style="color: hsl(0, 100%, 40%);">-or alternatively,</span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span>-----</span><br><span style="color: hsl(0, 100%, 40%);">-resources:</span><br><span style="color: hsl(0, 100%, 40%);">- bts:</span><br><span style="color: hsl(0, 100%, 40%);">- - times: 2</span><br><span style="color: hsl(0, 100%, 40%);">- type: osmo-bts-sysmo</span><br><span>-----</span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span style="color: hsl(0, 100%, 40%);">-[[schema_config]]</span><br><span style="color: hsl(0, 100%, 40%);">-==== Schema 'config'</span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span style="color: hsl(0, 100%, 40%);">-This schema defines all the attributes which can be used by object classes or</span><br><span style="color: hsl(0, 100%, 40%);">-tests during test execution. The main difference between this schema and the</span><br><span style="color: hsl(0, 100%, 40%);">-<<schema_resources,resources>> schema is that the former contains configuration</span><br><span style="color: hsl(0, 100%, 40%);">-to be applied globally for all objects being used, while the later applies</span><br><span style="color: hsl(0, 100%, 40%);">-attributes to a specific object in the list of allocated resources. This schema</span><br><span style="color: hsl(0, 100%, 40%);">-hence allows setting attributes for objects which are not allocated as resources</span><br><span style="color: hsl(0, 100%, 40%);">-and hence not directly accessible through scenarios, like a BSC or an iperf3</span><br><span style="color: hsl(0, 100%, 40%);">-client.</span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span style="color: hsl(0, 100%, 40%);">-This schema is built dynamically at runtime from content registered by:</span><br><span style="color: hsl(0, 100%, 40%);">-- object classes registering their own attributes</span><br><span style="color: hsl(0, 100%, 40%);">-- test suite registering their own attributes through <<suite_conf,suite.conf>></span><br><span style="color: hsl(0, 100%, 40%);">- and tests being able to later retrieve them through 'testenv' API.</span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span style="color: hsl(0, 100%, 40%);">-[[schema_all]]</span><br><span style="color: hsl(0, 100%, 40%);">-==== Schema 'all'</span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span style="color: hsl(0, 100%, 40%);">-This schema is basically an aggregated namespace for <<schema_want,want>> schema</span><br><span style="color: hsl(0, 100%, 40%);">-and <<schema_config,config>> schema, and is the one used by</span><br><span style="color: hsl(0, 100%, 40%);">-<<suite_conf,suite.conf>> and <<scenario_conf,scenario.conf>> files. It contains</span><br><span style="color: hsl(0, 100%, 40%);">-these main element sections:::</span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span style="color: hsl(0, 100%, 40%);">-[[schema_all_sec_resources]]</span><br><span style="color: hsl(0, 100%, 40%);">-- Section 'resources': Contains a set of elements validated with <<schema_want,want>></span><br><span style="color: hsl(0, 100%, 40%);">- schema. In <<suite_conf,suite.conf>> it is used to construct the list of</span><br><span style="color: hsl(0, 100%, 40%);">- requested resources. In <<scenario_conf,scenario.conf>>, it is used to inject</span><br><span style="color: hsl(0, 100%, 40%);">- attributes to the initial <<suite_conf,suite.conf>> _resources_ section and</span><br><span style="color: hsl(0, 100%, 40%);">- hence further restrain it.</span><br><span style="color: hsl(0, 100%, 40%);">-[[schema_all_sec_modifiers]]</span><br><span style="color: hsl(0, 100%, 40%);">-- Section 'modifiers': Both in <<suite_conf,suite.conf>> and</span><br><span style="color: hsl(0, 100%, 40%);">- <<scenario_conf,scenario.conf>>, values presented in here are injected into</span><br><span style="color: hsl(0, 100%, 40%);">- the content of the <<schema_all_sec_resources,resources section>> after</span><br><span style="color: hsl(0, 100%, 40%);">- _resource_ allocation, hereby overwriting attributes passed to the object</span><br><span style="color: hsl(0, 100%, 40%);">- class instance managing the specific _resource_ (matches by resource type and</span><br><span style="color: hsl(0, 100%, 40%);">- list position). Since it is combined with the content of</span><br><span style="color: hsl(0, 100%, 40%);">- <<schema_all_sec_resources,resources section>>, it is clear that the</span><br><span style="color: hsl(0, 100%, 40%);">- <<schema_want,want schema>> is used to validate this content.</span><br><span style="color: hsl(0, 100%, 40%);">-[[schema_all_sec_config]]</span><br><span style="color: hsl(0, 100%, 40%);">-- Section 'config': Contains configuration attributes for {app-name} object</span><br><span style="color: hsl(0, 100%, 40%);">- classes which are not _resources_, and hence cannot be configured with</span><br><span style="color: hsl(0, 100%, 40%);">- <<schema_all_sec_modifiers,modifiers>>. They can overwrite values provided in the</span><br><span style="color: hsl(0, 100%, 40%);">- <<defaults_conf,defaults.conf>> file. Content in this section follows the</span><br><span style="color: hsl(0, 100%, 40%);">- <<schema_config,config>> schema.</span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span style="color: hsl(0, 100%, 40%);">-//TODO: defaults.timeout should be change in code to be config.test_timeout or similar</span><br><span style="color: hsl(0, 100%, 40%);">-//TODO: 'config' should be split into its own schema and validate defaults.conf</span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span> [[config]]</span><br><span> === Configuration files and directories</span><br><span> </span><br><span>@@ -642,6 +431,217 @@</span><br><span> - phys_chan_config: TCH/F_TCH/H_PDCH</span><br><span> ----</span><br><span> </span><br><span style="color: hsl(120, 100%, 40%);">+=== Schemas</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+All configuration attributes in {app-name} are stored and provided as YAML</span><br><span style="color: hsl(120, 100%, 40%);">+files, which are handled internally mostly as sets of dictionaries, lists and</span><br><span style="color: hsl(120, 100%, 40%);">+scalars. Each of these configurations have a known format (set of keys and</span><br><span style="color: hsl(120, 100%, 40%);">+values), which is called 'schema'. Each provided configuration is validated</span><br><span style="color: hsl(120, 100%, 40%);">+against its 'schema' at parse time. Hence, 'schemas' can be seen as a namespace</span><br><span style="color: hsl(120, 100%, 40%);">+containing a structured tree of configuration attributes. Each attribute has a</span><br><span style="color: hsl(120, 100%, 40%);">+schema type assigned which constrains the type of value it can hold.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+There are several well-known schemas used across {app-name}, and they are</span><br><span style="color: hsl(120, 100%, 40%);">+described in following sub-sections.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+[[schema_main_cfg]]</span><br><span style="color: hsl(120, 100%, 40%);">+==== Schema 'main config'</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+This schema defines all the attributes available in {app-name} the main</span><br><span style="color: hsl(120, 100%, 40%);">+configuration file <<main_conf,main.conf>>, and it is used to validate it.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+[[schema_resources]]</span><br><span style="color: hsl(120, 100%, 40%);">+==== Schema 'resources'</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+This schema defines all the attributes which can be assigned to</span><br><span style="color: hsl(120, 100%, 40%);">+a _resource_, and it is used to validate the <<resources_conf,resources.conf>></span><br><span style="color: hsl(120, 100%, 40%);">+file. Hence, the <<resources_conf,resources.conf>> contains a list of elements</span><br><span style="color: hsl(120, 100%, 40%);">+for each resource type. This schema is also used and extended by the</span><br><span style="color: hsl(120, 100%, 40%);">+<<schema_want,'want' schema>>.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+It is important to understand that the content in this schema refers to a list of</span><br><span style="color: hsl(120, 100%, 40%);">+resources for each resource class. Since a list is ordered by definition, it</span><br><span style="color: hsl(120, 100%, 40%);">+clearly identifies specific resources by order. This is important when applying</span><br><span style="color: hsl(120, 100%, 40%);">+filters or modifiers, since they are applied per-resource in the list. One can</span><br><span style="color: hsl(120, 100%, 40%);">+for instance apply attribute A to first resource of class C, while not applying</span><br><span style="color: hsl(120, 100%, 40%);">+it or applying another attribute B to second resources of the same class. As a</span><br><span style="color: hsl(120, 100%, 40%);">+result, complex forms can be used to filter and modify a list of resources</span><br><span style="color: hsl(120, 100%, 40%);">+required by a testsuite.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+On the other hand, it's also important to note that lists for simple or scalar</span><br><span style="color: hsl(120, 100%, 40%);">+types are currently being treated as unordered sets, which mean combination of</span><br><span style="color: hsl(120, 100%, 40%);">+filters or modifiers apply differently. In the future, it may be possible to</span><br><span style="color: hsl(120, 100%, 40%);">+have both behaviors for scalar/simple types by using also the YAML 'set' type in</span><br><span style="color: hsl(120, 100%, 40%);">+{app-name}.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+//TODO: update this list and use a table for each resource type in its own object section</span><br><span style="color: hsl(120, 100%, 40%);">+////</span><br><span style="color: hsl(120, 100%, 40%);">+These kinds of resources and their attributes are known:</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+'ip_address'::</span><br><span style="color: hsl(120, 100%, 40%);">+ List of IP addresses to run osmo-nitb instances on. The main unit</span><br><span style="color: hsl(120, 100%, 40%);">+ typically has a limited number of such IP addresses configured, which</span><br><span style="color: hsl(120, 100%, 40%);">+ the connected BTS models can see on their network.</span><br><span style="color: hsl(120, 100%, 40%);">+ 'addr':::</span><br><span style="color: hsl(120, 100%, 40%);">+ IPv4 address of the local interface.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+'bts'::</span><br><span style="color: hsl(120, 100%, 40%);">+ List of available BTS hardware.</span><br><span style="color: hsl(120, 100%, 40%);">+ 'label':::</span><br><span style="color: hsl(120, 100%, 40%);">+ human readable label for your own reference</span><br><span style="color: hsl(120, 100%, 40%);">+ 'type':::</span><br><span style="color: hsl(120, 100%, 40%);">+ which way to launch this BTS, one of</span><br><span style="color: hsl(120, 100%, 40%);">+ - 'osmo-bts-sysmo'</span><br><span style="color: hsl(120, 100%, 40%);">+ - 'osmo-bts-trx'</span><br><span style="color: hsl(120, 100%, 40%);">+ - 'osmo-bts-octphy'</span><br><span style="color: hsl(120, 100%, 40%);">+ - 'ipa-nanobts'</span><br><span style="color: hsl(120, 100%, 40%);">+ 'ipa_unit_id':::</span><br><span style="color: hsl(120, 100%, 40%);">+ ip.access unit id to be used by the BTS, written into BTS and BSC config.</span><br><span style="color: hsl(120, 100%, 40%);">+ 'addr':::</span><br><span style="color: hsl(120, 100%, 40%);">+ Remote IP address of the BTS for BTS like sysmoBTS, and local IP address</span><br><span style="color: hsl(120, 100%, 40%);">+ to bind to for locally run BTS such as osmo-bts-trx.</span><br><span style="color: hsl(120, 100%, 40%);">+ 'band':::</span><br><span style="color: hsl(120, 100%, 40%);">+ GSM band that this BTS shoud use (*TODO*: allow multiple bands). One of:</span><br><span style="color: hsl(120, 100%, 40%);">+ - 'GSM-1800'</span><br><span style="color: hsl(120, 100%, 40%);">+ - 'GSM-1900'</span><br><span style="color: hsl(120, 100%, 40%);">+ - (*TODO*: more bands)</span><br><span style="color: hsl(120, 100%, 40%);">+ 'trx_list':::</span><br><span style="color: hsl(120, 100%, 40%);">+ Specific TRX configurations for this BTS. There should be as many of</span><br><span style="color: hsl(120, 100%, 40%);">+ these as the BTS has TRXes. (*TODO*: a way to define >1 TRX without</span><br><span style="color: hsl(120, 100%, 40%);">+ special configuration for them.)</span><br><span style="color: hsl(120, 100%, 40%);">+ 'hw_addr'::::</span><br><span style="color: hsl(120, 100%, 40%);">+ Hardware (MAC) address of the TRX in the form of '11:22:33:44:55:66',</span><br><span style="color: hsl(120, 100%, 40%);">+ only used for osmo-bts-octphy. (*TODO*: and nanobts??)</span><br><span style="color: hsl(120, 100%, 40%);">+ 'net_device'::::</span><br><span style="color: hsl(120, 100%, 40%);">+ Local network device to reach the TRX's 'hw_addr' at, only used for</span><br><span style="color: hsl(120, 100%, 40%);">+ osmo-bts-octphy. Example: 'eth0'.</span><br><span style="color: hsl(120, 100%, 40%);">+ 'nominal_power'::::</span><br><span style="color: hsl(120, 100%, 40%);">+ Nominal power to be used by the TRX.</span><br><span style="color: hsl(120, 100%, 40%);">+ 'max_power_red'::::</span><br><span style="color: hsl(120, 100%, 40%);">+ Max power reduction to apply to the nominal power of the TRX.</span><br><span style="color: hsl(120, 100%, 40%);">+'arfcn'::</span><br><span style="color: hsl(120, 100%, 40%);">+ List of ARFCNs to use for running BTSes, which defines the actual RF</span><br><span style="color: hsl(120, 100%, 40%);">+ frequency bands used.</span><br><span style="color: hsl(120, 100%, 40%);">+ 'arfcn':::</span><br><span style="color: hsl(120, 100%, 40%);">+ ARFCN number, see e.g.</span><br><span style="color: hsl(120, 100%, 40%);">+ https://en.wikipedia.org/wiki/Absolute_radio-frequency_channel_number</span><br><span style="color: hsl(120, 100%, 40%);">+ (note that the resource type 'arfcn' contains an item trait also named</span><br><span style="color: hsl(120, 100%, 40%);">+ 'arfcn').</span><br><span style="color: hsl(120, 100%, 40%);">+ 'band':::</span><br><span style="color: hsl(120, 100%, 40%);">+ GSM band name to use this ARFCN for, same as for 'bts:band' above.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+'modem'::</span><br><span style="color: hsl(120, 100%, 40%);">+ List of modems reachable via ofono and information on the inserted SIM</span><br><span style="color: hsl(120, 100%, 40%);">+ card. (Note: the MSISDN is allocated dynamically in test scripts).</span><br><span style="color: hsl(120, 100%, 40%);">+ 'label':::</span><br><span style="color: hsl(120, 100%, 40%);">+ Human readable label for your own reference, which also appears in logs.</span><br><span style="color: hsl(120, 100%, 40%);">+ 'path':::</span><br><span style="color: hsl(120, 100%, 40%);">+ Ofono's path for this modem, like '/modemkind_99'.</span><br><span style="color: hsl(120, 100%, 40%);">+ 'imsi':::</span><br><span style="color: hsl(120, 100%, 40%);">+ IMSI of the inserted SIM card, like '"123456789012345"'.</span><br><span style="color: hsl(120, 100%, 40%);">+ 'ki':::</span><br><span style="color: hsl(120, 100%, 40%);">+ 16 byte authentication/encryption KI of the inserted SIM card, in</span><br><span style="color: hsl(120, 100%, 40%);">+ hexadecimal notation (32 characters) like +</span><br><span style="color: hsl(120, 100%, 40%);">+ '"00112233445566778899aabbccddeeff"'.</span><br><span style="color: hsl(120, 100%, 40%);">+ 'auth_algo':::</span><br><span style="color: hsl(120, 100%, 40%);">+ Authentication algorithm to be used with the SIM card. One of:</span><br><span style="color: hsl(120, 100%, 40%);">+ - 'none'</span><br><span style="color: hsl(120, 100%, 40%);">+ - 'xor'</span><br><span style="color: hsl(120, 100%, 40%);">+ - 'comp128v1'</span><br><span style="color: hsl(120, 100%, 40%);">+ 'ciphers':::</span><br><span style="color: hsl(120, 100%, 40%);">+ List of ciphers that this modem supports, used to match</span><br><span style="color: hsl(120, 100%, 40%);">+ requirements in suites or scenarios. Any combination of:</span><br><span style="color: hsl(120, 100%, 40%);">+ - 'a5_0'</span><br><span style="color: hsl(120, 100%, 40%);">+ - 'a5_1'</span><br><span style="color: hsl(120, 100%, 40%);">+ - 'a5_2'</span><br><span style="color: hsl(120, 100%, 40%);">+ - 'a5_3'</span><br><span style="color: hsl(120, 100%, 40%);">+ - 'a5_4'</span><br><span style="color: hsl(120, 100%, 40%);">+ - 'a5_5'</span><br><span style="color: hsl(120, 100%, 40%);">+ - 'a5_6'</span><br><span style="color: hsl(120, 100%, 40%);">+ - 'a5_7'</span><br><span style="color: hsl(120, 100%, 40%);">+ 'features':::</span><br><span style="color: hsl(120, 100%, 40%);">+ List of features that this modem supports, used to match requirements in</span><br><span style="color: hsl(120, 100%, 40%);">+ suites or scenarios. Any combination of:</span><br><span style="color: hsl(120, 100%, 40%);">+ - 'sms'</span><br><span style="color: hsl(120, 100%, 40%);">+ - 'gprs'</span><br><span style="color: hsl(120, 100%, 40%);">+ - 'voice'</span><br><span style="color: hsl(120, 100%, 40%);">+ - 'ussd'</span><br><span style="color: hsl(120, 100%, 40%);">+////</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+[[schema_want]]</span><br><span style="color: hsl(120, 100%, 40%);">+==== Schema 'want'</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+This schema is basically the same as the <<schema_resources,resources>> one, but</span><br><span style="color: hsl(120, 100%, 40%);">+with an extra 'times' attribute for each resource item. All 'times' attributes</span><br><span style="color: hsl(120, 100%, 40%);">+are expanded before matching. For example, if a 'suite.conf' requests two BTS,</span><br><span style="color: hsl(120, 100%, 40%);">+one may enforce that both BTS should be of type 'osmo-bts-sysmo' in these ways:</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+----</span><br><span style="color: hsl(120, 100%, 40%);">+resources:</span><br><span style="color: hsl(120, 100%, 40%);">+ bts:</span><br><span style="color: hsl(120, 100%, 40%);">+ - type: osmo-bts-sysmo</span><br><span style="color: hsl(120, 100%, 40%);">+ - type: osmo-bts-sysmo</span><br><span style="color: hsl(120, 100%, 40%);">+----</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+or alternatively,</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+----</span><br><span style="color: hsl(120, 100%, 40%);">+resources:</span><br><span style="color: hsl(120, 100%, 40%);">+ bts:</span><br><span style="color: hsl(120, 100%, 40%);">+ - times: 2</span><br><span style="color: hsl(120, 100%, 40%);">+ type: osmo-bts-sysmo</span><br><span style="color: hsl(120, 100%, 40%);">+----</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+[[schema_config]]</span><br><span style="color: hsl(120, 100%, 40%);">+==== Schema 'config'</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+This schema defines all the attributes which can be used by object classes or</span><br><span style="color: hsl(120, 100%, 40%);">+tests during test execution. The main difference between this schema and the</span><br><span style="color: hsl(120, 100%, 40%);">+<<schema_resources,resources>> schema is that the former contains configuration</span><br><span style="color: hsl(120, 100%, 40%);">+to be applied globally for all objects being used, while the later applies</span><br><span style="color: hsl(120, 100%, 40%);">+attributes to a specific object in the list of allocated resources. This schema</span><br><span style="color: hsl(120, 100%, 40%);">+hence allows setting attributes for objects which are not allocated as resources</span><br><span style="color: hsl(120, 100%, 40%);">+and hence not directly accessible through scenarios, like a BSC or an iperf3</span><br><span style="color: hsl(120, 100%, 40%);">+client.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+This schema is built dynamically at runtime from content registered by:</span><br><span style="color: hsl(120, 100%, 40%);">+- object classes registering their own attributes</span><br><span style="color: hsl(120, 100%, 40%);">+- test suite registering their own attributes through <<suite_conf,suite.conf>></span><br><span style="color: hsl(120, 100%, 40%);">+ and tests being able to later retrieve them through 'testenv' API.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+[[schema_all]]</span><br><span style="color: hsl(120, 100%, 40%);">+==== Schema 'all'</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+This schema is basically an aggregated namespace for <<schema_want,want>> schema</span><br><span style="color: hsl(120, 100%, 40%);">+and <<schema_config,config>> schema, and is the one used by</span><br><span style="color: hsl(120, 100%, 40%);">+<<suite_conf,suite.conf>> and <<scenario_conf,scenario.conf>> files. It contains</span><br><span style="color: hsl(120, 100%, 40%);">+these main element sections:::</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+[[schema_all_sec_resources]]</span><br><span style="color: hsl(120, 100%, 40%);">+- Section 'resources': Contains a set of elements validated with <<schema_want,want>></span><br><span style="color: hsl(120, 100%, 40%);">+ schema. In <<suite_conf,suite.conf>> it is used to construct the list of</span><br><span style="color: hsl(120, 100%, 40%);">+ requested resources. In <<scenario_conf,scenario.conf>>, it is used to inject</span><br><span style="color: hsl(120, 100%, 40%);">+ attributes to the initial <<suite_conf,suite.conf>> _resources_ section and</span><br><span style="color: hsl(120, 100%, 40%);">+ hence further restrain it.</span><br><span style="color: hsl(120, 100%, 40%);">+[[schema_all_sec_modifiers]]</span><br><span style="color: hsl(120, 100%, 40%);">+- Section 'modifiers': Both in <<suite_conf,suite.conf>> and</span><br><span style="color: hsl(120, 100%, 40%);">+ <<scenario_conf,scenario.conf>>, values presented in here are injected into</span><br><span style="color: hsl(120, 100%, 40%);">+ the content of the <<schema_all_sec_resources,resources section>> after</span><br><span style="color: hsl(120, 100%, 40%);">+ _resource_ allocation, hereby overwriting attributes passed to the object</span><br><span style="color: hsl(120, 100%, 40%);">+ class instance managing the specific _resource_ (matches by resource type and</span><br><span style="color: hsl(120, 100%, 40%);">+ list position). Since it is combined with the content of</span><br><span style="color: hsl(120, 100%, 40%);">+ <<schema_all_sec_resources,resources section>>, it is clear that the</span><br><span style="color: hsl(120, 100%, 40%);">+ <<schema_want,want schema>> is used to validate this content.</span><br><span style="color: hsl(120, 100%, 40%);">+[[schema_all_sec_config]]</span><br><span style="color: hsl(120, 100%, 40%);">+- Section 'config': Contains configuration attributes for {app-name} object</span><br><span style="color: hsl(120, 100%, 40%);">+ classes which are not _resources_, and hence cannot be configured with</span><br><span style="color: hsl(120, 100%, 40%);">+ <<schema_all_sec_modifiers,modifiers>>. They can overwrite values provided in the</span><br><span style="color: hsl(120, 100%, 40%);">+ <<defaults_conf,defaults.conf>> file. Content in this section follows the</span><br><span style="color: hsl(120, 100%, 40%);">+ <<schema_config,config>> schema.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+//TODO: defaults.timeout should be change in code to be config.test_timeout or similar</span><br><span style="color: hsl(120, 100%, 40%);">+//TODO: 'config' should be split into its own schema and validate defaults.conf</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span> === Example Setup</span><br><span> </span><br><span> {app-name} comes with an example official setup which is the one used to run</span><br><span></span><br></pre><p>To view, visit <a href="https://gerrit.osmocom.org/c/osmo-gsm-tester/+/18215">change 18215</a>. To unsubscribe, or for help writing mail filters, visit <a href="https://gerrit.osmocom.org/settings">settings</a>.</p><div itemscope itemtype="http://schema.org/EmailMessage"><div itemscope itemprop="action" itemtype="http://schema.org/ViewAction"><link itemprop="url" href="https://gerrit.osmocom.org/c/osmo-gsm-tester/+/18215"/><meta itemprop="name" content="View Change"/></div></div>
<div style="display:none"> Gerrit-Project: osmo-gsm-tester </div>
<div style="display:none"> Gerrit-Branch: master </div>
<div style="display:none"> Gerrit-Change-Id: Iaf31808a655a5c77a1dfaa155e86d42585130820 </div>
<div style="display:none"> Gerrit-Change-Number: 18215 </div>
<div style="display:none"> Gerrit-PatchSet: 2 </div>
<div style="display:none"> Gerrit-Owner: pespin <pespin@sysmocom.de> </div>
<div style="display:none"> Gerrit-Reviewer: Jenkins Builder </div>
<div style="display:none"> Gerrit-Reviewer: pespin <pespin@sysmocom.de> </div>
<div style="display:none"> Gerrit-MessageType: merged </div>