Module Reference

Software for control of the CESNET NDK based FPGA acceleration cards

class nfb.BaseComp(dev='/dev/nfb0', node: Node | None = None, index: int = 0)[source]

BaseComp represents common parent for all classes that manages HW components

Derived class should set it’s own DT_COMPATIBLE!

Variables:
nfb.open(str path: str = '0') Nfb

Open a handle to NFB device in system

Parameters:

path – Path to device node, default leads to /dev/nfb0

Returns:

The libnfb.Nfb object, enhanced by eth.EthManager

nfb.libnfb

class libnfb.AbstractBaseComp(dev=Nfb.default_device, node: fdt.Node | None = None, index: int = 0)

AbstractBaseComp represents common parent for all classes that manages HW components

Derived class should set it’s own DT_COMPATIBLE!

Variables:
class libnfb.Comp

Comp class instance represents component handle inside NFB device.

clr_bit(self, addr, bit, width=32)

Clear bit in component register

The register is first readen and if the value of requested bit differs, the new value is written into register as a whole word of specified width.

Parameters:
  • addr – Address of the register in component space

  • bit – Bit number in register

  • width – The bit width of accessed register; supported values are 8, 16, 32, 64

get_bit(self, addr, bit, width=32)

Get value of bit in component register

Parameters:
  • addr – Address of the register in component space

  • bit – Bit number in register

  • width – The bit width of accessed register; supported values are 8, 16, 32, 64

read(self, addr: int, count: int)

Read data from component register

Parameters:
  • addr – Address of the register in component space

  • count – Number of bytes to read

read16(self, addr: int)
read32(self, addr: int)
read64(self, addr: int)
read8(self, addr: int)

Read integer value from component register, use 8 bit access (1 byte)

Parameters:

addr – Address of the register in component space

Returns:

Readen unsigned integer value

set_bit(self, addr, bit, value=True, width=32)

Set bit in component register

The register is first readen and if the value of requested bit differs, the new value is written into register as a whole word of specified width.

Parameters:
  • addr – Address of the register in component space

  • bit – Bit number in register

  • value – Set or clear bit

  • width – The bit width of accessed register; supported values are 8, 16, 32, 64

wait_for_bit(self, addr, bit, timeout=5.0, delay=0.01, level=True, width=32)

Wait for bit in comenent register

Parameters:
  • addr – Address of the register in component space

  • bit – Bit number in register

  • timeout – Timeout after which will be the waiting terminated

  • delay – Delay between each ask (ask = read of a given register)

  • level – For what bit level is function waiting

  • width – The bit width of accessed register; supported values are 8, 16, 32, 64

Returns:

True if bit was set in time, else False

write(self, addr: int, bytes data: bytes)

Write data to component register

Parameters:
  • addr – Address of the register in component space

  • data – Data bytes to be written

write16(self, addr: int, data: int)
write32(self, addr: int, data: int)
write64(self, addr: int, data: int)
write8(self, addr: int, data: int)

Write integer value to component register, use 8 bit access (1 byte)

Parameters:
  • addr – Address of the register in component space

  • data – Unsigned integer value to be written

class libnfb.NdpQueue(Nfb nfb: Nfb, node, index: int)

Object representing a NDP queue

start(self)

Start the queue and prepare for transceiving

stats_read(self)
stats_reset(self)
stop(self)

Stop the queue

class libnfb.NdpQueueRx(Nfb nfb: Nfb, node, index)

Object representing a queue for receiving data from NDP

is_accessible(self)

Check if the control registers are accessible

is_available(self)

Check if the queue can transfer data

recv(self, cnt: int = -1, timeout=0) List[bytes]

Receive packets

Try to receive packets from the queue.

With default parameter values receive all currently pending packets and return.

Parameters:
  • cnt – Maximum number of packets to read. cnt == -1 means unlimited packet count (timeout must be used).

  • timeout – Maximum time in secs to wait for packets. timeout == None means unlimited time (cnt must be used).

Returns:

list of packets; packet is represented by bytes

recvmsg(self, cnt: int = -1, timeout=0) List[Tuple[bytes, bytes, int]]

Receive messages

Try to receive messages from the queue.

With default parameter values receive all currently pending mesages and return.

Parameters:
  • cnt – Maximum number of messages to read. cnt == -1 means unlimited message count (timeout must be used).

  • timeout – Maximum time in secs to wait for messages. timeout == None means unlimited time (cnt must be used).

Returns:

list of messages; message is represented by tuple of (packet, packet_header, flags)

stats_read(self) dict

Read statistic counters

Returns:

Dictionary with counters values: ‘received’, ‘received_bytes’, ‘discarded’, ‘discarded_bytes’.

stats_reset(self)

Reset statistic counters

class libnfb.NdpQueueTx(Nfb nfb: Nfb, node, index)

Object representing a queue for transmitting data over NDP

flush(self)

Flush the prepared packet/messages

is_accessible(self)

Check if the control registers are accessible

is_available(self)

Check if the queue can transfer data

send(self, pkts: Union[bytes, List[bytes]], hdrs: Optional[Union[bytes, List[bytes]]] = None, flags: Optional[Union[int, List[int]]] = None, bool flush: bool = True) None

Send a packet or burst of packets

Parameters:
  • pkts – Packets represented by list of data bytes or a single packet

  • hdrs – Packet headers represented by data bytes or a single packet header, which will be used for all packets

  • flags – Metadata represented by list of integers or a single integer, which will be used for all packets; value meaning is TBD; specific for particular NDP type

  • flush – Send data immediatelly (default is True)

sendmsg(self, pkts: List[Tuple[bytes, bytes, int]], bool flush: bool = True) None

Send burst of messages

Parameters:
  • pkts – List of messages represented by tuple: (packet data, header data, flags)

  • flush – Send data immediatelly

stats_read(self)

Read statistic counters

Returns:

Dictionary with counters values: ‘sent’, ‘sent_bytes’.

stats_reset(self)

Reset statistic counters

class libnfb.Nfb(str path: str)

Nfb class instance represents handle to NFB device in system

It allows to create Comp object instance for access to the component registers inside the NFB device. It also allows to access to the object representation of the Flattened Device Tree by the fdt attribute and some helper functions.

Variables:
comp_open(self, comp: Union[str, fdt.items.Node], int index: cython.int = 0) Comp

Create component handle from a component instance inside the NFB

Parameters:
  • comp – Exact node representing the component from the Nfb.fdt or compatible string, which will be searched and matched in properties of Nfb.fdt nodes

  • index – Index of component with matching compatible string

Returns:

Component object handle

fdt_get_compatible(self, str compatible: str) List[fdt.items.Node]

Get list of all Nfb.fdt nodes for specific compatible string

Parameters:

compatible – Compatible string, which will be searched and matched in properties of Nfb.fdt nodes

Returns:

List of matched fdt nodes

fdt_get_phandle(self, phandle: int) fdt.items.Node | None

Get the Nfb.fdt node with equal phandle property value as requested

Parameters:

phandle – phandle number

Returns:

Matched fdt node

class libnfb.QueueManager(nfb)
Variables:
flush(self, i=None)

Flush the prepared packets/messages on multiple queues

See NdpQueueTx.flush()

Parameters:

i – list of queue indexes

recv(self, cnt: int = -1, timeout=0, i: int | List[int] | None = None)

Receive packets from multiple queues

See NdpQueueRx.recv()

Parameters:

i – list of queue indexes

recvmsg(self, cnt: int = -1, timeout=0, i: int | List[int] | None = None)

Receive messages from multiple queues

See NdpQueueRx.recvmsg()

Parameters:

i – list of queue indexes

send(self, pkts: Union[bytes, List[bytes]], hdrs: Optional[Union[bytes, List[bytes]]] = None, flags: Optional[Union[int, List[int]]] = None, bool flush: bool = True, i: Optional[Union[int, List[int]]] = None) None

Send burst of packets to multiple queues

See NdpQueueTx.send()

Parameters:

i – list of queue indexes

sendmsg(self, pkts: List[Tuple[bytes, bytes, int]], bool flush: bool = True, i: Optional[Union[int, List[int]]] = None) None

Send burst of messages to multiple queues

See NdpQueueTx.sendmsg()

Parameters:

i – list of queue indexes

start(self, i: int | List[int] | None = None)

Start all Rx and Tx queues

See NdpQueue.start()

Parameters:

i – list of queue indexes

stop(self, i: int | List[int] | None = None)

Stop all Rx and Tx queues

See NdpQueue.stop()

Parameters:

i – list of queue indexes

libnfb.open(str path: str = '0') Nfb

Open a handle to NFB device in system

Parameters:

path – Path to device node, default leads to /dev/nfb0

Returns:

The libnfb.Nfb object, enhanced by eth.EthManager

nfb.libnetcope

class libnetcope.DmaCtrlNdp(Nfb nfb, node)
desc0(self, dma_addr_t phys: dma_addr_t) int
desc2(self, dma_addr_t phys: dma_addr_t, length: int, meta: int = 0, bool next: bool = False, hdr_length: int = 0) int
flush_sdp(self)
flush_sp(self)
read_stats(self)
start(self, dma_addr_t desc_buffer: dma_addr_t, dma_addr_t hdr_buffer: dma_addr_t, dma_addr_t update_buffer: dma_addr_t, update_buffer_p: memoryview, uint32_t nb_desc: uint32_t, uint32_t nb_hdr: uint32_t)
stop(self, force=False)
update_hdp(self)
update_hhp(self)
class libnetcope.I2c(Nfb nfb, node, addr=0xA0)
read_reg(self, reg, size)
write_reg(self, reg: int, bytes data: bytes)
class libnetcope.Mdio(Nfb nfb, node, param_node=None)
read(self, devad: int, reg: int, prtad: int = 0)
write(self, devad: int, reg: int, val: int, prtad: int = 0)
class libnetcope.RxMac(Nfb nfb, node)
disable(self)
enable(self, bool enable: bool = True)
is_enabled(self)
stats_read(self, bool etherstats: bool = False)

Read statistic counters

Parameters:

etherstats – Request statistic values defined by RFC 2819

Returns:

A dictionary with counters values

stats_reset(self)

Reset statistic counters

class libnetcope.TxMac(Nfb nfb, node)
disable(self)
enable(self, bool enable: bool = True)
is_enabled(self)
stats_read(self)

Read statistic counters

Returns:

A dictionary with counters values

stats_reset(self)

Reset statistic counters

nfb.eth

class nfb.eth.Eth(nfb, node)[source]

Object representing one Ethernet interface

Variables:
class nfb.eth.EthManager(nfb)[source]

Object which encapsulates all Ethernet interfaces into nfb

class nfb.eth.PcsPma(nfb, node)[source]

Object representing a PCS/PMA configuration registers

Variables:
  • mdio (libnetcope.Mdio) – MDIO bus handle

  • mdio_portad (int) – Port address of PCS/PMA on MDIO bus

property pma_local_loopback

Get or set loopback on local side of PMA module

class nfb.eth.Transceiver(nfb, node)[source]

Object representing a transciever interface

Variables:

i2c (I2c) – I2c bus handle (only with QSFP+ modules)

property vendor_name: str

vendor of the transceiver

property vendor_pn: str

product number of the transceiver

property vendor_sn: str

serial number of the transceiver