From 828f00012c9fcddc7ae422fdda29679bdde852ff Mon Sep 17 00:00:00 2001 From: Martin Braun Date: Tue, 4 Jan 2022 17:50:50 +0100 Subject: docs: Improve page on RFNoC block properties - Fix some minor formatting - Add emphases where appropriate - Minor clarifications --- host/docs/properties.dox | 32 +++++++++++++++++++------------- 1 file changed, 19 insertions(+), 13 deletions(-) (limited to 'host/docs') diff --git a/host/docs/properties.dox b/host/docs/properties.dox index b6e899dfe..7ab99da3e 100644 --- a/host/docs/properties.dox +++ b/host/docs/properties.dox @@ -20,7 +20,7 @@ the incoming signal is shifted in frequency. The decimation is the integer value by which the incoming sampling rate is divided. Put differently, the user properties control the behaviour of the DDC block. -On top of that, the DDC block also has an edge property for the sampling rate +On top of that, the DDC block also has an *edge property* for the sampling rate on both the outgoing edge and the incoming edge. This property describes something about the data on this graph edge. @@ -28,7 +28,7 @@ something about the data on this graph edge. ┌──────────────┐ │ DDC Block │ samp_rate │ │ samp_rate -───────────> - freq ├─────────> +───────────> - freq ├───────────> │ - decim │ │ │ └──────────────┘ @@ -276,6 +276,7 @@ add_property_resolver( [this, &fft_size]() { fft_size = coerce_to_power_of_2(fft_size.get()); if (fft_size.is_dirty()) { + // FFT_SIZE_REG stores address of FFT size register this->regs().poke32(FFT_SIZE_REG, log2(fft_size.get())); } }); @@ -285,7 +286,7 @@ Alternatively, we poke the register as part of cleaning the property: ~~~{.cpp} register_property( &fft_size, - [this, &fft_size](){ this->regs().poke32(FFT_SIZE_REG, log2(FFT_SIZE.get()); } + [this, &fft_size](){ this->regs().poke32(FFT_SIZE_REG, log2(fft_size.get()); } ); add_property_resolver( {&fft_size}, @@ -302,11 +303,15 @@ The differences are subtle: - In the first approach, the register is poked as soon as the new value is known. In the second approach, the poke happens only after the resolution is complete. +- The manual step of checking the clean/dirty flag is used to avoid unnecessary + writes to hardware in the first approach. It is not required in the second + approach, because the write to hardware is coupled with the act of cleaning + the variable. In this particular instance, the second approach is the more readable and is -recommended. However, not always do properties map to poking registers (or other -actions) in a clean, one-to-one manner, which is when the first approach is -better suited. +recommended. However, not always does changing properties map to poking +registers (or other actions) in a clean, one-to-one manner, which is when the +first approach may be better suited. \section props_graph_resolution Graph Property Resolution @@ -425,13 +430,13 @@ the framework. There is a small number of edge properties that treated differently by the RFNoC framework. -\section props_special_props_tickrate Tick Rate +\section props_special_props_tickrate Tick Rate (`tick_rate`) The "tick rate" is the rate that is used for converting floating point timestamps into integer ticks. The tick rate has the additional constraint that within a graph, the tick rate must be the same for all blocks. Therefore, the tick rate is defined by the framework for all blocks that derive from uhd::rfnoc::noc_block_base, -and block authors cannot register properties with that name. +and block authors cannot register properties named `tick_rate`. The tick rate property is propagated to all edges to enforce all blocks having the same tick rate. Some blocks (like the radio blocks) set the tick rate via @@ -443,12 +448,13 @@ Within a block implementation, the uhd::rfnoc::noc_block_base::set_tick_rate() API call can be used to update the tick rate (most blocks do not have to do this). -\section props_special_props_mtu MTU +\section props_special_props_mtu MTU (`mtu`) -Because the MTU is part of the RFNoC framework (it is constrained by the buffer -size chosen between blocks, and is thus read back from a register in the FPGA), -its property is also created by the RFNoC framework for all blocks, and block -authors cannot use the name `mtu` for their properties. +Because the maximum transmission unit (MTU) is part of the RFNoC framework (it +is constrained by the buffer size chosen between blocks, and is thus read back +from a register in the FPGA), its property is also created by the RFNoC +framework for all blocks, and block authors cannot use the name `mtu` for their +properties. However, MTUs can differ within a graph, and blocks might have additional constraints on MTU. For this reason, accessing the MTU properties directly is -- cgit v1.2.3