NAI Documentation

NAI Ethernet Protocol Reference

9 min read

About This Reference

This page documents the byte-level layout of every command and response in the NAI Ethernet Protocol. It’s the authoritative source for what goes on the wire.

If you’re new to the protocol, start with NAI Ethernet Protocol Overview — it explains what each command category is for and when to reach for it. If you’re writing C code that sends or receives these messages, see NAI Ethernet Protocol APIs — most of this byte layout is built and decoded for you by the SSK.

Note

The protocol described here is shared across current Gen 5 and Gen 6 NAI motherboards. Gen 6 adds a small set of additional command variants — see Gen 6 Extensions at the bottom of this page.

Common Fields

Every command and response is wrapped in this envelope:

FieldDescription
PreambleAlways 0xD30F. Marks start of frame.
SequenceNoPairs a response with the originating command.
TypeCodeIdentifies command or response type.
LengthTotal bytes in the frame (Preamble through Postamble).
PayloadCommand- or response-specific data.
PostambleAlways 0xF03D. Marks end of frame.

All multibyte fields are big-endian.

Flags

Most register-style commands take a 2-byte Flags field:

  • Bit 0 — Onboard / Off-board addressing: 0 = onboard, 1 = off-board.
  • Bit 1 — Use SERDES blocks if supported: 0 = do not use, 1 = use. Some module firmware does not advertise SERDES block capability correctly; this bit lets you override.
  • Bit 4 — Register size: 0 = 32-bit, 1 = 16-bit.

SequenceNo for Unsolicited Responses

TDR and IDR responses are unsolicited — the board generates the SequenceNo so the host can identify the originating TDR or IDR.

TDR:  SequenceNo = 0x8000 | (TDRIndex << 10) | (CommandIndex << 6)
IDR:  SequenceNo = 0xC000 | (IDRIndex << 10) | (CommandIndex << 6)

Bit assignments:

  • Bit 15 — IDR response.
  • Bit 14 — TDR response.
  • Bits 13–10 — TDR/IDR index (Id − 1).
  • Bits 9–6 — command index (CommandId − 1).
  • Bits 5–0 — reserved.

Register Commands

ReadRegs and WriteRegs operate on one or more registers using a starting address, a count, and a stride.

Fields:

  • Flags (2 bytes) — see Common Fields.
  • Register Address (4 bytes) — starting register address.
  • Count (2 bytes) — number of registers to read or write. With the 16-bit flag set, Count means 16-bit words; with the 32-bit flag set, 32-bit words.
  • Stride (2 bytes) — bytes to advance the address per access. Must be a multiple of the register size. Stride 0 reads or writes the same address Count times (useful for FIFOs). Stride equal to the register size walks the addresses contiguously.

MaskValueReg

NameValue
TypeCode0x1005
Length (bytes)16+(8 OR 4)
FlagsXX
Register AddressXXXX
ValueXXXX or XX
MaskXXXX OR XX
Postamble0xF03D

MaskValueReg Response

NameValue
Preamble0xD30F
SequenceNoXX
TypeCode0x9005
Length (bytes)10
Postamble0xF03D

Block Commands

A Block is a saved list of register addresses that can be read or written in one round trip. All registers in a block share the same flags.

A block definition consists of:

  • BlockId (2 bytes).
  • Flags (2 bytes) — same definition as ReadRegs/WriteRegs. Bit 0 controls onboard/off-board, Bit 4 controls register size.
  • Register Count (2 bytes).
  • Register Addresses — (Register Count × 4) bytes.

Block commands don’t support mixed onboard / off-board addressing or mixed register sizes within a single block — use ZBlocks for that.

SetBlockConfig Command

NameValue
Preamble0xD30F
SequenceNoXX
TypeCode0x1010
Length (bytes)16+(RegisterCount*4)
BlockId1→16
FlagsXX
Register Count1→MaxRegister allowed in Block
Register AddressesXX…XX
Postamble0xF03D

SetBlockConfig Response

NameValue
Preamble0xD30F
SequenceNoXX
TypeCode0x9010
Length (bytes)10
Postamble0xF03D

GetBlockConfig Command

NameValue
Preamble0xD30F
SequenceNoXX
TypeCode0x1011
Length (bytes)12
BlockId1→16
Postamble0xF03D

GetBlockConfig Response

NameValue
Preamble0xD30F
SequenceNoXX
TypeCode0x9011
Length (bytes)14+(RegisterCount*4)
FlagsXX
Register Count1→MaxRegister allowed in Block
Register AddressesXX…XX
Postamble0xF03D

ClearBlockConfig Command

NameValue
Preamble0xD30F
SequenceNoXX
TypeCode0x1012
Length (bytes)12
BlockId1→16
Postamble0xF03D

ClearBlockConfig Response

NameValue
Preamble0xD30F
SequenceNoXX
TypeCode0x9012
Length (bytes)10
Postamble0xF03D

ReadBlock Command

NameValue
Preamble0xD30F
SequenceNoXX
TypeCode0x1013
Length (bytes)12
BlockId1→16
Postamble0xF03D

ReadBlock Response

NameValue
Preamble0xD30F
SequenceNoXX
TypeCode0x9013
Length (bytes)10 + (RegisterCount4 OR RegisterCount2)
PayloadXX…XX
Postamble0xF03D

WriteBlock Command

NameValue
Preamble0xD30F
SequenceNoXX
TypeCode0x1014
Length (bytes)12+(RegisterCount4 OR RegisterCount2)
BlockId1→16
Register Value(s)XXXX … XXXX
Postamble0xF03D

WriteBlock Response

NameValue
Preamble0xD30F
SequenceNoXX
TypeCode0x9014
Length (bytes)10
Postamble0xF03D

ZBlock Commands

A ZBlock is like a Block but each register address carries its own per-address flags, so onboard and off-board addresses can be mixed in the same ZBlock. The register-size flag still has to be consistent.

A ZBlock definition consists of:

  • ZBlockId (2 bytes).
  • Flags (2 bytes) — only Bit 4 applies at this level (register size).
  • Register Count (2 bytes).
  • Register Address Flags — (Register Count × 2) bytes. Each per-address flag’s Bit 0 controls onboard vs. off-board for that address.
  • Register Addresses — (Register Count × 4) bytes.

SetZBlockConfig Command

NameValue
Preamble0xD30F
SequenceNoXX
TypeCode0x1050
Length (bytes)16+(RegisterCount*6)
ZBlockId1→16
FlagsXX
Register Count1→MaxRegister allowed in ZBlock
Register Address FlagsXX…XX
Register AddressesXX…XX
Postamble0xF03D

SetZBlockConfig Response

NameValue
Preamble0xD30F
SequenceNoXX
TypeCode0x9050
Length (bytes)10
Postamble0xF03D

GetZBlockConfig Command

NameValue
Preamble0xD30F
SequenceNoXX
TypeCode0x1051
Length (bytes)12
ZBlockId1→16
Postamble0xF03D

GetZBlockConfig Response

NameValue
Preamble0xD30F
SequenceNoXX
TypeCode0x9051
Length (bytes)14+(RegisterCount*6)
FlagsXX
Register Count1→MaxRegister allowed in ZBlock
Register Address FlagsXX…XX
Register AddressesXX…XX
Postamble0xF03D

ClearZBlockConfig Command

NameValue
Preamble0xD30F
SequenceNoXX
TypeCode0x1052
Length (bytes)12
ZBlockId1→16
Postamble0xF03D

ClearZBlockConfig Response

NameValue
Preamble0xD30F
SequenceNoXX
TypeCode0x9052
Length (bytes)10
Postamble0xF03D

ReadZBlock Command

NameValue
Preamble0xD30F
SequenceNoXX
TypeCode0x1053
Length (bytes)12
ZBlockId1→16
Postamble0xF03D

ReadZBlock Response

NameValue
Preamble0xD30F
SequenceNoXX
TypeCode0x9053
Length (bytes)10 + (RegisterCount4 OR RegisterCount2)
PayloadXX…XX
Postamble0xF03D

WriteZBlock Command

NameValue
Preamble0xD30F
SequenceNoXX
TypeCode0x1054
Length (bytes)12+(RegisterCount4 OR RegisterCount2)
ZBlockId1→16
Register Value(s)XXXX … XXXX
Postamble0xF03D

WriteZBlock Response

NameValue
Preamble0xD30F
SequenceNoXX
TypeCode0x9054
Length (bytes)10
Postamble0xF03D

Timer Driven Response (TDR) Commands

TDRs execute a list of commands on a fixed timer. Up to 16 TDRs can be defined, each with up to 4 commands.

A TDR definition consists of:

  • TDR Id (2 bytes) — 1 to 16.
  • Response Protocol (2 bytes) — 0 = TCP, 1 = UDP.
  • Response IP Address Length (2 bytes) — 4 for IPv4, 16 for IPv6.
  • Response Address (4 or 16 bytes) — destination IP for responses.
  • Response Port (2 bytes) — destination port for responses.
  • Period (2 bytes) — milliseconds, 40 to 65535.
  • Command Count (2 bytes).
  • Commands — each a full ReadRegs, WriteRegs, ReadBlock, or WriteBlock frame including its own header and trailer.

SetTDRConfig Command

NameValue
Preamble0xD30F
SequenceNoXX
TypeCode0x1020
Length (bytes)22+(4 OR 16) + Commands
TDR Id1→16
Response Protocol0-TCP OR 1-UDP
Response IPAddressLength4-IPv4 OR 16-IPv6
Response IPAddressXX…XX
Response PortXX
Period (ms)40→65535
CommandCount1→4
Command 1XX…XX
Command 2XX…XX
…XX…XX
Command NXX…XX
Postamble0xF03D

SetTDRConfig Response

NameValue
Preamble0xD30F
SequenceNoXX
TypeCode0x9020
Length (bytes)10
Postamble0xF03D

GetTDRConfig Command

NameValue
Preamble0xD30F
SequenceNoXX
TypeCode0x1021
Length (bytes)12
TDR Id1→16
Postamble0xF03D

GetTDRConfig Response

NameValue
Preamble0xD30F
SequenceNoXX
TypeCode0x9021
Length (bytes)20+(4 OR 16) + Commands
Response Protocol0-TCP OR 1-UDP
Response IPAddressLength4-IPv4 OR 16-IPv6
Response IPAddressXX…XX
Response PortXX
Period (ms)40→65535
CommandCount1→4
Command 1XX…XX
Command 2XX…XX
…XX…XX
Command NXX…XX
Postamble0xF03D

ClearTDRConfig Command

NameValue
Preamble0xD30F
SequenceNoXX
TypeCode0x1022
Length (bytes)12
TDR Id1→16
Postamble0xF03D

ClearTDRConfig Response

NameValue
Preamble0xD30F
SequenceNoXX
TypeCode0x9022
Length (bytes)10
Postamble0xF03D

StartTDR Command

NameValue
Preamble0xD30F
SequenceNoXX
TypeCode0x1023
Length (bytes)12
TDR Id1→16
Postamble0xF03D

StartTDR Response

NameValue
Preamble0xD30F
SequenceNoXX
TypeCode0x9023
Length (bytes)10
Postamble0xF03D

StopTDR Command

NameValue
Preamble0xD30F
SequenceNoXX
TypeCode0x1024
Length (bytes)12
TDR Id1→16
Postamble0xF03D

StopTDR Response

NameValue
Preamble0xD30F
SequenceNoXX
TypeCode0x9024
Length (bytes)10
Postamble0xF03D

Interrupt Driven Response (IDR) Commands

IDRs execute a list of commands when an interrupt vector fires. Up to 16 IDRs can be defined, each with up to 4 commands.

An IDR definition consists of:

  • IDR Id (2 bytes) — 1 to 16.
  • Response Protocol (2 bytes) — 0 = TCP, 1 = UDP.
  • Response IP Address Length (2 bytes) — 4 for IPv4, 16 for IPv6.
  • Response Address (4 or 16 bytes) — destination IP for responses.
  • Response Port (2 bytes) — destination port for responses.
  • Vector (4 bytes) — 0x00000000 to 0xFFFFFFFF.
  • Command Count (2 bytes).
  • Commands — each a full ReadRegs, WriteRegs, ReadBlock, or WriteBlock frame including its own header and trailer.

SetIDRConfig Command

NameValue
Preamble0xD30F
SequenceNoXX
TypeCode0x1030
Length (bytes)24+(4 OR 16) + Commands
IDR Id1→16
Response Protocol0-TCP OR 1-UDP
Response IPAddressLength4-IPv4 OR 16-IPv6
Response IPAddressXX…XX
Response PortXX
VectorXXXX
CommandCount1→4
Command 1XX…XX
Command 2XX…XX
…XX…XX
Command NXX…XX
Postamble0xF03D

SetIDRConfig Response

NameValue
Preamble0xD30F
SequenceNoXX
TypeCode0x9030
Length (bytes)10
Postamble0xF03D

GetIDRConfig Command

NameValue
Preamble0xD30F
SequenceNoXX
TypeCode0x1031
Length (bytes)12
IDR Id1→16
Postamble0xF03D

GetIDRConfig Response

NameValue
Preamble0xD30F
SequenceNoXX
TypeCode0x9031
Length (bytes)22+(4 OR 16) + Commands
Response Protocol0-TCP OR 1-UDP
Response IPAddressLength4-IPv4 OR 16-IPv6
Response IPAddressXX…XX
Response PortXX
VectorXXXX
CommandCount1→4
Command 1XX…XX
Command 2XX…XX
…XX…XX
Command NXX…XX
Postamble0xF03D

ClearIDRConfig Command

NameValue
Preamble0xD30F
SequenceNoXX
TypeCode0x1032
Length (bytes)12
IDR Id1→16
Postamble0xF03D

ClearIDRConfig Response

NameValue
Preamble0xD30F
SequenceNoXX
TypeCode0x9032
Length (bytes)10
Postamble0xF03D

EnableIDR Command

NameValue
Preamble0xD30F
SequenceNoXX
TypeCode0x1033
Length (bytes)12
IDR Id1→16
Postamble0xF03D

EnableIDR Response

NameValue
Preamble0xD30F
SequenceNoXX
TypeCode0x9033
Length (bytes)10
Postamble0xF03D

DisableIDR Command

NameValue
Preamble0xD30F
SequenceNoXX
TypeCode0x1034
Length (bytes)12
IDR Id1→16
Postamble0xF03D

DisableIDR Response

NameValue
Preamble0xD30F
SequenceNoXX
TypeCode0x9034
Length (bytes)10
Postamble0xF03D

Scripting Commands

Scripts are command sequences stored in the listener’s memory. Up to 16 scripts can be defined, each containing up to 100 commands (subject to a 1500-byte total message limit). Scripts live for the lifetime of the listener process — they are not persisted across resets.

When a script is executed, its commands run serially and each produces its own response, just as if the commands had been sent individually.

Currently scriptable commands: NOP, ReadRegs, WriteRegs, ReadFIFO, MaskReg, MaskValueReg.

A single script can be designated as the SafeState script with SetSafeStateScriptId. The board executes it automatically when SafeState criteria are met (for example, an EtherOpMode communication timeout). Setting a value of 0 clears the SafeState script.

ClearScript Command

NameValue
Preamble0xD30F
SequenceNoXX
TypeCode0x1040
Length12
ScriptId1→16
Postamble0xF03D

ClearScript Response

NameValue
Preamble0xD30F
SequenceNoXX
TypeCode0x9040
Length10
Postamble0xF03D

WriteScript Command

NameValue
Preamble0xD30F
SequenceNoXX
TypeCode0x1041
Length14 + Commands
ScriptId1→16
CommandCount1→100
Command 1XX…XX
Command 2XX…XX
…XX…XX
Command NXX…XX
Postamble0xF03D

WriteScript Response

NameValue
Preamble0xD30F
SequenceNoXX
TypeCode0x9041
Length10
Postamble0xF03D

ReadScript Command

NameValue
Preamble0xD30F
SequenceNoXX
TypeCode0x1042
Length12
ScriptId1→16
Postamble0xF03D

ReadScript Response

NameValue
Preamble0xD30F
SequenceNoXX
TypeCode0x9042
Length12 + Commands
CommandCount1→100
Command 1XX…XX
Command 2XX…XX
…XX…XX
Command NXX…XX
Postamble0xF03D

ExecuteScript Command

NameValue
Preamble0xD30F
SequenceNoXX
TypeCode0x1043
Length12
ScriptId1→16
Postamble0xF03D

ExecuteScript Response

NameValue
Preamble0xD30F
SequenceNoXX
TypeCode0x9043
Length10
Postamble0xF03D

SetSafeStateScriptId Command

NameValue
Preamble0xD30F
SequenceNoXX
TypeCode0x1044
Length12
ScriptId1→16
Postamble0xF03D

SetSafeStateScriptId Response

NameValue
Preamble0xD30F
SequenceNoXX
TypeCode0x9044
Length10
Postamble0xF03D

GetSafeStateScriptId Command

NameValue
Preamble0xD30F
SequenceNoXX
TypeCode0x1045
Length10
Postamble0xF03D

GetSafeStateScriptId Response

NameValue
Preamble0xD30F
SequenceNoXX
TypeCode0x9045
Length12
ScriptId1→16
Postamble0xF03D

I2C Raw Commands

ReadI2CRaw and WriteI2CRaw forward raw I2C transactions to a device on the board.

An I2C Raw Data definition consists of:

  • Response Data Length (2 bytes) — bytes returned by the command.
  • I2C Command Data Length (2 bytes) — bytes in the I2C read command.
  • I2C Command — the I2C address (command).
  • I2C Command Data — data sent with the I2C read command.

I2C_RawRead Command

NameValue
Preamble0xD30F
SequenceNoXX
TypeCode0x1200
Length (bytes)14 + I2C Command data Length
Response Data LengthSize of data returned (in Bytes)
I2C Command data LengthSize of data in I2C command
I2C CommandI2C Address
I2C Command dataXXXX … XXXX
Postamble0xF03D

I2C_RawRead Response

NameValue
Preamble0xD30F
SequenceNoXX
TypeCode0x9200
Length (bytes)10 + Response Data Length
PayloadXX…XX
Postamble0xF03D

I2C_RawWrite Command

NameValue
Preamble0xD30F
SequenceNoXX
TypeCode0x1201
Length (bytes)11 + Register Count
I2C CommandI2C Address
Register Value(s)XXXX … XXXX
Postamble0xF03D

I2C_RawWrite Response

NameValue
Preamble0xD30F
SequenceNoXX
TypeCode0x9201
Length (bytes)10
Postamble0xF03D

System Configuration Commands

Intended for factory test only; may not be available on every platform.

Get System Configuration returns PCI/VME data for installed cards:

  • Card Number (4 bytes, int32_t).
  • Base Address (4 bytes, uint32_t).
  • Size (4 bytes, uint32_t).
  • Lane (2 bytes, uint16_t) — PCIe lane.
  • Bus (2 bytes, uint16_t) — PCI bus.
  • Dev (2 bytes, uint16_t) — PCI device.
  • Func (2 bytes, uint16_t) — PCI function.
  • DevId (2 bytes, uint16_t) — card PCI device ID.

Get System Configuration Command

NameValue
Preamble0xD30F
SequenceNoXX
TypeCode0x1210
Length (bytes)10 + 2
Number of cardsNumber of cards to return data for (1 - NAI_MAX_CARDS)
Postamble0xF03D

System Configuration Response

NameValue
Preamble0xD30F
SequenceNoXX
TypeCode0x9210
Length (bytes)10 + (Number of Cards * 22)
PayloadSystem configuration data
Postamble0xF03D

Error Responses

Error responses carry a TypeCode in the range 0x8000–0x8FFF. The payload is an ASCII message describing the failure — not null-terminated. Its size is Length − 10.

Error Response Packet

NameValue
Preamble0xD30F
SequenceNoXX
TypeCode0x8000 → 0x8FFF
Length (bytes)X
MessageXX…XX
Postamble0xF03D

Example Error

An example string that might appear in the Message field is “ReadRegs – wrong number of bytes in payload”. This would arrive with error code 0x8006 — Invalid Payload Size.

NameValue
Preamble0xD30F
SequenceNoXX
TypeCode0x8006
Length (bytes)0x35
Message5265616452656773202d2077726f6e67206e756d626572206f6620627974657320696e207061796c6f6164
Postamble0xF03D

Gen 6 Extensions

Gen 6 boards extend the protocol with additional command variants. These are defined in the SSK 2.x header naiether_typecode.h and include extended IDR (IDR3, IDR3_IPv6), block (BANK3, MREG3, FIFO3), and IPv6 variants of several existing commands.

For the current Gen 6-specific byte layouts, refer to naiether_typecode.h and the SSK 2.x source. The conceptual model is the same as the corresponding Gen 5 command in each case.

NAI Docs Assistant
Was this document helpful?