Change in osmo-gsm-tester[master]: doc/manuals: Swap order of schemas and config files

This is merely a historical archive of years 2008-2021, before the migration to mailman3.

A maintained and still updated list archive can be found at https://lists.osmocom.org/hyperkitty/list/gerrit-log@lists.osmocom.org/.

pespin gerrit-no-reply at lists.osmocom.org
Tue May 12 11:13:17 UTC 2020


pespin has uploaded this change for review. ( https://gerrit.osmocom.org/c/osmo-gsm-tester/+/18215 )


Change subject: doc/manuals: Swap order of schemas and config files
......................................................................

doc/manuals: Swap order of schemas and config files

First explain the different config files and directories, later describe
the schemas used in each of them.

Change-Id: Iaf31808a655a5c77a1dfaa155e86d42585130820
---
M doc/manuals/chapters/config.adoc
1 file changed, 211 insertions(+), 211 deletions(-)



  git pull ssh://gerrit.osmocom.org:29418/osmo-gsm-tester refs/changes/15/18215/1

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

-- 
To view, visit https://gerrit.osmocom.org/c/osmo-gsm-tester/+/18215
To unsubscribe, or for help writing mail filters, visit https://gerrit.osmocom.org/settings

Gerrit-Project: osmo-gsm-tester
Gerrit-Branch: master
Gerrit-Change-Id: Iaf31808a655a5c77a1dfaa155e86d42585130820
Gerrit-Change-Number: 18215
Gerrit-PatchSet: 1
Gerrit-Owner: pespin <pespin at sysmocom.de>
Gerrit-MessageType: newchange
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.osmocom.org/pipermail/gerrit-log/attachments/20200512/71cae0fb/attachment.htm>


More information about the gerrit-log mailing list