Improve documentation for Windows

Author: Steve-Tech

cros_ec_python/baseclass.py

@@ -3,7 +3,7 @@
 
 It doesn't do anything on its own, but it is used as a base for all CrosEc classes to inherit from.
 
-See `cros_ec_python.devices` for a few examples of a classes that inherits from this class.
+See `cros_ec_python.devices` for a few examples of a class that inherits from this class.
 """
 
 import abc

cros_ec_python/devices/__init__.py

@@ -6,7 +6,7 @@
 If you don't understand what this does, just use `cros_ec_python.cros_ec.get_cros_ec()` to pick an interface.
 
 All device class implementations should inherit from `cros_ec_python.baseclass.CrosEcClass`,
-and implement the methods described in that class. This allows everyone to use the standardised
+and implement the methods described in that class. This allows everything to use the standardised
 `cros_ec_python.baseclass.CrosEcClass.command` method to send commands to the EC, and
 `cros_ec_python.baseclass.CrosEcClass.memmap` to read memory from the EC.
 
@@ -17,17 +17,18 @@
 **Initialisation**
 
 ```python
-from cros_ec_python import get_cros_ec, CrosEcLpc, CrosEcDev
-
 # Pick one of the following:
 
 # Automatically pick the right class
+from cros_ec_python import get_cros_ec
 ec = get_cros_ec()
 
 # Manually pick LinuxDev
+from cros_ec_python import CrosEcDev
 ec = CrosEcDev()
 
 # Manually pick LPC
+from cros_ec_python import CrosEcLpc
 ec = CrosEcLpc()
 
 # Manually pick LPC with a specific address

cros_ec_python/ioports/__init__.py

@@ -1,15 +1,70 @@
 """
-This module is used to import the correct portio module based on the OS.
+# Description
+
+This submodule contains the classes for the different IO port interfaces supported by the library.
+
+If you don't understand what this does, just use `cros_ec_python.ioports.PortIO()` to import the correct class.
+
+All IO port classes should inherit from `cros_ec_python.ioports.baseportio.PortIOClass`,
+and implement the methods described in that class. This allows everything to use the standardised
+methods to interact with the IO ports in a platform-independent way.
+
+## Examples
+
+**Initialisation**
+
+```python
+# Automatically pick the right class (Recommended)
+from cros_ec_python.ioports import PortIO
+portio = PortIO()
+
+# Manually pick portio library (Linux, preferred)
+from cros_ec_python.ioports.x86portio import IoPortIo
+portio = IoPortIo()
+
+# Manually pick `/dev/port` (Linux, fallback)
+from cros_ec_python.ioports.devportio import DevPortIO
+portio = DevPortIO()
+
+# Manually pick WinRing0 (Windows)
+from cros_ec_python.ioports.winportio import WinPortIO
+portio = WinPortIO()
+```
+
+**Reading from a port**
+
+```python
+# Assuming `portio` is already initialised
+data = portio.inb(0x80)
+print(data)
+```
+
+**Writing to a port**
+
+```python
+# Assuming `portio` is already initialised
+portio.outb(0x55, 0x80)
+```
+
+See `cros_ec_python.ioports.baseportio.PortIOClass` for the full list of common methods.
+
+Some classes may have additional methods, such as `cros_ec_python.ioports.x86portio.IoPortIo`.
 """
 
 import os
 
-if os.name == "nt":
-    from .winportio import WinPortIO as PortIO
-elif os.name == "posix":
+if os.name == "posix":
     try:
         from .x86portio import IoPortIo as PortIO
     except ImportError:
         from .devportio import DevPortIO as PortIO
+elif os.name == "nt":
+    from .winportio import WinPortIO as PortIO
 else:
     raise Exception("Unsupported OS")
+
+# This is for pdoc
+from .baseportio import PortIOClass
+
+PortIO: PortIOClass
+"Automatically picked IO port class."

cros_ec_python/ioports/baseportio.py

@@ -3,7 +3,7 @@
 
 It doesn't do anything on its own, but it is used as a base for all port I/O backends to inherit from.
 
-See `cros_ec_python.io` for a few examples of a classes that inherits from this class.
+See `cros_ec_python.ioports` for a few examples of a class that inherits from this class.
 """
 
 import abc

cros_ec_python/ioports/winportio.py

@@ -7,6 +7,7 @@
 
 from enum import Enum
 import ctypes
+from ctypes import wintypes
 
 from .baseportio import PortIOClass
 
@@ -16,27 +17,28 @@ class WinPortIO(PortIOClass):
     A class to interact with the WinRing0 library for port I/O on Windows.
     """
 
-    winring0 = None
+    winring0: "ctypes.WinDLL | None" = None
+    "The WinRing0 library instance."
 
     def __init__(self):
         """
         Load and initialize the WinRing0 library.
         """
         self.winring0 = ctypes.WinDLL("WinRing0x64.dll")
-        self.winring0.InitializeOls.restype = ctypes.c_bool
-        self.winring0.GetDllStatus.restype = ctypes.c_ulong
+        self.winring0.InitializeOls.restype = wintypes.BOOL
+        self.winring0.GetDllStatus.restype = wintypes.DWORD
         self.winring0.DeinitializeOls.restype = None
         # ReadIoPort (port)
-        self.winring0.ReadIoPortByte.restype = ctypes.c_ubyte
-        self.winring0.ReadIoPortByte.argtypes = [ctypes.c_ushort]
-        self.winring0.ReadIoPortWord.restype = ctypes.c_ushort
-        self.winring0.ReadIoPortWord.argtypes = [ctypes.c_ushort]
-        self.winring0.ReadIoPortDword.restype = ctypes.c_ulong
-        self.winring0.ReadIoPortDword.argtypes = [ctypes.c_ushort]
+        self.winring0.ReadIoPortByte.restype = wintypes.BYTE
+        self.winring0.ReadIoPortByte.argtypes = [wintypes.WORD]
+        self.winring0.ReadIoPortWord.restype = wintypes.WORD
+        self.winring0.ReadIoPortWord.argtypes = [wintypes.WORD]
+        self.winring0.ReadIoPortDword.restype = wintypes.DWORD
+        self.winring0.ReadIoPortDword.argtypes = [wintypes.WORD]
         # WriteIoPort (port, data)
-        self.winring0.WriteIoPortByte.argtypes = [ctypes.c_ushort, ctypes.c_ubyte]
-        self.winring0.WriteIoPortWord.argtypes = [ctypes.c_ushort, ctypes.c_ushort]
-        self.winring0.WriteIoPortDword.argtypes = [ctypes.c_ushort, ctypes.c_ulong]
+        self.winring0.WriteIoPortByte.argtypes = [wintypes.WORD, wintypes.BYTE]
+        self.winring0.WriteIoPortWord.argtypes = [wintypes.WORD, wintypes.WORD]
+        self.winring0.WriteIoPortDword.argtypes = [wintypes.WORD, wintypes.DWORD]
 
         self.winring0.InitializeOls()
         if error := self.winring0.GetDllStatus():
@@ -49,21 +51,6 @@ def __del__(self):
         if self.winring0:
             self.winring0.DeinitializeOls()
 
-    class Status(Enum):
-        OLS_DLL_NO_ERROR = 0
-        OLS_DLL_UNSUPPORTED_PLATFORM = 1
-        OLS_DLL_DRIVER_NOT_LOADED = 2
-        OLS_DLL_DRIVER_NOT_FOUND = 3
-        OLS_DLL_DRIVER_UNLOADED = 4
-        OLS_DLL_DRIVER_NOT_LOADED_ON_NETWORK = 5
-        OLS_DLL_UNKNOWN_ERROR = 9
-
-        OLS_DLL_DRIVER_INVALID_PARAM = 10
-        OLS_DLL_DRIVER_SC_MANAGER_NOT_OPENED = 11
-        OLS_DLL_DRIVER_SC_DRIVER_NOT_INSTALLED = 12
-        OLS_DLL_DRIVER_SC_DRIVER_NOT_STARTED = 13
-        OLS_DLL_DRIVER_SC_DRIVER_NOT_REMOVED = 14
-
     def outb(self, data: int, port: int) -> None:
         """
         Write a byte (8 bit) to the specified port.
@@ -123,3 +110,22 @@ def iopl(self, level: int) -> None:
         `iopl` stub function. It's not required for WinRing0.
         """
         pass
+
+    class Status(Enum):
+        """
+        WinRing0 status codes.
+        """
+
+        OLS_DLL_NO_ERROR = 0
+        OLS_DLL_UNSUPPORTED_PLATFORM = 1
+        OLS_DLL_DRIVER_NOT_LOADED = 2
+        OLS_DLL_DRIVER_NOT_FOUND = 3
+        OLS_DLL_DRIVER_UNLOADED = 4
+        OLS_DLL_DRIVER_NOT_LOADED_ON_NETWORK = 5
+        OLS_DLL_UNKNOWN_ERROR = 9
+
+        OLS_DLL_DRIVER_INVALID_PARAM = 10
+        OLS_DLL_DRIVER_SC_MANAGER_NOT_OPENED = 11
+        OLS_DLL_DRIVER_SC_DRIVER_NOT_INSTALLED = 12
+        OLS_DLL_DRIVER_SC_DRIVER_NOT_STARTED = 13
+        OLS_DLL_DRIVER_SC_DRIVER_NOT_REMOVED = 14