ncsid/doc/ncsid_internals.md

1 # NC-SId Internals
3 **NOTE**: This documents describes the internal architecture of NC-SId daemon.
4 However, it is meant to be used as a guide for understanding the code, not on
11 - **NC-SId Core**. These are new components implemented in NC-SId.
13 - **Hardware**. External hardware components, in this case, the NIC.
15 - **EC**. This is the code borrowed from EC. The three state machines are pretty
18 - **External Components**. These are external services/daemons NC-SIs interacts
25 In the NIC — NC-SId interactions, NIC acts as a server, replying to NC-SId
26 requests and NC-SId itself acts as a client, sending those requests. Thus, there
27 is no state in NIC (server), but there is a state in NC-SId (client).
31 NC-SId reuses the state machines from EC. They are treated like black boxes.
33 NC-SI command buffer (reply from the NIC) and returns the buffer that needs to
38 This state machine performs basic configuration of the NC-SI comm channel and
47 This state machine periodically tests NC-SI connection with the NIC, verifies
48 filters and queries the NIC state (hostless or host-based). If it ever fails,
49 all state machines restart, which means that NC-SI in the NIC is also reset and
52 ---
55 not a part of EC state machines' state:
57 - State Parameters. These structures are allocated outside of EC State Machines,
59 - MAC Address. For L2 FSM this parameter is _OUT_.
60 - IP Address (only for L3/4 FSM and Test FSM) for setting up and verifying
62 - TCP Port (only for L3/4 FSM and Test FSM) for setting up and verifying
65 In the initial state the command buffer (reply from the NIC) is empty. When
66 there is nothing more to send to the NIC, i.e. that particular state machine is
67 done, it returns empty buffer.
71 NC-SId uses `phosphord-networkd` to configure the BMC's network (MAC Address).
72 In turn, `phosphord-networkd` uses `systemd`. Their interactions go through
75 ## NC-SId Core
85 Implements `net::ConfigBase` and makes calls to `phosphord-networkd` via `DBus`
90 Implements `net::SockIO` and sends NC-SI commands to the NIC through raw Unix
95 ---
101 To allow some fairly sophisticated unit-tests, EC State Machines as well as
105 The most complicated part of these tests is `mock::NIC`, which acts as a NC-SI
106 server, replying to NC-SI requests coming from NC-SI State Machines.