From 2b81f34fcd6b99ef0dcf7dc1630cf0f4e521e565 Mon Sep 17 00:00:00 2001 From: Joachim Wiberg Date: Wed, 20 Mar 2024 07:00:01 +0100 Subject: [PATCH] doc: cleanup and harmoize yang model linking Signed-off-by: Joachim Wiberg --- doc/cli/text-editor.md | 2 +- doc/hardware.md | 36 +++++++++++++++++++++++++----------- doc/license.md | 18 +++++++++--------- doc/networking.md | 29 +++++++++++++++++------------ 4 files changed, 52 insertions(+), 33 deletions(-) diff --git a/doc/cli/text-editor.md b/doc/cli/text-editor.md index c81904ee..0b8a5245 100644 --- a/doc/cli/text-editor.md +++ b/doc/cli/text-editor.md @@ -66,5 +66,5 @@ admin@host:/config/system/> set text-editor emacs nano vi admin@host:/config/system/> set text-editor nano admin@host:/config/system/> leave -admin@example:/> +admin@host:/> ``` diff --git a/doc/hardware.md b/doc/hardware.md index 9c3ca078..12de9b9d 100644 --- a/doc/hardware.md +++ b/doc/hardware.md @@ -1,10 +1,13 @@ -# Hardware information and status +# Hardware Information and Status -The hardware infomation and status is handled by the YANG model [IETF hardware][ietf-hardware]. -with deviations and augmentations in _infix-hardware_. +The hardware infomation and status is handled by the YANG model [IETF +hardware][1], with deviations and augmentations in _infix-hardware_. ## USB Ports -For infix to be able to control the USB port(s), a device tree modification is needed (see _alder.dtsi_ for full example). + +For Infix to be able to control USB port(s), a device tree modification +is needed (see _alder.dtsi_ for full example). + ``` chosen { infix { @@ -13,33 +16,44 @@ For infix to be able to control the USB port(s), a device tree modification is n }; }; ``` + Two USB ports are also exposed in QEMU for test purpose. -All USB ports in the system will be disabled during boot due to the file _board/common/rootfs/etc/modprobe.d/usbcore.conf_. -If you not want Infix to controll the USB port(s), remove the file or manually enable the USB bus, here is an example: +All USB ports in the system will be disabled during boot due to the file +`board/common/rootfs/etc/modprobe.d/usbcore.conf`. If you do not want +Infix to control USB port(s), remove the file or manually enable the USB +bus, here is an example: ``` - # Enable the bus +# Enable the bus echo 1 > /sys/bus/usb/devices/usb1/authorized ``` + And then enable sub-devices (e.g. USB memory) + ``` # Enable a device plugged into usb1 echo 1 > /sys/bus/usb/devices/usb1/1-1/authorized ``` ### Current status + ``` admin@example:/> show hardware USB PORTS NAME STATE USB unlocked ``` -An USB port can be in two states _unlocked_ and _locked_. When a port is locked, -all connected devices will get power, but never authorized by Linux to use. + +An USB port can be in two states _unlocked_ and _locked_. When a port is +locked, all connected devices will get power, but never authorized by +Linux to use. ### Configure USB port -> **Note:** You can only configure an USB ports that exist in _show hardware_ in admin exec. + +> **Note:** You can only configure USB ports known to the system. See +> `show hardware` in admin-exec context. (Use `do` prefix in configure +> context.) ``` root@example:/> configure @@ -48,4 +62,4 @@ all connected devices will get power, but never authorized by Linux to use. root@example:/> ``` -[ietf-hardware]: https://www.rfc-editor.org/rfc/rfc8348.html +[1]: https://www.rfc-editor.org/rfc/rfc8348.html diff --git a/doc/license.md b/doc/license.md index c2dd4b7c..5517dadf 100644 --- a/doc/license.md +++ b/doc/license.md @@ -6,8 +6,9 @@ them, as well as the build system with its helper scripts and tools, is from [Buildroot][1], which is distributed under the terms of the GNU General Public License (GPL). See the file COPYING for details. -Some files in Buildroot contain a different license statement. Those -files are licensed under the license contained in the file itself. +Some files in Buildroot may contain a different open source license +statement. Those files are licensed under the license contained in the +file itself. Buildroot and Infix also bundle patch files, which are applied to the sources of the various packages. Those patches are not covered by the @@ -20,13 +21,12 @@ Infix releases include the license information covering all Open Source packages. This is extracted automatically at build time using the tool `make legal-info`. Any proprietary software built on top of Infix, or Buildroot, would need separate auditing to ensure it does not link with -any GPL[^2] licensed library. +any GPL[^1] licensed library. -[^2]: Infix image builds use GNU libc (GLIBC) which is covered by the - [LGPL][8]. The LGPL *does allow* proprietary software, as long as - said software is linking dynamically, [not statically][5], to GLIBC. +[^1]: Infix image builds use GNU libc (GLIBC) which is covered by the + [LGPL][3]. The LGPL *does allow* proprietary software, as long as + said software is linking dynamically, [not statically][2], to GLIBC. [1]: https://buildroot.org/ -[2]: https://www.sysrepo.org/ -[5]: https://lwn.net/Articles/117972/ -[8]: https://en.wikipedia.org/wiki/GNU_Lesser_General_Public_License +[2]: https://lwn.net/Articles/117972/ +[3]: https://en.wikipedia.org/wiki/GNU_Lesser_General_Public_License diff --git a/doc/networking.md b/doc/networking.md index 28da1f2f..1da93573 100644 --- a/doc/networking.md +++ b/doc/networking.md @@ -2,11 +2,15 @@ Infix aims to support all Linux Networking constructs. The YANG models used to describe the system are chosen to fit well and leverage the -underlying Linux kernel's capabilities. The `ietf-interfaces.yang` -model forms the base, extended with `ietf-ip.yang` and other layer-3 +underlying Linux kernel's capabilities. The [ietf-interfaces.yang][1] +model forms the base, extended with [ietf-ip.yang][2] and other layer-3 IETF models. The layer-2 bridge and aggregate models are defined by Infix to exploit the unique features not available in IEEE models. +> **Note:** when issuing `leave` to activate your changes, remember to +> also save your settings, `copy running-config startup-config`. See +> the [CLI Introduction](cli/introduction.md) for a background. + ## Interface LEGO® @@ -310,7 +314,7 @@ default. As shown, the link-local IPv4 address is configured with `set autconf enabled true`. The resulting address (169.254.1.3/16) is of type -*random* ([IETF ip-yang][ietf-ip-yang]). +*random* ([ietf-ip.yang][2]). #### Use of DHCP for IPv4 address assignment @@ -378,9 +382,8 @@ admin@example:/> Stateless address auto-configuration of global addresses is enabled by default. The address is formed by concatenating the network prefix advertised by the router (here 2001:db8:0:1::0/64) and the interface -identifier. The resulting address is of type *link-layer*, as it -is formed based on the interface identifier ([IETF -ip-yang][ietf-ip-yang]). +identifier. The resulting address is of type *link-layer*, as it is +formed based on the interface identifier ([ietf-ip.yang][2]). admin@example:/> show interfaces INTERFACE PROTOCOL STATE DATA @@ -426,7 +429,8 @@ are formed from a link-identifier based on the MAC address. admin@example:/> To avoid revealing identity information in the IPv6 address, it is -possible to specify use of a random identifier ([ietf-ip][ietf-ip-yang] YANG and [RFC8981][ietf-ipv6-privacy]). +possible to specify use of a random identifier ([ietf-ip.yang][2] and +[RFC8981][3]). admin@example:/> configure admin@example:/config/> edit interface eth0 ipv6 @@ -627,10 +631,11 @@ The source protocol describes the origin of the route. The YANG model *ietf-routing* support multiple ribs but only two are currently supported, namely `ipv4` and `ipv6`. -[ietf-ip-yang]: https://www.rfc-editor.org/rfc/rfc8344.html -[ietf-ipv6-privacy]: https://www.rfc-editor.org/rfc/rfc8981.html +[1]: https://www.rfc-editor.org/rfc/rfc8343 +[2]: https://www.rfc-editor.org/rfc/rfc8344 +[3]: https://www.rfc-editor.org/rfc/rfc8981 [^1]: Please note, link aggregates are not yet supported in Infix. -[^2]: Link-local IPv6 addresses are implicitly enabled when enabling IPv6. - IPv6 can be enabled/disabled per interface in the [ietf-ip][ietf-ip-yang] - YANG model. +[^2]: Link-local IPv6 addresses are implicitly enabled when enabling + IPv6. IPv6 can be enabled/disabled per interface in the + [ietf-ip][2] YANG model.