Coverage for hdl_registers/generator/python/register_accessor_interface.py: 100%

1# -------------------------------------------------------------------------------------------------- 

2# Copyright (c) Lukas Vik. All rights reserved. 

3# 

4# This file is part of the hdl-registers project, an HDL register generator fast enough to run 

5# in real time. 

6# https://hdl-registers.com 

7# https://github.com/hdl-registers/hdl-registers 

8# -------------------------------------------------------------------------------------------------- 

9 

10# Standard libraries 

11from abc import ABC, abstractmethod 

12 

13 

14class PythonRegisterAccessorInterface(ABC): 

15 """ 

16 Interface base class for accessing register values on a target system. 

17 To be used with code generated by :class:`.PythonAccessorGenerator`. 

18 See the :ref:`Python generator documentation <generator_python>` for usage details. 

19 

20 In order to use :class:`.PythonAccessorGenerator` class to read/write/print register and 

21 field values, you must implement the methods of this interface in a subclass. 

22 You must implement them to use whichever method you have available 

23 to access register values on your target (SSH, telnet, UART, ...). 

24 These details vary greatly in different projects, and is something that hdl-registers 

25 can not provide a generic solution for. 

26 

27 The byte address that shall be accessed, in both the methods, is 

28 

29 register_list_base_address + register_address 

30 

31 where ``register_list_base_address`` is the the base address of the requested register 

32 list on your register bus. 

33 Logic for finding this base address, probably using ``register_list_name``, must be 

34 implemented given the layout of your system. 

35 

36 You are free to raise any exceptions you want in your implementation of the methods. 

37 For example, unknown register list name, invalid address, timeout, bus error, etc. 

38 Exceptions will not be caught by :class:`.PythonAccessorGenerator` code, 

39 but will instead be propagated to the user wherever the accessor is used. 

40 """ 

41 

42 @abstractmethod 

43 def read_register(self, register_list_name: str, register_address: int) -> int: 

44 """ 

45 Read the value of a register. 

46 

47 Arguments: 

48 register_list_name: Name of the register list that the requested register belongs to. 

49 register_address: Byte address of the register, within the register list. 

50 Return: 

51 The register value that was read, as an unsigned 32-bit number. 

52 """ 

53 

54 @abstractmethod 

55 def write_register( 

56 self, register_list_name: str, register_address: int, register_value: int 

57 ) -> None: 

58 """ 

59 Write a register. 

60 

61 Arguments: 

62 register_list_name: Name of the register list that the requested register belongs to. 

63 register_address: Byte address of the register, within the register list. 

64 register_value: The value that shall be written, as an unsigned 32-bit number. 

65 """