cros_ec_python.ioports.winportio

This file provides a way to interact with the WinRing0 library for port I/O on Windows.

For this to work, you will need to copy WinRing0x64.dll and WinRing0x64.sys to either the same directory as python.exe, or to C:\Windows\System32.

  1"""
  2This file provides a way to interact with the WinRing0 library for port I/O on Windows.
  3
  4For this to work, you will need to copy `WinRing0x64.dll` and `WinRing0x64.sys` to either
  5the same directory as `python.exe`, or to `C:\\Windows\\System32`.
  6"""
  7
  8from enum import Enum
  9import ctypes
 10from ctypes import wintypes
 11
 12from .baseportio import PortIOClass
 13
 14
 15class WinPortIO(PortIOClass):
 16    """
 17    A class to interact with the WinRing0 library for port I/O on Windows.
 18    """
 19
 20    winring0: "ctypes.WinDLL | None" = None
 21    "The WinRing0 library instance."
 22
 23    def __init__(self):
 24        """
 25        Load and initialize the WinRing0 library.
 26        """
 27        self.winring0 = ctypes.WinDLL("WinRing0x64.dll")
 28        self.winring0.InitializeOls.restype = wintypes.BOOL
 29        self.winring0.GetDllStatus.restype = wintypes.DWORD
 30        self.winring0.DeinitializeOls.restype = None
 31        # ReadIoPort (port)
 32        self.winring0.ReadIoPortByte.restype = wintypes.BYTE
 33        self.winring0.ReadIoPortByte.argtypes = [wintypes.WORD]
 34        self.winring0.ReadIoPortWord.restype = wintypes.WORD
 35        self.winring0.ReadIoPortWord.argtypes = [wintypes.WORD]
 36        self.winring0.ReadIoPortDword.restype = wintypes.DWORD
 37        self.winring0.ReadIoPortDword.argtypes = [wintypes.WORD]
 38        # WriteIoPort (port, data)
 39        self.winring0.WriteIoPortByte.argtypes = [wintypes.WORD, wintypes.BYTE]
 40        self.winring0.WriteIoPortWord.argtypes = [wintypes.WORD, wintypes.WORD]
 41        self.winring0.WriteIoPortDword.argtypes = [wintypes.WORD, wintypes.DWORD]
 42
 43        self.winring0.InitializeOls()
 44        if error := self.winring0.GetDllStatus():
 45            raise OSError(f"WinRing0 Error: {self.Status(error)} ({error})")
 46
 47    def __del__(self):
 48        """
 49        Deinitialize the WinRing0 library.
 50        """
 51        if self.winring0:
 52            self.winring0.DeinitializeOls()
 53
 54    def outb(self, data: int, port: int) -> None:
 55        """
 56        Write a byte (8 bit) to the specified port.
 57        :param data: Byte to write.
 58        :param port: Port to write to.
 59        """
 60        self.winring0.WriteIoPortByte(port, data)
 61
 62    def outw(self, data: int, port: int) -> None:
 63        """
 64        Write a word (16 bit) to the specified port.
 65        :param data: Word to write.
 66        :param port: Port to write to.
 67        """
 68        self.winring0.WriteIoPortWord(port, data)
 69
 70    def outl(self, data: int, port: int) -> None:
 71        """
 72        Write a long (32 bit) to the specified port.
 73        :param data: Long to write.
 74        :param port: Port to write to.
 75        """
 76        self.winring0.WriteIoPortDword(port, data)
 77
 78    def inb(self, port: int) -> int:
 79        """
 80        Read a byte (8 bit) from the specified port.
 81        :param port: Port to read from.
 82        :return: Byte read.
 83        """
 84        return self.winring0.ReadIoPortByte(port)
 85
 86    def inw(self, port: int) -> int:
 87        """
 88        Read a word (16 bit) from the specified port.
 89        :param port: Port to read from.
 90        :return: Word read.
 91        """
 92        return self.winring0.ReadIoPortWord(port)
 93
 94    def inl(self, port: int) -> int:
 95        """
 96        Read a long (32 bit) from the specified port.
 97        :param port: Port to read from.
 98        :return: Long read.
 99        """
100        return self.winring0.ReadIoPortDword(port)
101
102    def ioperm(self, port: int, num: int, turn_on: bool) -> None:
103        """
104        `ioperm` stub function. It's not required for WinRing0.
105        """
106        pass
107
108    def iopl(self, level: int) -> None:
109        """
110        `iopl` stub function. It's not required for WinRing0.
111        """
112        pass
113
114    class Status(Enum):
115        """
116        WinRing0 status codes.
117        """
118
119        OLS_DLL_NO_ERROR = 0
120        OLS_DLL_UNSUPPORTED_PLATFORM = 1
121        OLS_DLL_DRIVER_NOT_LOADED = 2
122        OLS_DLL_DRIVER_NOT_FOUND = 3
123        OLS_DLL_DRIVER_UNLOADED = 4
124        OLS_DLL_DRIVER_NOT_LOADED_ON_NETWORK = 5
125        OLS_DLL_UNKNOWN_ERROR = 9
126
127        OLS_DLL_DRIVER_INVALID_PARAM = 10
128        OLS_DLL_DRIVER_SC_MANAGER_NOT_OPENED = 11
129        OLS_DLL_DRIVER_SC_DRIVER_NOT_INSTALLED = 12
130        OLS_DLL_DRIVER_SC_DRIVER_NOT_STARTED = 13
131        OLS_DLL_DRIVER_SC_DRIVER_NOT_REMOVED = 14
class WinPortIO(cros_ec_python.ioports.baseportio.PortIOClass): 
 16class WinPortIO(PortIOClass):
 17    """
 18    A class to interact with the WinRing0 library for port I/O on Windows.
 19    """
 20
 21    winring0: "ctypes.WinDLL | None" = None
 22    "The WinRing0 library instance."
 23
 24    def __init__(self):
 25        """
 26        Load and initialize the WinRing0 library.
 27        """
 28        self.winring0 = ctypes.WinDLL("WinRing0x64.dll")
 29        self.winring0.InitializeOls.restype = wintypes.BOOL
 30        self.winring0.GetDllStatus.restype = wintypes.DWORD
 31        self.winring0.DeinitializeOls.restype = None
 32        # ReadIoPort (port)
 33        self.winring0.ReadIoPortByte.restype = wintypes.BYTE
 34        self.winring0.ReadIoPortByte.argtypes = [wintypes.WORD]
 35        self.winring0.ReadIoPortWord.restype = wintypes.WORD
 36        self.winring0.ReadIoPortWord.argtypes = [wintypes.WORD]
 37        self.winring0.ReadIoPortDword.restype = wintypes.DWORD
 38        self.winring0.ReadIoPortDword.argtypes = [wintypes.WORD]
 39        # WriteIoPort (port, data)
 40        self.winring0.WriteIoPortByte.argtypes = [wintypes.WORD, wintypes.BYTE]
 41        self.winring0.WriteIoPortWord.argtypes = [wintypes.WORD, wintypes.WORD]
 42        self.winring0.WriteIoPortDword.argtypes = [wintypes.WORD, wintypes.DWORD]
 43
 44        self.winring0.InitializeOls()
 45        if error := self.winring0.GetDllStatus():
 46            raise OSError(f"WinRing0 Error: {self.Status(error)} ({error})")
 47
 48    def __del__(self):
 49        """
 50        Deinitialize the WinRing0 library.
 51        """
 52        if self.winring0:
 53            self.winring0.DeinitializeOls()
 54
 55    def outb(self, data: int, port: int) -> None:
 56        """
 57        Write a byte (8 bit) to the specified port.
 58        :param data: Byte to write.
 59        :param port: Port to write to.
 60        """
 61        self.winring0.WriteIoPortByte(port, data)
 62
 63    def outw(self, data: int, port: int) -> None:
 64        """
 65        Write a word (16 bit) to the specified port.
 66        :param data: Word to write.
 67        :param port: Port to write to.
 68        """
 69        self.winring0.WriteIoPortWord(port, data)
 70
 71    def outl(self, data: int, port: int) -> None:
 72        """
 73        Write a long (32 bit) to the specified port.
 74        :param data: Long to write.
 75        :param port: Port to write to.
 76        """
 77        self.winring0.WriteIoPortDword(port, data)
 78
 79    def inb(self, port: int) -> int:
 80        """
 81        Read a byte (8 bit) from the specified port.
 82        :param port: Port to read from.
 83        :return: Byte read.
 84        """
 85        return self.winring0.ReadIoPortByte(port)
 86
 87    def inw(self, port: int) -> int:
 88        """
 89        Read a word (16 bit) from the specified port.
 90        :param port: Port to read from.
 91        :return: Word read.
 92        """
 93        return self.winring0.ReadIoPortWord(port)
 94
 95    def inl(self, port: int) -> int:
 96        """
 97        Read a long (32 bit) from the specified port.
 98        :param port: Port to read from.
 99        :return: Long read.
100        """
101        return self.winring0.ReadIoPortDword(port)
102
103    def ioperm(self, port: int, num: int, turn_on: bool) -> None:
104        """
105        `ioperm` stub function. It's not required for WinRing0.
106        """
107        pass
108
109    def iopl(self, level: int) -> None:
110        """
111        `iopl` stub function. It's not required for WinRing0.
112        """
113        pass
114
115    class Status(Enum):
116        """
117        WinRing0 status codes.
118        """
119
120        OLS_DLL_NO_ERROR = 0
121        OLS_DLL_UNSUPPORTED_PLATFORM = 1
122        OLS_DLL_DRIVER_NOT_LOADED = 2
123        OLS_DLL_DRIVER_NOT_FOUND = 3
124        OLS_DLL_DRIVER_UNLOADED = 4
125        OLS_DLL_DRIVER_NOT_LOADED_ON_NETWORK = 5
126        OLS_DLL_UNKNOWN_ERROR = 9
127
128        OLS_DLL_DRIVER_INVALID_PARAM = 10
129        OLS_DLL_DRIVER_SC_MANAGER_NOT_OPENED = 11
130        OLS_DLL_DRIVER_SC_DRIVER_NOT_INSTALLED = 12
131        OLS_DLL_DRIVER_SC_DRIVER_NOT_STARTED = 13
132        OLS_DLL_DRIVER_SC_DRIVER_NOT_REMOVED = 14

A class to interact with the WinRing0 library for port I/O on Windows.

WinPortIO() 
24    def __init__(self):
25        """
26        Load and initialize the WinRing0 library.
27        """
28        self.winring0 = ctypes.WinDLL("WinRing0x64.dll")
29        self.winring0.InitializeOls.restype = wintypes.BOOL
30        self.winring0.GetDllStatus.restype = wintypes.DWORD
31        self.winring0.DeinitializeOls.restype = None
32        # ReadIoPort (port)
33        self.winring0.ReadIoPortByte.restype = wintypes.BYTE
34        self.winring0.ReadIoPortByte.argtypes = [wintypes.WORD]
35        self.winring0.ReadIoPortWord.restype = wintypes.WORD
36        self.winring0.ReadIoPortWord.argtypes = [wintypes.WORD]
37        self.winring0.ReadIoPortDword.restype = wintypes.DWORD
38        self.winring0.ReadIoPortDword.argtypes = [wintypes.WORD]
39        # WriteIoPort (port, data)
40        self.winring0.WriteIoPortByte.argtypes = [wintypes.WORD, wintypes.BYTE]
41        self.winring0.WriteIoPortWord.argtypes = [wintypes.WORD, wintypes.WORD]
42        self.winring0.WriteIoPortDword.argtypes = [wintypes.WORD, wintypes.DWORD]
43
44        self.winring0.InitializeOls()
45        if error := self.winring0.GetDllStatus():
46            raise OSError(f"WinRing0 Error: {self.Status(error)} ({error})")

Load and initialize the WinRing0 library.

winring0: 'ctypes.WinDLL | None' = None

The WinRing0 library instance.

def outb(self, data: int, port: int) -> None: 
55    def outb(self, data: int, port: int) -> None:
56        """
57        Write a byte (8 bit) to the specified port.
58        :param data: Byte to write.
59        :param port: Port to write to.
60        """
61        self.winring0.WriteIoPortByte(port, data)

Write a byte (8 bit) to the specified port.

Parameters
  • data: Byte to write.
  • port: Port to write to.
def outw(self, data: int, port: int) -> None: 
63    def outw(self, data: int, port: int) -> None:
64        """
65        Write a word (16 bit) to the specified port.
66        :param data: Word to write.
67        :param port: Port to write to.
68        """
69        self.winring0.WriteIoPortWord(port, data)

Write a word (16 bit) to the specified port.

Parameters
  • data: Word to write.
  • port: Port to write to.
def outl(self, data: int, port: int) -> None: 
71    def outl(self, data: int, port: int) -> None:
72        """
73        Write a long (32 bit) to the specified port.
74        :param data: Long to write.
75        :param port: Port to write to.
76        """
77        self.winring0.WriteIoPortDword(port, data)

Write a long (32 bit) to the specified port.

Parameters
  • data: Long to write.
  • port: Port to write to.
def inb(self, port: int) -> int: 
79    def inb(self, port: int) -> int:
80        """
81        Read a byte (8 bit) from the specified port.
82        :param port: Port to read from.
83        :return: Byte read.
84        """
85        return self.winring0.ReadIoPortByte(port)

Read a byte (8 bit) from the specified port.

Parameters
  • port: Port to read from.
Returns

Byte read.

def inw(self, port: int) -> int: 
87    def inw(self, port: int) -> int:
88        """
89        Read a word (16 bit) from the specified port.
90        :param port: Port to read from.
91        :return: Word read.
92        """
93        return self.winring0.ReadIoPortWord(port)

Read a word (16 bit) from the specified port.

Parameters
  • port: Port to read from.
Returns

Word read.

def inl(self, port: int) -> int: 
 95    def inl(self, port: int) -> int:
 96        """
 97        Read a long (32 bit) from the specified port.
 98        :param port: Port to read from.
 99        :return: Long read.
100        """
101        return self.winring0.ReadIoPortDword(port)

Read a long (32 bit) from the specified port.

Parameters
  • port: Port to read from.
Returns

Long read.

def ioperm(self, port: int, num: int, turn_on: bool) -> None: 
103    def ioperm(self, port: int, num: int, turn_on: bool) -> None:
104        """
105        `ioperm` stub function. It's not required for WinRing0.
106        """
107        pass

ioperm stub function. It's not required for WinRing0.

def iopl(self, level: int) -> None: 
109    def iopl(self, level: int) -> None:
110        """
111        `iopl` stub function. It's not required for WinRing0.
112        """
113        pass

iopl stub function. It's not required for WinRing0.

class WinPortIO.Status(enum.Enum): 
115    class Status(Enum):
116        """
117        WinRing0 status codes.
118        """
119
120        OLS_DLL_NO_ERROR = 0
121        OLS_DLL_UNSUPPORTED_PLATFORM = 1
122        OLS_DLL_DRIVER_NOT_LOADED = 2
123        OLS_DLL_DRIVER_NOT_FOUND = 3
124        OLS_DLL_DRIVER_UNLOADED = 4
125        OLS_DLL_DRIVER_NOT_LOADED_ON_NETWORK = 5
126        OLS_DLL_UNKNOWN_ERROR = 9
127
128        OLS_DLL_DRIVER_INVALID_PARAM = 10
129        OLS_DLL_DRIVER_SC_MANAGER_NOT_OPENED = 11
130        OLS_DLL_DRIVER_SC_DRIVER_NOT_INSTALLED = 12
131        OLS_DLL_DRIVER_SC_DRIVER_NOT_STARTED = 13
132        OLS_DLL_DRIVER_SC_DRIVER_NOT_REMOVED = 14

WinRing0 status codes.

OLS_DLL_NO_ERROR = <Status.OLS_DLL_NO_ERROR: 0>
OLS_DLL_UNSUPPORTED_PLATFORM = <Status.OLS_DLL_UNSUPPORTED_PLATFORM: 1>
OLS_DLL_DRIVER_NOT_LOADED = <Status.OLS_DLL_DRIVER_NOT_LOADED: 2>
OLS_DLL_DRIVER_NOT_FOUND = <Status.OLS_DLL_DRIVER_NOT_FOUND: 3>
OLS_DLL_DRIVER_UNLOADED = <Status.OLS_DLL_DRIVER_UNLOADED: 4>
OLS_DLL_DRIVER_NOT_LOADED_ON_NETWORK = <Status.OLS_DLL_DRIVER_NOT_LOADED_ON_NETWORK: 5>
OLS_DLL_UNKNOWN_ERROR = <Status.OLS_DLL_UNKNOWN_ERROR: 9>
OLS_DLL_DRIVER_INVALID_PARAM = <Status.OLS_DLL_DRIVER_INVALID_PARAM: 10>
OLS_DLL_DRIVER_SC_MANAGER_NOT_OPENED = <Status.OLS_DLL_DRIVER_SC_MANAGER_NOT_OPENED: 11>
OLS_DLL_DRIVER_SC_DRIVER_NOT_INSTALLED = <Status.OLS_DLL_DRIVER_SC_DRIVER_NOT_INSTALLED: 12>
OLS_DLL_DRIVER_SC_DRIVER_NOT_STARTED = <Status.OLS_DLL_DRIVER_SC_DRIVER_NOT_STARTED: 13>
OLS_DLL_DRIVER_SC_DRIVER_NOT_REMOVED = <Status.OLS_DLL_DRIVER_SC_DRIVER_NOT_REMOVED: 14>