Skip to content

W
White Rabbit Trigger Distribution
Commit d49642ed authored by Dimitris Lampridis's avatar Dimitris Lampridis
Browse files
Options

doc: document Python wrapper class

parent 2d960e1f
Hide whitespace changes
Inline Side-by-side
Showing with 163 additions and 10 deletions
software/lib/python/PyWrtd.py
View file @ d49642ed
"""
@package docstring
@copyright: Copyright (c) 2019 CERN (home.cern)
Wrapper for WRTD C library using ctypes.
All ctypes functions have exactly the same names as the ones in the
C library. To each C function corresponds a Python function that hides
C specific operations from the user. The names of these functions are
the sames as the ctypes functions without the WRTD prefix.
Copyright (c) 2019 CERN (home.cern)
SPDX-License-Identifier: LGPL-3.0-or-later
"""
import sys
import decorator
from ctypes import *
""" Wrapper for WRTD C library using ctypes
All ctypes functions have exactly the same names as the ones in the
C library. To each C function corresponds a Python function that hides
C specific operations from the user. The names of these functions are
the sames as the ctypes functions without the WRTD prefix."""
class wrtd_dev(Structure):
pass
......@@ -31,6 +34,7 @@ class wrtd_tstamp(Structure):
yield 'ns' , self.ns
yield 'frac' , self.seconds
@decorator.decorator
def encode_arguments(func):
"""Used to convert arguments from strings to bytes"""
def wrapper(self, *args, **kwargs):
......@@ -45,6 +49,15 @@ def encode_arguments(func):
return wrapper
class PyWrtd():
"""Top-level Python wrapper class for WRTD library.
:ref:`api_error_codes` and :ref:`api_attr_id` are the same as in the WRTD library.
:param resource_name: Underlying MockTurtle device ID in the form of ``MTxxx`` or\
``trtl-xxxx``. See also :ref:`res_names`.
"""
WRTD_SUCCESS = 0
__WRTD_ERROR_BASE = 0xBFFA0000
WRTD_ERROR_INVALID_ATTRIBUTE = __WRTD_ERROR_BASE + 0x0C
......@@ -265,9 +278,15 @@ class PyWrtd():
self.wrtd_p = 0
def reset(self):
"""
Corresponds to C library :cpp:func:`wrtd_reset`.
"""
self.wrtd_lib.wrtd_reset(self.wrtd_p)
def get_error(self):
"""
Corresponds to C library :cpp:func:`wrtd_get_error`.
"""
buf_size = self.wrtd_lib.wrtd_get_error(self.wrtd_p, None, 0, None)
error_description = create_string_buffer(buf_size)
error_c = c_int()
......@@ -276,6 +295,13 @@ class PyWrtd():
return error_c.value, error_description.value.decode('ascii')
def error_message(self, err_code):
"""
Corresponds to C library :cpp:func:`wrtd_error_message`.
:param err_code: error code to convert
:return: error message (string)
"""
error_message = create_string_buffer(256)
self.wrtd_lib.wrtd_error_message(self.wrtd_p, err_code,
error_message)
......@@ -283,11 +309,26 @@ class PyWrtd():
@encode_arguments
def set_attr_bool(self, rep_cap_id, id, value):
"""
Corresponds to C library :cpp:func:`wrtd_set_attr_bool`.
:param rep_cap_id: :ref:`rep_cap_id`
:param id: ID of concerned :ref:`attribute`
:param value: Value to write to the :ref:`attribute`
"""
self.wrtd_lib.wrtd_set_attr_bool(self.wrtd_p, rep_cap_id,
id, value)
@encode_arguments
def get_attr_bool(self, rep_cap_id, id):
"""
Corresponds to C library :cpp:func:`wrtd_get_attr_bool`.
:param rep_cap_id: :ref:`rep_cap_id`
:param id: ID of concerned :ref:`attribute`
:return: Retrieved attribute value
"""
value = c_bool()
self.wrtd_lib.wrtd_get_attr_bool(self.wrtd_p, rep_cap_id,
id, byref(value))
......@@ -295,11 +336,26 @@ class PyWrtd():
@encode_arguments
def set_attr_int32(self, rep_cap_id, id, value):
"""
Corresponds to C library :cpp:func:`wrtd_set_attr_int32`.
:param rep_cap_id: :ref:`rep_cap_id`
:param id: ID of concerned :ref:`attribute`
:param value: Value to write to the :ref:`attribute`
"""
self.wrtd_lib.wrtd_set_attr_int32(self.wrtd_p, rep_cap_id,
id, value)
@encode_arguments
def get_attr_int32(self, rep_cap_id, id):
"""
Corresponds to C library :cpp:func:`wrtd_get_attr_int32`.
:param rep_cap_id: :ref:`rep_cap_id`
:param id: ID of concerned :ref:`attribute`
:return: Retrieved attribute value
"""
value = c_int32()
self.wrtd_lib.wrtd_get_attr_int32(self.wrtd_p, rep_cap_id,
id, byref(value))
......@@ -307,11 +363,26 @@ class PyWrtd():
@encode_arguments
def set_attr_string(self, rep_cap_id, id, value):
"""
Corresponds to C library :cpp:func:`wrtd_set_attr_string`.
:param rep_cap_id: :ref:`rep_cap_id`
:param id: ID of concerned :ref:`attribute`
:param value: Value to write to the :ref:`attribute`
"""
self.wrtd_lib.wrtd_set_attr_string(self.wrtd_p, rep_cap_id,
id, value)
@encode_arguments
def get_attr_string(self, rep_cap_id, id):
"""
Corresponds to C library :cpp:func:`wrtd_get_attr_string`.
:param rep_cap_id: :ref:`rep_cap_id`
:param id: ID of concerned :ref:`attribute`
:return: Retrieved attribute value
"""
buf_size = self.wrtd_lib.wrtd_get_attr_string(self.wrtd_p,
rep_cap_id, id,
0, None)
......@@ -323,21 +394,45 @@ class PyWrtd():
@encode_arguments
def set_attr_tstamp(self, rep_cap_id, id,
seconds = 0, ns = 0, frac = 0):
"""
Corresponds to C library :cpp:func:`wrtd_set_attr_tstamp`.
:param rep_cap_id: :ref:`rep_cap_id`
:param id: ID of concerned :ref:`attribute`
:param seconds: Seconds value to write to the :ref:`attribute`
:param ns: Nanoseconds value to write to the :ref:`attribute`
:param frac: Fractional nanoseconds value to write to the :ref:`attribute`
"""
tstamp = wrtd_tstamp(seconds, ns, frac)
self.wrtd_lib.wrtd_set_attr_tstamp(self.wrtd_p, rep_cap_id,
id, byref(tstamp))
@encode_arguments
def get_attr_tstamp(self, rep_cap_id, id):
"""
Corresponds to C library :cpp:func:`wrtd_get_attr_tstamp`.
:param rep_cap_id: :ref:`rep_cap_id`
:param id: ID of concerned :ref:`attribute`
:return: Retrieved attribute value\
(Python dictionary with ``seconds``, ``ns`` and ``frac`` keys)
"""
tstamp = wrtd_tstamp()
self.wrtd_lib.wrtd_get_attr_tstamp(self.wrtd_p, rep_cap_id,
id, byref(tstamp))
return dict(tstamp)
def clear_event_log_entries(self):
"""
Corresponds to C library :cpp:func:`wrtd_clear_event_log_entries`.
"""
self.wrtd_lib.clear_event_log_entries(self.wrtd_p)
def get_next_event_log_entry(self):
"""
Corresponds to C library :cpp:func:`wrtd_get_next_event_log_entry`.
"""
buf_size = self.WRTD_LOG_ENTRY_SIZE
log_entry = create_string_buffer(buf_size)
self.wrtd_lib.wrtd_get_next_event_log_entry(self.wrtd_p,
......@@ -347,19 +442,42 @@ class PyWrtd():
@encode_arguments
def add_alarm(self, rep_cap_id):
"""
Corresponds to C library :cpp:func:`wrtd_add_alarm`.
:param rep_cap_id: :ref:`rep_cap_id` of new :ref:`alarm`
"""
self.wrtd_lib.wrtd_add_alarm(self.wrtd_p, rep_cap_id)
def disable_all_alarms(self):
"""
Corresponds to C library :cpp:func:`wrtd_disable_all_alarms`.
"""
self.wrtd_lib.wrtd_disable_all_alarms(self.wrtd_p)
@encode_arguments
def remove_alarm(self, rep_cap_id):
"""
Corresponds to C library :cpp:func:`wrtd_remove_alarm`.
:param rep_cap_id: :ref:`rep_cap_id` of :ref:`alarm` to remove
"""
self.wrtd_lib.wrtd_remove_alarm(self.wrtd_p, rep_cap_id)
def remove_all_rules(self):
self.wrtd_lib.wrtd_remove_all_rules(self.wrtd_p)
def remove_all_alarms(self):
"""
Corresponds to C library :cpp:func:`wrtd_remove_all_alarms`.
"""
self.wrtd_lib.wrtd_remove_all_alarms(self.wrtd_p)
def get_alarm_name(self, index):
"""
Corresponds to C library :cpp:func:`wrtd_get_alarm_name`.
:param index: Index of the :ref:`alarm`
:return: :ref:`rep_cap_id` of the :ref:`alarm`
"""
buf_size = self.wrtd_lib.wrtd_get_alarm_name(self.wrtd_p,
index,
0, None)
......@@ -370,19 +488,42 @@ class PyWrtd():
@encode_arguments
def add_rule(self, rep_cap_id):
"""
Corresponds to C library :cpp:func:`wrtd_add_rule`.
:param rep_cap_id: :ref:`rep_cap_id` of new :ref:`rule`
"""
self.wrtd_lib.wrtd_add_rule(self.wrtd_p, rep_cap_id)
def disable_all_rules(self):
"""
Corresponds to C library :cpp:func:`wrtd_disable_all_alarms`.
"""
self.wrtd_lib.wrtd_disable_all_rules(self.wrtd_p)
@encode_arguments
def remove_rule(self, rep_cap_id):
"""
Corresponds to C library :cpp:func:`wrtd_remove_rule`.
:param rep_cap_id: :ref:`rep_cap_id` of :ref:`rule` to remove
"""
self.wrtd_lib.wrtd_remove_rule(self.wrtd_p, rep_cap_id)
def remove_all_rules(self):
"""
Corresponds to C library :cpp:func:`wrtd_remove_all_rules`.
"""
self.wrtd_lib.wrtd_remove_all_rules(self.wrtd_p)
def get_rule_name(self, index):
"""
Corresponds to C library :cpp:func:`wrtd_get_rule_name`.
:param index: Index of the :ref:`rule`
:return: :ref:`rep_cap_id` of the :ref:`rule`
"""
buf_size = self.wrtd_lib.wrtd_get_rule_name(self.wrtd_p,
index,
0, None)
......@@ -393,9 +534,21 @@ class PyWrtd():
@encode_arguments
def reset_rule_stats(self, rep_cap_id):
"""
Corresponds to C library :cpp:func:`wrtd_reset_rule_stats`.
:param rep_cap_id: :ref:`rep_cap_id` of the :ref:`rule` to reset its statistics
"""
self.wrtd_lib.wrtd_reset_rule_stats(self.wrtd_p, rep_cap_id)
def get_fw_name(self, index):
"""
Corresponds to C library :cpp:func:`wrtd_get_fw_name`.
:param index: Index of the :ref:`application`
:return: :ref:`rep_cap_id` of the :ref:`application`
"""
buf_size = self.wrtd_lib.wrtd_get_fw_name(self.wrtd_p,
index,
0, None)
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment