From ecfad4d9abacf903a525f0a252c38844eda0d2dd Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jean-Fran=C3=A7ois=20Nguyen?= Date: Thu, 20 Aug 2020 17:56:09 +0200 Subject: [PATCH] Clarify documentation for alignment parameters to mention it is log2. Fixes #6. --- nmigen_soc/csr/bus.py | 25 +++++++++++++------------ nmigen_soc/memory.py | 6 +++--- nmigen_soc/wishbone/bus.py | 4 ++-- 3 files changed, 18 insertions(+), 17 deletions(-) diff --git a/nmigen_soc/csr/bus.py b/nmigen_soc/csr/bus.py index 5f40177..0f444ee 100644 --- a/nmigen_soc/csr/bus.py +++ b/nmigen_soc/csr/bus.py @@ -192,19 +192,20 @@ class Multiplexer(Elaboratable): are possible for connecting the CSR bus to the CPU: * The CPU could access the CSR bus directly (with no intervening logic other than simple translation of control signals). In this case, the register alignment should be set - to 1, and each *w*-bit register would occupy *ceil(w/n)* addresses from the CPU - perspective, requiring the same amount of memory instructions to access. + to 1 (i.e. `alignment` should be set to 0), and each *w*-bit register would occupy + *ceil(w/n)* addresses from the CPU perspective, requiring the same amount of memory + instructions to access. * The CPU could also access the CSR bus through a width down-converter, which would issue *k/n* CSR accesses for each CPU access. In this case, the register alignment should be set to *k/n*, and each *w*-bit register would occupy *ceil(w/k)* addresses from the CPU perspective, requiring the same amount of memory instructions to access. - If alignment is greater than 1, it affects which CSR bus write is considered a write to - the last register chunk. For example, if a 24-bit register is used with a 8-bit CSR bus and - a CPU with a 32-bit datapath, a write to this register requires 4 CSR bus writes to complete - and the 4th write is the one that actually writes the value to the register. This allows - determining write latency solely from the amount of addresses the register occupies in - the CPU address space, and the width of the CSR bus. + If the register alignment (i.e. `2 ** alignment`) is greater than 1, it affects which CSR bus + write is considered a write to the last register chunk. For example, if a 24-bit register is + used with a 8-bit CSR bus and a CPU with a 32-bit datapath, a write to this register requires + 4 CSR bus writes to complete and the 4th write is the one that actually writes the value to + the register. This allows determining write latency solely from the amount of addresses the + register occupies in the CPU address space, and the width of the CSR bus. Parameters ---------- @@ -212,8 +213,8 @@ class Multiplexer(Elaboratable): Address width. See :class:`Interface`. data_width : int Data width. See :class:`Interface`. - alignment : int - Register alignment. See :class:`Interface`. + alignment : log2 of int + Register alignment. See :class:`..memory.MemoryMap`. Attributes ---------- @@ -327,8 +328,8 @@ class Decoder(Elaboratable): Address width. See :class:`Interface`. data_width : int Data width. See :class:`Interface`. - alignment : int - Window alignment. See :class:`Interface`. + alignment : log2 of int + Window alignment. See :class:`..memory.MemoryMap`. Attributes ---------- diff --git a/nmigen_soc/memory.py b/nmigen_soc/memory.py index c1df25c..1ff7c2b 100644 --- a/nmigen_soc/memory.py +++ b/nmigen_soc/memory.py @@ -70,7 +70,7 @@ class MemoryMap: Address width. data_width : int Data width. - alignment : int + alignment : log2 of int Range alignment. Each added resource and window will be placed at an address that is a multiple of ``2 ** alignment``, and its size will be rounded up to be a multiple of ``2 ** alignment``. @@ -142,7 +142,7 @@ def align_to(self, alignment): Arguments --------- - alignment : int + alignment : log2 of int Address alignment. The start of the implicit next address will be a multiple of ``2 ** max(alignment, self.alignment)``. @@ -216,7 +216,7 @@ def add_resource(self, resource, *, size, addr=None, alignment=None, extend=Fals size : int Size of the resource, in minimal addressable units. Rounded up to a multiple of ``2 ** max(alignment, self.alignment)``. - alignment : int or None + alignment : log2 of int or None Alignment of the resource. If not specified, the memory map alignment is used. extend: bool Allow memory map extension. If ``True``, the upper bound of the address space is diff --git a/nmigen_soc/wishbone/bus.py b/nmigen_soc/wishbone/bus.py index 3916213..a62949b 100644 --- a/nmigen_soc/wishbone/bus.py +++ b/nmigen_soc/wishbone/bus.py @@ -184,8 +184,8 @@ class Decoder(Elaboratable): Granularity. See :class:`Interface` features : iter(str) Optional signal set. See :class:`Interface`. - alignment : int - Window alignment. See :class:`Interface`. + alignment : log2 of int + Window alignment. See :class:`..memory.MemoryMap` Attributes ----------