# An interpretation of Nm configurations

We'll only focus on the configurations that we need when implementing Nm.

## Implementation goals
What should we achieve when implementing Nm?

### Goal of the Nm module
Nm offers StateManagement the Nm network handles, each of which can control multiple networks together.

> The Adaptive Network Management offers services that allows to request and query the network states for logical network handles ...
> [name=SWS_NetworkManagement 7][^nm]

> Logical network handles are (a) mapped to one or more partial or physical networks, ...
> By using the logical network hanlde all assigned partial networks, VLANs and underlying physical channel(s) are controlled together.
> [name=SWS_NetworkManagement 7.3][^nm]

### Goal of an Nm node
An Nm node should be able to send NM packets to all nodes in the NM cluster via multicast periodically when necessary.

> The AUTOSAR Adaptive NM is based on decentralized direct network management strategy, which means that every network node performs activities self-sufficient depending only on the NM packets received and/or transmitted within the communication system.
>
>The AUTOSAR Adaptive NM algorithm is based on **periodic NM packets, which are received by all nodes in the cluster via multicast.**[name=SWS_NetworkManagement 7.2][^nm]

Combining the two, we could get some basic understanding of the goals and concepts of the Nm module.
- There're many **Nm nodes**, gathering into **Nm clusters**.
- Nm nodes, by sending/receiving **Nm packets** to other nodes in their belonging Nm clusters, can activate/deactivate the clusters.
- The status of Nm clusters can somehow map to physical networks, thus the control over networks is achieved.
- Finally, the Nm module provides the ability to control networks to StateManagement, via **Nm network handles**.

Note the (de)activation of a cluster is the effect due to the correct behavior of nodes. The Nm module does not control the network (or cluster) directly.

Notes:
- To see the explanation of node's **correct behavior**, visit the Operational Modes section of our previous report. [^NMop]
Here's the only fix:
A node doesn't send to **every node**, but to a **multicast IP address**. The message delivery to other nodes is handled by UDP Multicast technology itself.
We'll see the multicast IP address later in configurations.
- To see the **format** of Nm packets, visit another report[^NMformat] about message format.

## Details and configurations
In following sections, we'll introduce many configurations.
Keep in mind that Nm module don't configure them, but read and follow them.

### NmConfig
This is the simplest one.
All Nm-related configuration is here in `NmConfig`.
[TPS_ManifestSpecification[^manifest] Table 9.57]

We'll talk about `NmCluster` later.

### Physical Network
The unit that a Nm module controls is a physical network (though not directly). In Nm, a physical network means a **VLAN**[^VLAN]. To put it simply, a VLAN is a subset of the actually connected devices.

AP uses `EthernetPhysicalChannel` to model it:

[TPS_ManifestSpecification[^manifest] Table D.60]

Those fields are not important to us.
Knowing that it's the unit of control is enough.

### Nm cluster
The Nm configuration corresponds to a `EthernetPhysicalChannel`.
Here both abstract base class `NmCluster` and concrete subclass `UdpNmCluster` are shown here.
[SWS_NetworkManagement[^nm] Table A.3, Table A.9]

As you can see, many configurations controlling the behavior of Nm Algorithm are listed in these 2 classes.
If you find any configuration with `nm-` prefix, check `NmCluster` and `UdpNmCluster` first is probably the fastest way to go.

An important configuration, **multicast IP and port**, is hidden in `UdpNmCluster`.`networkConfiguration`.
Here's `UdpNmNetworkConfiguration`
[TRS_ManifestSpecification[^manifest] Table D.126]

This is exactly where a node should check when it tries to multicast Nm packets.

Also note the `vlan` field is the connection between a `NmCluster` and a `EthernetPhysicalChannel`.
See this connection as a bidirectional mapping. That is, we can check which `EthernetPhysicalChannel` a `NmCluster` corresponds to, and vice versa.

### Nm node
Pretty clear. As described above, a `NmCluster` is a group of `NmNode`. More specifically, `NmCluster`.`nmNode` aggregates the nodes of the cluster.
Again, both abstract base class `NmNode` and concrete subclass `UdpNmNode` are shown here.
[SWS_NetworkManagment[^nm] Table A.5, Table A.10]

### EthernetCommunicationConnector
Referenced by `NmNode`.`communicationConnector`.
As you might guess, like `NmCluster` and `EthernetPhysicalChannel`, it's the corresponding element of `NmNode` in network configuration of AP.

Our `Macahine`, where our AP stack runs on, connects to different VLANs via different `EthernetCommunicationConnetor`s.
Another way is to think of a `EthernetCommunicationConnector` as a *shadow* of our `Machine` in different VLANs. In this interpretation, the similar structure between
`EthernetCommunicationConnector` $\leftrightarrow$ `EtherneyPhysicalChannel`
`NmNode` $\leftrightarrow$ `NmCluster`
is shown more clearly.

[SWS_NetworkManagement[^nm] Table A.1]

Those fields are not important to us. Grabbing the idea of a `EthernetCommunicationConnector` and its relation between `NmNode` is enough.

Now the basic elements are all presented. But what about Nm network handles, which we'll actually provide to StateManagement?

## Nm network handle
Recall the job of network handles:
> Nm offers StateManagement the Nm network handles, each of which can control multiple networks together.

It has to control **multiple** networks together, so it must somehow map to some of the above elements.
[SWS_NetworkManagement[^nm] Table A.4]

For now put `partialNetwork` aside, we'll focus on physical `vlan` first.

As you can see, it references multiple `EthernetCommunicationConnector`s, which in terms connects to the corresponding `NmNode`s and `NmCluster`s the handle wants to control.

If you've already checked the report about nodes behavior[^NMop], you'll see the elements that's really doing something is the nodes. The effect of a network is activated/deactivated is due to the behavior of nodes.

Here, the `EthernetCommunicationConnector`s referenced by `vlan` field are the nodes which should enter `Nomral Operation State` and keep multicasting packets.

`NmNetworkHandle`s that Nm should provide are also defined by the rest of AP, aggregated in `NmInstantiation`.
[TRS_ManifestSpecification[^manifest] Table 9.55]

`NmInstantiation` is a element of `Machine`.`moduleInstantiation`.

## Extending to partial network
> ... while a partial network itself can be mapped to one or multiple physical networks.
> [name=SWS_NetworkManagement 7.3][^nm]

From the description, a **partial network** is a collection of multiple VLANs.
So by referencing a partial network, multiple VLANs are referenced.

`NmNetworkHandle` use the field `partialNetwork` to reference a partial network.

### Pnc mapping
However, `PncMappingIdent` is only a referrable identifier, the actual configurations are located in `PncMapping`.
[SWS_NetworkManagement Table A.6, Table A.7]

There're two ways `PncMapping` connects to VLANs. They can be used at the same time.
1. `physicalChannel`
This is rather straightforward, refer to a `PhysicalChannel`. In Nm, we only care the case with type `EthernetPhysicalChannel` (which is a VLAN).
2. `serviceInstance`
There will be a `ServiceInstanceToMachineMapping`, which refers to both `AdaptivePlatformServiceInstance` and `EthernetCommunicationConnector`.
Thus providing a map from `AdaptivePlatformServiceInstance` to `EthernetCommunicationConnector`.
[TRS_ManifestSpecification[^manifest] Table 10.31]
(Note: `CommunicationConnector` is the base class of `EthernetCommunicationConnector`)

## What's next?
I believe that everything is ready to develop a working Nm module.
Here is a list of reports may help during development:
- Structure, mental models and confirugations of Nm module:
current report
- Behavior of node:
https://hackmd.io/e7LWFlwkSIGeZldXTpx5Wg?view#Operational-Modes with the fix note in the section [Goal of an Nm node](https://hackmd.io/czja6H2UR1KjolsJchdkzw?both#Goal-of-an-Nm-node)
- NM message format:
https://hackmd.io/TtbN7yZ2QzW5rCSp5ugi-g
- ara::com service skeleton class implementation:
https://hackmd.io/v7bSV3o1RGmyy_gcoYZR0g

Our only question is:
- Given a service module (like Nm), how to put it into AP so it'll be correctly started?

## Documents
[^nm]: [SWS_NetworkManagement](https://www.autosar.org/fileadmin/standards/adaptive/22-11/AUTOSAR_SWS_NetworkManagement.pdf) R22-11

[^manifest]: [TPS_ManifestSpecification](https://www.autosar.org/fileadmin/standards/adaptive/21-11/AUTOSAR_TPS_ManifestSpecification.pdf) R21-11

[^VLAN]: These links may help in grabbing its concept. Don't worry too much about it, we don't need to configure it anyway.
https://www.youtube.com/watch?v=_PPaArOxHhw
https://www.youtube.com/watch?v=oo-hejIq3iQ

[^NMop]: ara::nm, Operational Modes section
https://hackmd.io/e7LWFlwkSIGeZldXTpx5Wg?view#Operational-Modes

[^NMformat]: ara::nm 2 : NM Messages
https://hackmd.io/TtbN7yZ2QzW5rCSp5ugi-g