services/mctp/server/INITIALIZATION.md - third_party/github/OpenPRoT/openprot - Git at Google

 # MCTP Server — Initialization and Variable Glossary

 Source: `services/mctp/server/src/main.rs`

 ---

 ## Build Modes

 The server compiles into one of two mutually exclusive modes, selected by Cargo
 feature flags set in the Bazel `rust_app` target.

 | Feature flags | Mode | IPC served? | SPDM in-process? |
 |---|---|---|---|
 | _(none)_ | Notification | Yes | No |
 | `i2c-polling` | Polling | No | No |
 | `i2c-polling` + `direct-client` | Polling + SPDM | No | Yes |

 ---

 ## Initialization Sequence

 ### Shared constants (always)

 ```
 OWN_EID = 0x08       — MCTP Endpoint ID assigned to this device
 OWN_I2C_ADDR = 0x10  — I2C 7-bit slave address of this device
 ```

 ---

 ### Polling mode (`i2c-polling`)

 Steps execute once at startup before the event loop begins.

 ```
 1. IpcI2cClient::new(handle::I2C)
        → Opens IPC channel to the I2C server (for configuration and rx).
          Stored in `i2c`.

 2. I2cAddress::new(OWN_I2C_ADDR)
        → Validates the address value fits in 7 bits.
          Stored in `addr`.

 3. i2c.configure_target_address(BUS_2, addr)
        → Programs the I2C hardware to respond to OWN_I2C_ADDR on bus 2.
          FATAL if this fails (I2C server unreachable or bad address).

 4. i2c.enable_receive(BUS_2)
        → Arms the I2C slave receive FIFO. After this the hardware will
          accept incoming frames into the I2C server's buffer.
          FATAL if this fails.

 5. IpcI2cClient::new(handle::I2C)  [second instance]
        → A separate IPC channel to the I2C server, used exclusively for
          outbound I2C master writes. Ownership is transferred to I2cSender.

 6. I2cSender::new(i2c_client_2, BUS_2, OWN_I2C_ADDR)
        → Outbound MCTP-over-I2C transport. Implements mctp_lib::Sender.
          Stored in `sender`.

 7. MctpI2cReceiver::new(OWN_I2C_ADDR)
        → Inbound frame decoder. Strips I2C framing to produce raw MCTP
          packets. Stored in `receiver`.

 8a. (direct-client only) RefCell::new(Server::new(Eid(OWN_EID), 0, sender))
        → MCTP router wrapped in RefCell for shared &self access.
          Stored in `server_cell`.

 8b. (no direct-client) Server::new(Eid(OWN_EID), 0, sender)
        → MCTP router, exclusively owned.
          Stored in `server_plain`.

 ── SPDM setup (direct-client only) ──────────────────────────────────────────

 9.  DirectMctpClient::new(&server_cell)
        → In-process MctpClient. Calls server_cell methods directly;
          no IPC channel to a separate process.
          Consumed immediately by step 10.

 10. MctpSpdmTransport::new_responder(client)
        → SPDM transport layer in responder mode (listens for msg_type=0x05).
          Stored in `transport`.

 11. transport.init_sequence()
        → Calls server.listener(0x05) in-process, reserving a listener handle
          in the router for SPDM messages.
          FATAL if the router's listener table is full (MAX_LISTENERS=8).

 12. MockCertStore / MockHash / MockRng / MockEvidence
        → Placeholder platform implementations.  No crypto hardware access.
          Stored in `cert_store`, `hash`, `m1_hash`, `l1_hash`, `rng`, `evidence`.

 13. CapabilityFlags { CERT_CAP, CHAL_CAP, MEAS_CAP=2, MEAS_FRESH_CAP, CHUNK_CAP }
        → Bitmask of SPDM capabilities advertised to the requester.
          Stored in `flags`, then moved into `capabilities`.

 14. DeviceCapabilities { ct_exponent=0, data_transfer_size=1024,
                          max_spdm_msg_size=4096 }
        → SPDM device capability parameters. Stored in `capabilities`.

 15. SUPPORTED_VERSIONS = [V12, V13]  (static)
        → SPDM protocol versions this responder accepts.

 16. LocalDeviceAlgorithms { SHA-384, ECDSA-P384, DMTF measurements }
        → Cryptographic algorithm selections. Stored in `algorithms`.

 17. SpdmContext::new(...)
        → Constructs the full SPDM state machine. Takes references to all
          platform impls (transport, cert_store, hash, rng, evidence).
          FATAL if any required platform impl is misconfigured.
          Stored in `spdm_ctx`.

 18. [0u8; MAX_PAYLOAD_SIZE]  +  MessageBuf::new(&mut spdm_buf)
        → Fixed-size scratch buffer for SPDM message encoding/decoding.
          msg_buf wraps spdm_buf for the lifetime of the loop.
          Both declared outside the loop to avoid borrow-checker conflict.
 ```

 ---

 ### Notification mode (default, no `i2c-polling`)

 ```
 1. IpcI2cClient::new(handle::I2C)
        → IPC channel to I2C server for configuration, notifications, and
          pending-message retrieval. Stored in `i2c_notify`.

 2-4.   Same address configuration as polling mode (steps 2-4 above).

 5.  i2c_notify.register_notification(BUS_2, 0)
        → Requests the I2C server to post a USER signal to this process
          when a slave-mode frame arrives. FATAL if it fails.

 6.  IpcI2cClient::new(handle::I2C)  [second instance]
        → Separate channel for outbound sends, transferred to I2cSender.

 7-8.   I2cSender and MctpI2cReceiver as in polling mode.

 9.  Server::new(Eid(OWN_EID), 0, sender)
        → MCTP router. Stored in `server`.

 10. [0u8; MAX_REQUEST_SIZE/MAX_RESPONSE_SIZE/MAX_PAYLOAD_SIZE]
        → IPC wire buffers. Stored in `request_buf`, `response_buf`, `recv_buf`.

 11. syscall::wait_group_add(WG, MCTP, READABLE, user_data=0)
        → Register the IPC channel as event source 0 in the WaitGroup.

 12. syscall::wait_group_add(WG, I2C, USER, user_data=1)
        → Register the I2C notification signal as event source 1.
 ```

 ---

 ## Variable Glossary

 ### Constants

 | Name | Value | Meaning |
 |---|---|---|
 | `OWN_EID` | `0x08` | MCTP Endpoint ID of this device |
 | `OWN_I2C_ADDR` | `0x10` | I2C 7-bit slave address of this device |

 ### Polling mode variables

 | Name | Type | Lifetime | Purpose |
 |---|---|---|---|
 | `i2c` | `IpcI2cClient` | setup + loop | I2C IPC channel for configuration, `wait_for_messages`, rx |
 | `addr` | `I2cAddress` | setup only | Validated I2C address; consumed by `configure_target_address` |
 | `sender` | `I2cSender` | loop (via server) | Outbound MCTP-over-I2C; owns a second `IpcI2cClient` |
 | `receiver` | `MctpI2cReceiver` | loop | Decodes I2C slave frames into raw MCTP packets |
 | `server_cell` | `RefCell<Server>` | loop | MCTP router; RefCell allows shared borrow with DirectMctpClient |
 | `server_plain` | `Server` | loop | MCTP router when `direct-client` is not enabled |
 | `transport` | `MctpSpdmTransport` | loop (via spdm_ctx) | SPDM transport; calls server_cell through DirectMctpClient |
 | `cert_store` | `MockCertStore` | loop (via spdm_ctx) | Provides certificate chain to SPDM protocol |
 | `hash` | `MockHash` | loop (via spdm_ctx) | Main transcript hash |
 | `m1_hash` | `MockHash` | loop (via spdm_ctx) | M1 measurement hash (measurements with signature) |
 | `l1_hash` | `MockHash` | loop (via spdm_ctx) | L1 challenge hash |
 | `rng` | `MockRng` | loop (via spdm_ctx) | Random number source (nonces, challenge data) |
 | `evidence` | `MockEvidence` | loop (via spdm_ctx) | Device measurement evidence provider |
 | `flags` | `CapabilityFlags` | setup only | SPDM capability bitmask; consumed by `capabilities` |
 | `capabilities` | `DeviceCapabilities` | setup only | SPDM capability parameters; consumed by `SpdmContext::new` |
 | `SUPPORTED_VERSIONS` | `[SpdmVersion; 2]` | `'static` | SPDM versions [V1.2, V1.3]; must be static due to spdm-lib lifetime |
 | `algorithms` | `LocalDeviceAlgorithms` | setup only | Algorithm selections; consumed by `SpdmContext::new` |
 | `spdm_ctx` | `SpdmContext` | loop | Full SPDM state machine; processes one request per `process_message` call |
 | `spdm_buf` | `[u8; MAX_PAYLOAD_SIZE]` | loop | Raw byte storage for SPDM message encoding |
 | `msg_buf` | `MessageBuf` | loop | Cursor over `spdm_buf`; reset each iteration via `msg_buf.reset()` |

 ### Notification mode variables

 | Name | Type | Lifetime | Purpose |
 |---|---|---|---|
 | `i2c_notify` | `IpcI2cClient` | loop | I2C channel for slave config, notification registration, and `get_pending_messages` |
 | `addr` | `I2cAddress` | setup only | Validated I2C address |
 | `sender` | `I2cSender` | loop (via server) | Outbound MCTP-over-I2C |
 | `receiver` | `MctpI2cReceiver` | loop | Decodes I2C slave frames |
 | `server` | `Server` | loop | MCTP router |
 | `request_buf` | `[u8; MAX_REQUEST_SIZE]` | loop | IPC receive buffer for inbound MCTP operation requests |
 | `response_buf` | `[u8; MAX_RESPONSE_SIZE]` | loop | IPC transmit buffer for operation responses |
 | `recv_buf` | `[u8; MAX_PAYLOAD_SIZE]` | loop | Scratch buffer passed to `dispatch_mctp_op` for message payload |

 ### Fault-isolation counters (polling mode, loop-scoped)

 | Name | Increments on | Logged when |
 |---|---|---|
 | `i2c_pkt` | Successful I2C frame decode | Every packet (at `debug` level) |
 | `i2c_recv_err` | `wait_for_messages` returns `Err` | 1st occurrence, then every 16th |
 | `decode_err` | `receiver.decode()` failure | 1st occurrence, then every 16th |
 | `inbound_err` | `server.inbound()` returns `Err` | 1st occurrence, then every 16th |
 | `spdm_ok` | `responder_process_message` returns `Ok` | Every success (at `info` level) |
 | `spdm_err` | `responder_process_message` returns `Err` | 1st occurrence, then every 256th (at `debug` level — mostly TimedOut noise) |

 ---

 ## Handle IDs (`app_mctp_server::handle`)

 Generated by `app_package` codegen from `system.json5`. The numeric values are
 target-specific and should not be hardcoded.

 | Handle | Used by | Purpose |
 |---|---|---|
 | `handle::I2C` | Both modes | IPC channel to `i2c_server` process |
 | `handle::MCTP` | Notification mode only | IPC channel handler for MCTP client connections |
 | `handle::WG` | Notification mode only | WaitGroup multiplexing IPC + I2C notification |
	# MCTP Server — Initialization and Variable Glossary

	Source: `services/mctp/server/src/main.rs`

	---

	## Build Modes

	The server compiles into one of two mutually exclusive modes, selected by Cargo
	feature flags set in the Bazel `rust_app` target.

	\| Feature flags \| Mode \| IPC served? \| SPDM in-process? \|
	\|---\|---\|---\|---\|
	\| _(none)_ \| Notification \| Yes \| No \|
	\| `i2c-polling` \| Polling \| No \| No \|
	\| `i2c-polling` + `direct-client` \| Polling + SPDM \| No \| Yes \|

	---

	## Initialization Sequence

	### Shared constants (always)

	```
	OWN_EID = 0x08 — MCTP Endpoint ID assigned to this device
	OWN_I2C_ADDR = 0x10 — I2C 7-bit slave address of this device
	```

	---

	### Polling mode (`i2c-polling`)

	Steps execute once at startup before the event loop begins.

	```
	1. IpcI2cClient::new(handle::I2C)
	→ Opens IPC channel to the I2C server (for configuration and rx).
	Stored in `i2c`.

	2. I2cAddress::new(OWN_I2C_ADDR)
	→ Validates the address value fits in 7 bits.
	Stored in `addr`.

	3. i2c.configure_target_address(BUS_2, addr)
	→ Programs the I2C hardware to respond to OWN_I2C_ADDR on bus 2.
	FATAL if this fails (I2C server unreachable or bad address).

	4. i2c.enable_receive(BUS_2)
	→ Arms the I2C slave receive FIFO. After this the hardware will
	accept incoming frames into the I2C server's buffer.
	FATAL if this fails.

	5. IpcI2cClient::new(handle::I2C) [second instance]
	→ A separate IPC channel to the I2C server, used exclusively for
	outbound I2C master writes. Ownership is transferred to I2cSender.

	6. I2cSender::new(i2c_client_2, BUS_2, OWN_I2C_ADDR)
	→ Outbound MCTP-over-I2C transport. Implements mctp_lib::Sender.
	Stored in `sender`.

	7. MctpI2cReceiver::new(OWN_I2C_ADDR)
	→ Inbound frame decoder. Strips I2C framing to produce raw MCTP
	packets. Stored in `receiver`.

	8a. (direct-client only) RefCell::new(Server::new(Eid(OWN_EID), 0, sender))
	→ MCTP router wrapped in RefCell for shared &self access.
	Stored in `server_cell`.

	8b. (no direct-client) Server::new(Eid(OWN_EID), 0, sender)
	→ MCTP router, exclusively owned.
	Stored in `server_plain`.

	── SPDM setup (direct-client only) ──────────────────────────────────────────

	9. DirectMctpClient::new(&server_cell)
	→ In-process MctpClient. Calls server_cell methods directly;
	no IPC channel to a separate process.
	Consumed immediately by step 10.

	10. MctpSpdmTransport::new_responder(client)
	→ SPDM transport layer in responder mode (listens for msg_type=0x05).
	Stored in `transport`.

	11. transport.init_sequence()
	→ Calls server.listener(0x05) in-process, reserving a listener handle
	in the router for SPDM messages.
	FATAL if the router's listener table is full (MAX_LISTENERS=8).

	12. MockCertStore / MockHash / MockRng / MockEvidence
	→ Placeholder platform implementations. No crypto hardware access.
	Stored in `cert_store`, `hash`, `m1_hash`, `l1_hash`, `rng`, `evidence`.

	13. CapabilityFlags { CERT_CAP, CHAL_CAP, MEAS_CAP=2, MEAS_FRESH_CAP, CHUNK_CAP }
	→ Bitmask of SPDM capabilities advertised to the requester.
	Stored in `flags`, then moved into `capabilities`.

	14. DeviceCapabilities { ct_exponent=0, data_transfer_size=1024,
	max_spdm_msg_size=4096 }
	→ SPDM device capability parameters. Stored in `capabilities`.

	15. SUPPORTED_VERSIONS = [V12, V13] (static)
	→ SPDM protocol versions this responder accepts.

	16. LocalDeviceAlgorithms { SHA-384, ECDSA-P384, DMTF measurements }
	→ Cryptographic algorithm selections. Stored in `algorithms`.

	17. SpdmContext::new(...)
	→ Constructs the full SPDM state machine. Takes references to all
	platform impls (transport, cert_store, hash, rng, evidence).
	FATAL if any required platform impl is misconfigured.
	Stored in `spdm_ctx`.

	18. [0u8; MAX_PAYLOAD_SIZE] + MessageBuf::new(&mut spdm_buf)
	→ Fixed-size scratch buffer for SPDM message encoding/decoding.
	msg_buf wraps spdm_buf for the lifetime of the loop.
	Both declared outside the loop to avoid borrow-checker conflict.
	```

	---

	### Notification mode (default, no `i2c-polling`)

	```
	1. IpcI2cClient::new(handle::I2C)
	→ IPC channel to I2C server for configuration, notifications, and
	pending-message retrieval. Stored in `i2c_notify`.

	2-4. Same address configuration as polling mode (steps 2-4 above).

	5. i2c_notify.register_notification(BUS_2, 0)
	→ Requests the I2C server to post a USER signal to this process
	when a slave-mode frame arrives. FATAL if it fails.

	6. IpcI2cClient::new(handle::I2C) [second instance]
	→ Separate channel for outbound sends, transferred to I2cSender.

	7-8. I2cSender and MctpI2cReceiver as in polling mode.

	9. Server::new(Eid(OWN_EID), 0, sender)
	→ MCTP router. Stored in `server`.

	10. [0u8; MAX_REQUEST_SIZE/MAX_RESPONSE_SIZE/MAX_PAYLOAD_SIZE]
	→ IPC wire buffers. Stored in `request_buf`, `response_buf`, `recv_buf`.

	11. syscall::wait_group_add(WG, MCTP, READABLE, user_data=0)
	→ Register the IPC channel as event source 0 in the WaitGroup.

	12. syscall::wait_group_add(WG, I2C, USER, user_data=1)
	→ Register the I2C notification signal as event source 1.
	```

	---

	## Variable Glossary

	### Constants

	\| Name \| Value \| Meaning \|
	\|---\|---\|---\|
	\| `OWN_EID` \| `0x08` \| MCTP Endpoint ID of this device \|
	\| `OWN_I2C_ADDR` \| `0x10` \| I2C 7-bit slave address of this device \|

	### Polling mode variables

	\| Name \| Type \| Lifetime \| Purpose \|
	\|---\|---\|---\|---\|
	\| `i2c` \| `IpcI2cClient` \| setup + loop \| I2C IPC channel for configuration, `wait_for_messages`, rx \|
	\| `addr` \| `I2cAddress` \| setup only \| Validated I2C address; consumed by `configure_target_address` \|
	\| `sender` \| `I2cSender` \| loop (via server) \| Outbound MCTP-over-I2C; owns a second `IpcI2cClient` \|
	\| `receiver` \| `MctpI2cReceiver` \| loop \| Decodes I2C slave frames into raw MCTP packets \|
	\| `server_cell` \| `RefCell<Server>` \| loop \| MCTP router; RefCell allows shared borrow with DirectMctpClient \|
	\| `server_plain` \| `Server` \| loop \| MCTP router when `direct-client` is not enabled \|
	\| `transport` \| `MctpSpdmTransport` \| loop (via spdm_ctx) \| SPDM transport; calls server_cell through DirectMctpClient \|
	\| `cert_store` \| `MockCertStore` \| loop (via spdm_ctx) \| Provides certificate chain to SPDM protocol \|
	\| `hash` \| `MockHash` \| loop (via spdm_ctx) \| Main transcript hash \|
	\| `m1_hash` \| `MockHash` \| loop (via spdm_ctx) \| M1 measurement hash (measurements with signature) \|
	\| `l1_hash` \| `MockHash` \| loop (via spdm_ctx) \| L1 challenge hash \|
	\| `rng` \| `MockRng` \| loop (via spdm_ctx) \| Random number source (nonces, challenge data) \|
	\| `evidence` \| `MockEvidence` \| loop (via spdm_ctx) \| Device measurement evidence provider \|
	\| `flags` \| `CapabilityFlags` \| setup only \| SPDM capability bitmask; consumed by `capabilities` \|
	\| `capabilities` \| `DeviceCapabilities` \| setup only \| SPDM capability parameters; consumed by `SpdmContext::new` \|
	\| `SUPPORTED_VERSIONS` \| `[SpdmVersion; 2]` \| `'static` \| SPDM versions [V1.2, V1.3]; must be static due to spdm-lib lifetime \|
	\| `algorithms` \| `LocalDeviceAlgorithms` \| setup only \| Algorithm selections; consumed by `SpdmContext::new` \|
	\| `spdm_ctx` \| `SpdmContext` \| loop \| Full SPDM state machine; processes one request per `process_message` call \|
	\| `spdm_buf` \| `[u8; MAX_PAYLOAD_SIZE]` \| loop \| Raw byte storage for SPDM message encoding \|
	\| `msg_buf` \| `MessageBuf` \| loop \| Cursor over `spdm_buf`; reset each iteration via `msg_buf.reset()` \|

	### Notification mode variables

	\| Name \| Type \| Lifetime \| Purpose \|
	\|---\|---\|---\|---\|
	\| `i2c_notify` \| `IpcI2cClient` \| loop \| I2C channel for slave config, notification registration, and `get_pending_messages` \|
	\| `addr` \| `I2cAddress` \| setup only \| Validated I2C address \|
	\| `sender` \| `I2cSender` \| loop (via server) \| Outbound MCTP-over-I2C \|
	\| `receiver` \| `MctpI2cReceiver` \| loop \| Decodes I2C slave frames \|
	\| `server` \| `Server` \| loop \| MCTP router \|
	\| `request_buf` \| `[u8; MAX_REQUEST_SIZE]` \| loop \| IPC receive buffer for inbound MCTP operation requests \|
	\| `response_buf` \| `[u8; MAX_RESPONSE_SIZE]` \| loop \| IPC transmit buffer for operation responses \|
	\| `recv_buf` \| `[u8; MAX_PAYLOAD_SIZE]` \| loop \| Scratch buffer passed to `dispatch_mctp_op` for message payload \|

	### Fault-isolation counters (polling mode, loop-scoped)

	\| Name \| Increments on \| Logged when \|
	\|---\|---\|---\|
	\| `i2c_pkt` \| Successful I2C frame decode \| Every packet (at `debug` level) \|
	\| `i2c_recv_err` \| `wait_for_messages` returns `Err` \| 1st occurrence, then every 16th \|
	\| `decode_err` \| `receiver.decode()` failure \| 1st occurrence, then every 16th \|
	\| `inbound_err` \| `server.inbound()` returns `Err` \| 1st occurrence, then every 16th \|
	\| `spdm_ok` \| `responder_process_message` returns `Ok` \| Every success (at `info` level) \|
	\| `spdm_err` \| `responder_process_message` returns `Err` \| 1st occurrence, then every 256th (at `debug` level — mostly TimedOut noise) \|

	---

	## Handle IDs (`app_mctp_server::handle`)

	Generated by `app_package` codegen from `system.json5`. The numeric values are
	target-specific and should not be hardcoded.

	\| Handle \| Used by \| Purpose \|
	\|---\|---\|---\|
	\| `handle::I2C` \| Both modes \| IPC channel to `i2c_server` process \|
	\| `handle::MCTP` \| Notification mode only \| IPC channel handler for MCTP client connections \|
	\| `handle::WG` \| Notification mode only \| WaitGroup multiplexing IPC + I2C notification \|