Overview

Unified Chip Design Platform - Address Map.

Modules:

Name	Description
access	Access.
addrdecoder	Address Decoder aka Demultiplexer.
addrinfo	Address Information.
addrmap	Address Map.
addrmapfinder	Address Map Finder.
addrmapref	Module, Word and Field Reference.
addrmaster	Generic Master.
addrmatrix	Master-Slave Matrix.
addrrange	Address Range.
addrref	Addressed Reference.
addrslave	Generic Addressed Slave.
addrspace	Address Space.
addrspacealias	Address Space Alias.
addrspaces	Address Spaces.
cli	Command Line Interface.
const	Constants.
data	Access Type Description.
datainfo	Data Information.
defines	Defines.
resolver	Module, Word and Field Resolver.
util	Utilities.
wordinfo	Word Information.

Classes:

Name	Description
Access	Access.
ReadOp	Read Operation.
WriteOp	Write Operation.
AddrDecoder	Address Decoder aka Demultiplexer.
AddrInfo	Address Info.
AddrMap	Address Map.
AddrMapRef	Address Map Reference.
AddrMaster	Master.
AddrMatrix	Bus Matrix with a number of masters and slave with optional connections.
AddrRange	Address Range.
AddrSlave	Slave.
SlaveAddrspace	Slave Address Space.
Addrspace	Address Space.
DefaultAddrspace	Default Address Space.
Field	Field.
FullError	Full.
ReservedAddrspace	A Reserved Address Space.
Word	Word.
Words	Multiple Related Words.
AddrspaceAlias	Address Space Alias.
DataType	Trans Type.
DataInfo	Data Information.
WordInfo	WordInfo Info.

Functions:

Name	Description
any_read	Return True if there is any read.
cast_access	Cast Access.
get_counteraccess	Get Counter Access.
is_read_repeatable	Return True if a read has no side-effects.
is_write_repeatable	Return True if a write has no side-effects.
create_fill_addrspace	Create Fill Addrspace.
get_addrmap	Search Address Spaces and Create Address Map.
get_addrspaces	Search Address Spaces.
create_fill_field	Create Fill Field.
create_fill_word	Create Fill Word.
get_is_const	Calc Is Constant Flag based on Accesses.
get_is_volatile	Calc Volatile Flag based on Accesses.
get_mask	Return mask for all fields of one word.
name_alpha	Convert number to a alpha digit.
read_on_modify	Return True if a read is needed in read-modify-write operations on word word with mask.
resolve_field_value	Resolve Enumeration If necessary.
join_addrspaces	Join Address Spaces.
zip_addrspaces	Zip Address Spaces.
check_data	Check Data.
get_datatype	Data Type.
get_size	Determine Maximum Addressed Size of Data.
resolve	Retrieve AddrSpace, Word and Field referenced by item from addrmap.
resolves	Same as resolve but returns all matches.
calc_depth_size	Calc Either Depth Or Size.
split_keyvaluepairs	Split comma-separated fields into (name, value) pairs.

Attributes:

Name	Type	Description
ToAddrMapRef	TypeAlias	Unresolved Address Map Reference.
AddrRef	TypeAlias	Addressed Reference.
AddrData	TypeAlias	Address-Data Pair.

ToAddrMapRef module-attribute

ToAddrMapRef = (
    AddrMapRef | AddrRange | Addrspace | str | int
)

Unresolved Address Map Reference.

AddrRef module-attribute

AddrRef = Object | str

Addressed Reference.

AddrData module-attribute

AddrData = tuple[int, int]

Address-Data Pair.

Access

Bases: IdentLightObject

Access.

Attributes:

Name	Type	Description
title		Title.
descr		Description.

title property

title

Title.

descr property

descr

Description.

ReadOp

Bases: IdentLightObject

Read Operation.

NEXT = {data}DATA

Attributes:

Name	Type	Description
data	Literal[None, 0, 1, '~']	Operation On Stored Data.
once	bool	Operation is just allowed once.
title	str	Title.
descr	str	Description.

data class-attribute instance-attribute

data = None

Operation On Stored Data.

once class-attribute instance-attribute

once = False

Operation is just allowed once.

title class-attribute instance-attribute

title = Field(repr=False)

Title.

descr class-attribute instance-attribute

descr = Field(repr=False)

Description.

WriteOp

Bases: IdentLightObject

Write Operation.

NEXT = {data}DATA {op} {write}WRITE

Attributes:

Name	Type	Description
data	Literal[None, '', '~']	Operation On Stored Data.
op	Literal[None, 0, 1, '&', '|']	Operation On Stored and Incoming Data.
write	Literal[None, '', '~']	Operation On Incoming Data.
once	bool	Operation is just allowed once.
title	str	Title.
descr	str	Description.

data class-attribute instance-attribute

data = None

Operation On Stored Data.

op class-attribute instance-attribute

op = None

Operation On Stored and Incoming Data.

write class-attribute instance-attribute

write = None

Operation On Incoming Data.

once class-attribute instance-attribute

once = False

Operation is just allowed once.

title class-attribute instance-attribute

title = Field(repr=False)

Title.

descr class-attribute instance-attribute

descr = Field(repr=False)

Description.

AddrDecoder

Bases: Object

Address Decoder aka Demultiplexer.

An address decoder manages the access to a known list of slaves. The address map contains the address to slave mapping.

An address decoder contains a unique address map and a namespace with all slaves.

Methods:

Name	Description
get_addrspaces	Address Spaces.

Attributes:

Name	Type	Description
addrmap	AddrMap	Address Map With All Slaves.
slaves	Namespace	Namespace With All Slaves.
default_size	Bytes | None	Default Size if not given.
is_sub	bool	Just decode address LSBs.

addrmap class-attribute instance-attribute

addrmap = Field(
    default_factory=lambda: AddrMap(unique=True)
)

Address Map With All Slaves.

slaves class-attribute instance-attribute

slaves = Field(default_factory=Namespace)

Namespace With All Slaves.

default_size class-attribute instance-attribute

default_size = None

Default Size if not given.

is_sub class-attribute instance-attribute

is_sub = False

Just decode address LSBs.

get_addrspaces

get_addrspaces(**kwargs)

Address Spaces.

AddrInfo

Bases: Object

Address Info.

Methods:

Name	Description
create	Create AddrInfo.
iter	Iteratate over address ranges.

create staticmethod

create(addrmap, item, offset=None, mask=None)

Create AddrInfo.

Parameters:

Name	Type	Description	Default
addrmap	AddrMap	Address Map	required
item	ToAddrMapRef	Thing to be resolved	required

Other Parameters:

Name	Type	Description
offset	int | None	address offset in bytes
mask	int | None	Value Mask (not allowed for fields)

Example Address Map:

>>> import ucdp as u
>>> from ucdp_addr import Addrspace, Word, Field, AddrMap
>>> addrmap = AddrMap()
>>> for idx, aname in enumerate(("uart", "spi", "owi")):
...     addrspace = Addrspace(name=aname, width=32, depth=8, baseaddr=8*4*idx)
...     addrmap.add(addrspace)
...     word = addrspace.add_word("ctrl")
...     field = word.add_field("ena", u.BitType(), "RW")
...     word = addrspace.add_word("stat")
...     field = word.add_field("bsy", u.BitType(), "RO", offset=9)

Addrspace:

>>> addrinfo = AddrInfo.create(addrmap, "spi")
>>> str(addrinfo)
'spi [0x20 8x32 (32 bytes)]'
>>> addrinfo.ref
AddrMapRef(..., addrspace=Addrspace(name='spi', baseaddr=Hex('0x20'), size=Bytesize('32 bytes')))
>>> addrinfo.mask
>>> tuple(addrinfo.iter())
(Hex('0x20'), Hex('0x24'), Hex('0x28'), Hex('0x2C'), Hex('0x30'), Hex('0x34'), Hex('0x38'), Hex('0x3C'))

>>> addrinfo = AddrInfo.create(addrmap, "spi", offset=8, mask=0xF0)
>>> str(addrinfo)
'spi [0x28 6x32 (24 bytes)] mask=0xF0'
>>> addrinfo.mask
Hex('0xF0')
>>> tuple(addrinfo.iter())
(Hex('0x28'), Hex('0x2C'), Hex('0x30'), Hex('0x34'), Hex('0x38'), Hex('0x3C'))

Word:

>>> addrinfo = AddrInfo.create(addrmap, "spi.stat")
>>> str(addrinfo)
'spi.stat [0x24 1x32 (4 bytes)]'
>>> addrinfo.ref
AddrMapRef(..., addrspace=Addrspace(name='spi', baseaddr=Hex('0x20'), ..., word=Word(name='stat', ...)
>>> addrinfo.mask
>>> tuple(addrinfo.iter())
(Hex('0x24'),)

>>> AddrInfo.create(addrmap, "spi.stat", offset=8)
Traceback (most recent call last):
  ...
ValueError: 'offset' is not allowed for words and fields

Field:

>>> addrinfo = AddrInfo.create(addrmap, "spi.stat.bsy")
>>> str(addrinfo)
'spi.stat.bsy [0x24 1x32 (4 bytes)] mask=0x200'
>>> addrinfo.ref
AddrMapRef(...Hex('0x20'), ... word=Word(name='stat', ...(name='bsy', type_=BitType(), bus=RO, offset=9))
>>> addrinfo.mask
Hex('0x200')
>>> tuple(addrinfo.iter())
(Hex('0x24'),)

>>> AddrInfo.create(addrmap, "spi.stat.bsy", offset=8)
Traceback (most recent call last):
  ...
ValueError: 'offset' is not allowed for words and fields
>>> AddrInfo.create(addrmap, "spi.stat.bsy", mask=8)
Traceback (most recent call last):
  ...
ValueError: 'mask' is not allowed for fields

iter

iter()

Iteratate over address ranges.

AddrMap

Bases: Object

Address Map.

Methods:

Name	Description
from_addrspaces	Create From address spaces.
add	Add Address Space.
get	Add Address Space.
iter	Iterate over Address Spaces.
get_free_baseaddr	Return baseaddress of free window with size.
get_overview	Return overview table.
get_addrspaces_overview	Get Address Spaces Overview Data.
get_word_fields_overview	Get Word-Fields Overview Data.

Attributes:

Name	Type	Description
size	Bytes | None	Size in Bytes.
addrwidth	int | None	Address Width.
firstaddr	int | None	First used address.
lastaddr	int | None	Last used address.
addrslice	Slice | None	Address Slice.

size property

size

Size in Bytes.

addrwidth property

addrwidth

Address Width.

firstaddr property

firstaddr

First used address.

lastaddr property

lastaddr

Last used address.

addrslice property

addrslice

Address Slice.

from_addrspaces staticmethod

from_addrspaces(
    addrspaces,
    unique=False,
    fixed_size=None,
    defines=None,
    ref=None,
)

Create From address spaces.

add

add(addrspace)

Add Address Space.

get

get(addrspace)

Add Address Space.

iter

iter(filter_=None, fill=None)

Iterate over Address Spaces.

get_free_baseaddr

get_free_baseaddr(size, align=None, start=None)

Return baseaddress of free window with size.

Parameters:

Name	Type	Description	Default
size	Bytes	Window Size	required

Other Parameters:

Name	Type	Description
align		Alignment, default aligned to size
start		Start search behind given address

get_overview

get_overview(minimal=False, fill=None)

Return overview table.

get_addrspaces_overview

get_addrspaces_overview(fill=None)

Get Address Spaces Overview Data.

get_word_fields_overview

get_word_fields_overview(
    addrspaces=True, words=True, fields=True
)

Get Word-Fields Overview Data.

AddrMapRef

Bases: Object

Address Map Reference.

Methods:

Name	Description
create	Create Addrspace with Proper AddrRange.

Attributes:

Name	Type	Description
addrrange	AddrRange	Address Range.
addrspace	Addrspace | None	Address Space.
word	Word | None	Word.
field	Field | None	Field.

addrrange instance-attribute

addrrange

Address Range.

addrspace class-attribute instance-attribute

addrspace = None

Address Space.

word class-attribute instance-attribute

word = None

Word.

field class-attribute instance-attribute

field = None

Field.

create staticmethod

create(addrspace, word=None, field=None, addrrange=None)

Create Addrspace with Proper AddrRange.

Parameters:

Name	Type	Description	Default
addrspace	Addrspace	Address Space	required

Other Parameters:

Name	Type	Description
word	Word | None	Word
field	Field | None	Field (requires word as well)
addrrange	AddrRange | None	Address Range

AddrMaster

Bases: IdentObject

Master.

AddrMatrix

Bases: AddrDecoder

Bus Matrix with a number of masters and slave with optional connections.

Methods:

Name	Description
add_interconnects	Add Interconnects.
get_overview	Return overview tables.

Attributes:

Name	Type	Description
masters	Namespace	Masters.
master_slaves	tuple[tuple[AddrMaster, tuple[AddrSlave, ...]], ...]	Masters and Their Slaves.
slave_masters	tuple[tuple[AddrSlave, tuple[AddrMaster, ...]], ...]	Slaves and Their Masters.

masters class-attribute instance-attribute

masters = Field(default_factory=Namespace)

Masters.

master_slaves property

master_slaves

Masters and Their Slaves.

slave_masters property

slave_masters

Slaves and Their Masters.

add_interconnects

add_interconnects(masternames, slavenames)

Add Interconnects.

get_overview

get_overview()

Return overview tables.

AddrRange

Bases: Object

Address Range.

Examples:

>>> addrrange = AddrRange(size='4k')
>>> addrrange
AddrRange(size=Bytesize('4 KB'))
>>> addrrange.baseaddr
Hex('0x0')
>>> addrrange.width
32
>>> addrrange.depth
1024
>>> addrrange.size
Bytesize('4 KB')
>>> addrrange.addrwidth
12
>>> addrrange.endaddr
Hex('0xFFF')
>>> addrrange.nextaddr
Hex('0x1000')
>>> addrrange.wordsize
4.0
>>> str(addrrange)
'0x0 1024x32 (4 KB)'
>>> str(AddrRange(depth=16))
'0x0 16x32 (64 bytes)'
>>> str(AddrRange(size=16))
'0x0 4x32 (16 bytes)'

Attributes:

Name	Type	Description
baseaddr	Hex	Base Address
width	PositiveInt	Width in Bits.
depth	PositiveInt	Number of words.
size	Bytes	Size in Bytes.
addrwidth	PositiveInt	Address Width.
addrmask	PositiveInt	Address Width.
endaddr	Hex	End Address - baseaddr+size-1.
nextaddr	Hex	Next Free Address - baseaddr+size.
wordsize	float	Number of Bytes Per Word.
org	str	Organization.

baseaddr class-attribute instance-attribute

baseaddr = BASEADDR_DEFAULT

Base Address

width class-attribute instance-attribute

width = 32

Width in Bits.

depth class-attribute instance-attribute

depth = Field(repr=False)

Number of words.

size instance-attribute

size

Size in Bytes.

addrwidth property

addrwidth

Address Width.

addrmask property

addrmask

Address Width.

endaddr property

endaddr

End Address - baseaddr+size-1.

nextaddr property

nextaddr

Next Free Address - baseaddr+size.

wordsize property

wordsize

Number of Bytes Per Word.

org property

org

Organization.

AddrSlave

Bases: IdentObject

Slave.

Methods:

Name	Description
add_addrrange	Add Address Range.

Attributes:

Name	Type	Description
addrdecoder	AddrDecoder	Demultiplexer Addressing This Slave.
ref	AddrRef | None	Addressed Module.

addrdecoder class-attribute instance-attribute

addrdecoder = Field(repr=False)

Demultiplexer Addressing This Slave.

ref class-attribute instance-attribute

ref = None

Addressed Module.

add_addrrange

add_addrrange(baseaddr=AUTO, size=None)

Add Address Range.

Other Parameters:

Name	Type	Description
baseaddr		Sub Start Address. Take next free if 'AUTO'.
size	Bytes | None	Address Range Size (i.e. '4k')
ref		Referenced Object or instance path to it.

SlaveAddrspace

Bases: Addrspace

Slave Address Space.

Addrspace

Bases: AddrRange, IdentObject

Address Space.

Methods:

Name	Description
add_word	Add Word.
add_words	Add Word.
get_word	Retrieve Word.
lock	Lock For Modification.
get_word_hiername	Get Hierarchical Word Name.
get_field_hiername	Get Hierarchical Field Name.
iter	Iterate over words and their fields.
is_overlapping	Determine both Address Spaces Overlap.
get_intersect	Get Intersection.
join	Join if Possible.

Attributes:

Name	Type	Description
name	str	Name.
is_sub	bool	Address Decoder Just Compares addrwidth LSBs.
words	Namespace	Words within Address Space.
doc	Doc	Documentation
attrs	CastableAttrs	Attributes.
add_words_naming	NamingScheme	Naming Scheme for words created by add_words.
title	str | None	Alias to doc.title.
descr	str | None	Alias to doc.descr.
comment	str | None	Alias to doc.comment.
comment_or_title	str | None	Return comment if set, otherwise title.
size_used	Bytes	Number of Bytes Used.
free_offset	int	Free Offset.
info	str	Info.
base	str	Base.
access	str	Access.

name class-attribute instance-attribute

name = ''

Name.

is_sub class-attribute instance-attribute

is_sub = True

Address Decoder Just Compares addrwidth LSBs.

words class-attribute instance-attribute

words = Field(default_factory=Namespace, repr=False)

Words within Address Space.

doc class-attribute instance-attribute

doc = Doc()

Documentation

attrs class-attribute instance-attribute

attrs = ()

Attributes.

add_words_naming class-attribute instance-attribute

add_words_naming = 'dec'

Naming Scheme for words created by add_words.

title property

title

Alias to doc.title.

descr property

descr

Alias to doc.descr.

comment property

comment

Alias to doc.comment.

comment_or_title property

comment_or_title

Return comment if set, otherwise title.

size_used property

size_used

Number of Bytes Used.

free_offset property

free_offset

Free Offset.

info property

info

Info.

base property

base

Base.

access property

access

Access.

add_word

add_word(
    name,
    offset=None,
    align=None,
    byteoffset=None,
    bytealign=None,
    depth=None,
    bus=None,
    core=None,
    is_volatile=None,
    title=None,
    descr=None,
    comment=None,
    **kwargs,
)

Add Word.

add_words

add_words(
    name,
    offset=None,
    align=None,
    byteoffset=None,
    bytealign=None,
    depth=None,
    naming=None,
    **kwargs,
)

Add Word.

get_word

get_word(name)

Retrieve Word.

lock

lock()

Lock For Modification.

get_word_hiername

get_word_hiername(word)

Get Hierarchical Word Name.

get_field_hiername

get_field_hiername(word, field)

Get Hierarchical Field Name.

iter

iter(
    wordfilter=None,
    fieldfilter=None,
    fill=None,
    fill_word=None,
    fill_field=None,
    fill_word_end=None,
    fill_field_end=None,
)

Iterate over words and their fields.

is_overlapping

is_overlapping(other)

Determine both Address Spaces Overlap.

>>> one = Addrspace(name='one', baseaddr=0x2000, size='4kB')
>>> two = Addrspace(name='two', baseaddr=0x3000, size='4kB')
>>> three = Addrspace(name='three', baseaddr=0x2000, size='5kB')
>>> one.is_overlapping(two)
False
>>> one.is_overlapping(three)
True
>>> three.is_overlapping(one)
True
>>> three.is_overlapping(two)
True

get_intersect

get_intersect(other)

Get Intersection.

>>> one = Addrspace(name='one', baseaddr=0x2000, size='4kB')
>>> two = Addrspace(name='two', baseaddr=0x3000, size='4kB')
>>> three = Addrspace(name='three', baseaddr=0x2000, size='5kB')
>>> one.get_intersect(two)
>>> one.get_intersect(three)
Addrspace(name='one', baseaddr=Hex('0x2000'), size=Bytesize('4 KB'))
>>> three.get_intersect(one)
Addrspace(name='three', baseaddr=Hex('0x2000'), size=Bytesize('4 KB'))
>>> three.get_intersect(two)
Addrspace(name='three', baseaddr=Hex('0x3000'), size=Bytesize('1 KB'))

join

join(other)

Join if Possible.

TODO: doc

DefaultAddrspace

Bases: Addrspace

Default Address Space.

Field

Bases: IdentLightObject

Field.

Attributes:

Name	Type	Description
type_	BaseScalarType	Type.
bus	Access | None	Bus Access.
core	Access | None	Core Access.
offset	int | Expr	Rightmost Bit Position.
is_volatile	bool	Volatile.
doc	Doc	Documentation.
attrs	CastableAttrs	Attributes.
title	str | None	Alias to doc.title.
descr	str | None	Alias to doc.descr.
comment	str | None	Alias to doc.comment.
comment_or_title	str | None	Return comment if set, otherwise title.
slice	Slice	Slice with Word.
is_const	bool	Field is Constant.
access	str	Access.

type_ instance-attribute

type_

Type.

bus class-attribute instance-attribute

bus = None

Bus Access.

core class-attribute instance-attribute

core = None

Core Access.

offset instance-attribute

offset

Rightmost Bit Position.

is_volatile class-attribute instance-attribute

is_volatile = False

Volatile.

doc class-attribute instance-attribute

doc = Doc()

Documentation.

attrs class-attribute instance-attribute

attrs = ()

Attributes.

title property

title

Alias to doc.title.

descr property

descr

Alias to doc.descr.

comment property

comment

Alias to doc.comment.

comment_or_title property

comment_or_title

Return comment if set, otherwise title.

slice property

slice

Slice with Word.

is_const property

is_const

Field is Constant.

access property

access

Access.

FullError

Bases: ValueError

Full.

ReservedAddrspace

Bases: Addrspace

A Reserved Address Space.

Word

Bases: IdentObject

Word.

Methods:

Name	Description
add_field	Add field.
lock	Lock For Modification.
get_field	Get Field.
get_default	Return Word default value for all fields of one word.
get_mask	Return mask for all fields of one word.

Attributes:

Name	Type	Description
fields	Namespace	Fields within Word.
offset	int | Expr	Rightmost Word Position.
width	int	Width in Bits.
depth	int | Expr | None	Number of words.
doc	Doc	Documentation
attrs	CastableAttrs	Attributes.
title	str | None	Alias to doc.title.
descr	str | None	Alias to doc.descr.
comment	str | None	Alias to doc.comment.
comment_or_title	str | None	Return comment if set, otherwise title.
slice	Slice	Slice with Address Space.
wordsize	float	Word Size in Bytes.
byteoffset	Hex	Offset in Bytes, if word width is multiple of 8.
access	str	Access.

fields class-attribute instance-attribute

fields = Field(
    default_factory=Namespace, init=False, repr=False
)

Fields within Word.

offset instance-attribute

offset

Rightmost Word Position.

width instance-attribute

width

Width in Bits.

depth class-attribute instance-attribute

depth = None

Number of words.

doc class-attribute instance-attribute

doc = Doc()

Documentation

attrs class-attribute instance-attribute

attrs = ()

Attributes.

title property

title

Alias to doc.title.

descr property

descr

Alias to doc.descr.

comment property

comment

Alias to doc.comment.

comment_or_title property

comment_or_title

Return comment if set, otherwise title.

slice property

slice

Slice with Address Space.

wordsize property

wordsize

Word Size in Bytes.

byteoffset property

byteoffset

Offset in Bytes, if word width is multiple of 8.

access property

access

Access.

add_field

add_field(
    name,
    type_,
    bus=None,
    core=None,
    offset=None,
    align=None,
    is_volatile=None,
    title=None,
    descr=None,
    comment=None,
    attrs=None,
    **kwargs,
)

Add field.

lock

lock()

Lock For Modification.

get_field

get_field(name)

Get Field.

get_default

get_default(filter_=None)

Return Word default value for all fields of one word.

import ucdp_addr as ua word = ua.Word(name='word', offset=0, width=32) field = word.add_field('field0', u.UintType(3, default=3), ua.access.RO) field = word.add_field('field1', u.SintType(6, default=-8), ua.access.WO, align=4) field = word.add_field('field2', u.UintType(3, default=4), ua.access.RW, align=4)

word.get_default() Hex('0x00004383') word.get_default(filter_=lambda field: field.bus.read) Hex('0x00004003') word.get_default(filter_=lambda field: field.bus.write) Hex('0x00004380') word.get_default(filter_=lambda field: field.bus.read and field.bus.write) Hex('0x00004000')

get_mask

get_mask(filter_=None)

Return mask for all fields of one word.

import ucdp_addr as ua word = ua.Word(name='word', offset=0, width=32) field = word.add_field('field0', u.UintType(3), ua.access.RO) field = word.add_field('field1', u.UintType(6), ua.access.WO, align=4) field = word.add_field('field2', u.UintType(3), ua.access.RW, align=4)

word.get_mask() Hex('0x000073F7') word.get_mask(filter_=lambda field: field.bus.read) Hex('0x00007007') word.get_mask(filter_=lambda field: field.bus.write) Hex('0x000073F0') word.get_mask(filter_=lambda field: field.bus.read and field.bus.write) Hex('0x00007000')

Words

Bases: Object

Multiple Related Words.

Methods:

Name	Description
create	Create Helper for Set of Words.
next	Start a new Word.
add_field	Add Field to Current Word or start a new one.

Attributes:

Name	Type	Description
idx	int	Next Word Index.
word	Word	Current Word.
fields	tuple[Field, ...]	Fields Of All Words.

idx instance-attribute

idx

Next Word Index.

word instance-attribute

word

Current Word.

fields property

fields

Fields Of All Words.

create classmethod

create(
    name, addrspace, word_kwargs, naming="dec", **kwargs
)

Create Helper for Set of Words.

next

next()

Start a new Word.

add_field

add_field(*args, **kwargs)

Add Field to Current Word or start a new one.

AddrspaceAlias

Bases: Addrspace

Address Space Alias.

DataType

Bases: Enum

Trans Type.

DataInfo

Bases: Object

Data Information.

Single Data:

>>> datainfo = DataInfo.create(5)
>>> datainfo
DataInfo(datatype=SINGLE, data=5)
>>> str(datainfo)
'SINGLE: 5'
>>> tuple(datainfo.iter(AddrRange(width=64, depth=8)))
((Hex('0x0'), 5),)
>>> tuple(datainfo.iter(AddrRange(baseaddr=0x1000, width=64, depth=8)))
((Hex('0x1000'), 5),)

Burst Data:

>>> datainfo = DataInfo.create((5, 6, 7))
>>> datainfo
DataInfo(datatype=BURST, data=(5, 6, 7))
>>> str(datainfo)
'BURST: (5, 6, 7)'
>>> tuple(datainfo.iter(AddrRange(width=64, depth=8)))
((Hex('0x0'), 5), (Hex('0x8'), 6), (Hex('0x10'), 7))
>>> tuple(datainfo.iter(AddrRange(baseaddr=0x1000, width=64, depth=8)))
((Hex('0x1000'), 5), (Hex('0x1008'), 6), (Hex('0x1010'), 7))

Scattered Data:

>>> datainfo = DataInfo.create(((16, 5), (28, 6), (60, 7)))
>>> datainfo
DataInfo(datatype=SCAT, data=((16, 5), (28, 6), (60, 7)))
>>> str(datainfo)
'SCAT: ((16, 5), (28, 6), (60, 7))'
>>> tuple(datainfo.iter(AddrRange(width=64, depth=8)))
((Hex('0x10'), 5), (Hex('0x1C'), 6), (Hex('0x3C'), 7))
>>> tuple(datainfo.iter(AddrRange(baseaddr=0x1000, width=64, depth=8)))
((Hex('0x1010'), 5), (Hex('0x101C'), 6), (Hex('0x103C'), 7))

Errors:

>>> DataInfo.create('a')
Traceback (most recent call last):
  ...
TypeError: a
>>> DataInfo.create(('a', 'b'))
Traceback (most recent call last):
  ...
TypeError: ('a', 'b')

Methods:

Name	Description
create	Create :any:DataInfo for data.
iter	Iteratate over single address value pairs according to access.

create staticmethod

create(data)

Create :any:DataInfo for data.

iter

iter(addrrange)

Iteratate over single address value pairs according to access.

WordInfo

Bases: Object

WordInfo Info.

Methods:

Name	Description
create	Create WordInfo.
iter	Iteratate over single address value pairs according to access.
addrs	Addresses.

Attributes:

Name	Type	Description
ref	AddrMapRef	Address Map Reference.
addrrange	AddrRange	Accessed Address Range.
datatype	DataType	Data Type.
data	Data	Data.
mask	Hex | None	Data Masking.
rmw	bool | None	Read Modify Write - Read before write required.
read_repeatable	bool | None	Read Operation Has No Side-Effects.
write_repeatable	bool | None	Write Operation Has No Side-Effects.

ref instance-attribute

ref

Address Map Reference.

addrrange instance-attribute

addrrange

Accessed Address Range.

datatype instance-attribute

datatype

Data Type.

data instance-attribute

data

Data.

mask class-attribute instance-attribute

mask = None

Data Masking.

rmw class-attribute instance-attribute

rmw = None

Read Modify Write - Read before write required.

read_repeatable class-attribute instance-attribute

read_repeatable = None

Read Operation Has No Side-Effects.

write_repeatable class-attribute instance-attribute

write_repeatable = None

Write Operation Has No Side-Effects.

create staticmethod

create(
    addrmap,
    item,
    data,
    offset=None,
    mask=None,
    wordsize=None,
)

Create WordInfo.

Parameters:

Name	Type	Description	Default
addrmap	AddrMap	Address Map	required
item	ToAddrMapRef	Thing to be resolved	required
data	Data | str | FieldValues	Data	required

Other Parameters:

Name	Type	Description
offset	Offset | None	address offset in bytes
mask	int | None	Mask for non-field access.
wordsize	Size | None	Size of one word in bytes (Only allowed if item is an int)

iter

iter()

Iteratate over single address value pairs according to access.

addrs

addrs()

Addresses.

any_read

any_read(accesses)

Return True if there is any read.

Usage:

>>> any_read([NA])
False
>>> any_read([RO, RO])
True
>>> any_read([RW, RW])
True
>>> any_read([RO, RW, WO])
True

cast_access

cast_access(value)

Cast Access.

Usage:

>>> from ucdp_addr import addrspace
>>> access = addrspace.cast_access("RO")
>>> access
RO
>>> cast_access(access)
RO

get_counteraccess

get_counteraccess(access)

Get Counter Access.

Usage:

>>> from ucdp_addr import get_counteraccess, access
>>> str(get_counteraccess(access.RO))
'RW'
>>> str(get_counteraccess(access.RW))
'RO'

is_read_repeatable

is_read_repeatable(accesses)

Return True if a read has no side-effects.

Usage:

>>> is_read_repeatable([NA])
True
>>> is_read_repeatable([RO, RO])
True
>>> is_read_repeatable([RW, RW])
True
>>> is_read_repeatable([RO, RW, WO])
True
>>> is_read_repeatable([RO, RW, RC])
False
>>> is_read_repeatable([RO, RW, RP])
False

is_write_repeatable

is_write_repeatable(accesses)

Return True if a write has no side-effects.

>>> is_write_repeatable([NA])
True
>>> is_write_repeatable([RO, RO])
True
>>> is_write_repeatable([RW, RW])
True
>>> is_write_repeatable([RO, RW, WO])
True
>>> is_write_repeatable([RO, RW, WL])
False

create_fill_addrspace

create_fill_addrspace(idx, baseaddr, size)

Create Fill Addrspace.

get_addrmap

get_addrmap(mod, defines=None, unique=False, ref=None)

Search Address Spaces and Create Address Map.

get_addrspaces

get_addrspaces(mod, defines=None)

Search Address Spaces.

create_fill_field

create_fill_field(word, idx, offset, width)

Create Fill Field.

create_fill_word

create_fill_word(addrspace, idx, offset, depth)

Create Fill Word.

get_is_const

get_is_const(bus, core)

Calc Is Constant Flag based on Accesses.

get_is_volatile

get_is_volatile(bus, core)

Calc Volatile Flag based on Accesses.

get_mask

get_mask(word, filter_=None)

Return mask for all fields of one word.

import ucdp_addr as ua word = ua.Word(name='word', offset=0, width=32) field = word.add_field('field0', u.UintType(3), ua.access.RO) field = word.add_field('field1', u.UintType(6), ua.access.WO, align=4) field = word.add_field('field2', u.UintType(3), ua.access.RW, align=4)

get_mask(word) Hex('0x000073F7') get_mask(word, filter_=lambda field: field.bus.read) Hex('0x00007007') get_mask(word, filter_=lambda field: field.bus.write) Hex('0x000073F0') get_mask(word, filter_=lambda field: field.bus.read and field.bus.write) Hex('0x00007000')

name_alpha

name_alpha(num)

Convert number to a alpha digit.

name_alpha(0) 'a' name_alpha(25) 'z' name_alpha(26) 'aa' name_alpha(27) 'ab' name_alpha(26+25) 'az' name_alpha(26+26) 'ba' name_alpha(26+26+25) 'bz' name_alpha(1000) 'alm'

read_on_modify

read_on_modify(word, mask)

Return True if a read is needed in read-modify-write operations on word word with mask.

import ucdp_addr as ua word = ua.Word(name='word', offset=0, width=32) field = word.add_field('field0', u.UintType(3), ua.access.RO) field = word.add_field('field1', u.UintType(6), ua.access.WO, align=4) field = word.add_field('field2', u.UintType(3), ua.access.RW, align=4)

read_on_modify(word, 0x00007000) False read_on_modify(word, 0x00003000) True

resolve_field_value

resolve_field_value(field, value)

Resolve Enumeration If necessary.

join_addrspaces

join_addrspaces(base, addrspaces)

Join Address Spaces.

zip_addrspaces

zip_addrspaces(lefts, rights)

Zip Address Spaces.

one = ( ... Addrspace(name='a0', baseaddr=0x0000, size=0x1000), ... Addrspace(name='a1', baseaddr=0x1000, size=0x1000)) other = ( ... Addrspace(name='b0', baseaddr=0x0000, size=0x1000), ... Addrspace(name='b1', baseaddr=0x1000, size=0x800), ... Addrspace(name='b2', baseaddr=0x1800, size=0x800)) for left, right in zip_addrspaces(one, other): print(f"{str(left)!r} {str(right)!r}") 'a0 +0x0 1024x32' 'b0 +0x0 1024x32' 'a1 +0x1000 1024x32' 'b1 +0x1000 512x32' 'a1 +0x1000 1024x32' 'b2 +0x1800 512x32'

check_data

check_data(data, width)

Check Data.

get_datatype

get_datatype(data)

Data Type.

get_size

get_size(data, wordsize)

Determine Maximum Addressed Size of Data.

resolve

resolve(addrmap, item)

Retrieve AddrSpace, Word and Field referenced by item from addrmap.

item may be a string pattern with word and field name separated by '.' according to this scheme: 'addrspace[.word[.field]]'. Wildcards '*' and '?' are supported. The first match is returned.

item may be an address (integer). On check=True the address is checked to be covered by a valid addrspace and word, if the addrspace contains words.

item may be already a address map reference. On check=True the address is checked to be covered by a valid addrspace and word, if the addrspace contains words.

Example:

import ucdp as u from ucdp_addr import Addrspace, Word, Field, AddrMap addrmap = AddrMap() for aname in ("uart", "spi", "owi"): ... addrspace = Addrspace(name=aname, width=32, depth=128) ... addrmap.add(addrspace) ... word = addrspace.add_word("ctrl") ... field = word.add_field("ena", u.BitType(), "RW") ... word = addrspace.add_word("stat") ... field = word.add_field("bsy", u.BitType(), "RO")

By string:

resolve(addrmap, "uart") AddrMapRef(..., addrspace=Addrspace(name='uart', ...)) resolve(addrmap, "uart.ctrl") AddrMapRef(..., addrspace=Addrspace(name='uart', ...), word=Word(name='ctrl', ...)) resolve(addrmap, "uart.ctrl.ena") AddrMapRef(..., addrspace=Addrspace(name='uart', ...), word=Word(name='ctrl', ...), field=Field(name='ena', ...))

By reference:

ref = resolve(addrmap, "uart.ctrl.ena") ref AddrMapRef(..., addrspace=Addrspace(name='uart', ...), word=Word(name='ctrl', ...), field=Field(name='ena', ...)) resolve(addrmap, ref) AddrMapRef(..., addrspace=Addrspace(name='uart', ...), word=Word(name='ctrl', ...), field=Field(name='ena', ...))

By address space:

resolve(addrmap, Addrspace(baseaddr=0, width=32, depth=1)) AddrMapRef(..., addrspace=Addrspace(name='uart', size=Bytesize('4 bytes')))

By address range:

resolve(addrmap, AddrRange(baseaddr=0, width=32, depth=1)) AddrMapRef(addrrange=AddrRange(size=Bytesize('4 bytes')))

By address:

resolve(addrmap, 8) AddrMapRef(addrrange=AddrRange(baseaddr=Hex('0x8'), size=Bytesize('4 bytes')))

Errors:

resolve(addrmap, "uart.missing") Traceback (most recent call last): ... ValueError: 'uart.missing' does not exists resolve(addrmap, "uart:ctrl") Traceback (most recent call last): ... ValueError: uart:ctrl does not match pattern 'addrspace[.word[.field]]' resolve(addrmap, 5.0) Traceback (most recent call last): ... TypeError: 5.0 resolve(addrmap, Addrspace(baseaddr=0x1000, width=32, depth=1)) Traceback (most recent call last): ... ValueError: Addrspace(baseaddr=Hex('0x1000'), size=Bytesize('4 bytes')) does not exists

resolves

resolves(addrmap, item)

Same as resolve but returns all matches.

import ucdp as u from ucdp_addr import Addrspace, Word, Field, AddrMap addrmap = AddrMap() for aname in ("uart", "spi", "owi"): ... addrspace = Addrspace(name=aname, width=32, depth=128) ... addrmap.add(addrspace) ... word = addrspace.add_word("ctrl") ... field = word.add_field("ena", u.BitType(), "RW") ... word = addrspace.add_word("stat") ... field = word.add_field("bsy", u.BitType(), "RO")

for item in resolves(addrmap, "*.ctrl.ena"): print(item) uart.ctrl.ena spi.ctrl.ena owi.ctrl.ena

calc_depth_size

calc_depth_size(width, depth=None, size=None)

Calc Either Depth Or Size.

calc_depth_size(32, depth=64) (64, Bytesize('256 bytes')) calc_depth_size(32, size='64') (16, Bytesize('64 bytes')) calc_depth_size(32, depth=64, size=256) (64, Bytesize('256 bytes')) calc_depth_size(32) Traceback (most recent call last): ... ValueError: Either 'depth' or 'size' are required. calc_depth_size(32, depth=64, size='64') Traceback (most recent call last): ... ValueError: 'depth' and 'size' are mutually exclusive.

split_keyvaluepairs

split_keyvaluepairs(value)

Split comma-separated fields into (name, value) pairs.

split_keyvaluepairs('a=4') {'a': '4'} split_keyvaluepairs('a=4, b=a') {'a': '4', 'b': 'a'} split_keyvaluepairs('a=4, b') Traceback (most recent call last): ... ValueError: Invalid key=value pair: 'b' split_keyvaluepairs('a=4, a=a') Traceback (most recent call last): ... ValueError: Duplicate key 'a'