From ff18374c529fd029262714957096e93100b732aa Mon Sep 17 00:00:00 2001 From: Florent Kermarrec Date: Fri, 28 Jul 2023 09:15:52 +0200 Subject: [PATCH] interconnect/axi/axi_common: Document helper functions. --- litex/soc/interconnect/axi/axi_common.py | 57 +++++++++++++++++++++++- 1 file changed, 55 insertions(+), 2 deletions(-) diff --git a/litex/soc/interconnect/axi/axi_common.py b/litex/soc/interconnect/axi/axi_common.py index 41b666436..f050b1c7d 100644 --- a/litex/soc/interconnect/axi/axi_common.py +++ b/litex/soc/interconnect/axi/axi_common.py @@ -1,7 +1,7 @@ # # This file is part of LiteX. # -# Copyright (c) 2018-2022 Florent Kermarrec +# Copyright (c) 2018-2023 Florent Kermarrec # Copyright (c) 2020 Antmicro # SPDX-License-Identifier: BSD-2-Clause @@ -42,6 +42,21 @@ AXSIZE = { # AXI Connection Helpers --------------------------------------------------------------------------- def connect_axi(master, slave, keep=None, omit=None): + """ + Connect AXI master to slave channels. + + This function connects the AXI channels from the master and slave taking into account their + respective roles for each channel type. + + Parameters: + master : AXI master interface. + slave : AXI slave interface. + keep : Optional parameter to keep some signals while connecting. + omit : Optional parameter to omit some signals while connecting. + + Returns: + list: List of statements to create the necessary connections. + """ channel_modes = { "aw": "master", "w" : "master", @@ -59,6 +74,21 @@ def connect_axi(master, slave, keep=None, omit=None): return r def connect_to_pads(bus, pads, mode="master", axi_full=False): + """ + Connect to pads (I/O pins) on the Platform. + + This function connects the AXI bus signals to the respective pads on the Platform, taking into + account their roles (master or slave) for each channel type. + + Parameters: + bus : AXI bus interface. + pads : FPGA pad interface. + mode : Role for connection (master or slave). + axi_full : Boolean flag to indicate if AXI full is being used. + + Returns: + list: List of statements to create the necessary connections. + """ assert mode in ["slave", "master"] r = [] def swap_mode(mode): return "master" if mode == "slave" else "slave" @@ -69,11 +99,13 @@ def connect_to_pads(bus, pads, mode="master", axi_full=False): "ar": mode, "r" : swap_mode(mode), } + # Loop to connect each channel. for channel, mode in channel_modes.items(): ch = getattr(bus, channel) sig_list = [("valid", 1)] + ch.description.payload_layout + ch.description.param_layout if channel in ["w", "r"] and axi_full: sig_list += [("last", 1)] + # Loop to connect each signal within a channel. for name, width in sig_list: if (name == "dest"): continue # No DEST. @@ -95,19 +127,40 @@ def connect_to_pads(bus, pads, mode="master", axi_full=False): return r def axi_layout_flat(axi): - # yields tuples (channel, name, direction) + """ + Generator that yields a flat layout of each AXI signal's channel, name, and direction. + + This function is a generator that iterates over each AXI channel ("aw", "w", "b", "ar", "r"), + then over each group in the channel's layout. + + Parameters: + axi: AXI interface object. + + Yields: + tuple: A tuple of (channel, name, direction), where: + - channel is the name of the AXI channel, + - name is the name of the signal within that channel, + - direction is the direction of the signal (DIR_M_TO_S or DIR_S_TO_M). + """ + + # Helper function to correctly set the direction for "b" and "r" channels. def get_dir(channel, direction): if channel in ["b", "r"]: return {DIR_M_TO_S: DIR_S_TO_M, DIR_S_TO_M: DIR_M_TO_S}[direction] return direction + + # Iterate over each channel. for ch in ["aw", "w", "b", "ar", "r"]: channel = getattr(axi, ch) + + # Iterate over each group in the channel's layout. for group in channel.layout: if len(group) == 3: name, _, direction = group yield ch, name, get_dir(ch, direction) else: _, subgroups = group + # Iterate over each subgroup in the group. for subgroup in subgroups: name, _, direction = subgroup yield ch, name, get_dir(ch, direction)