renamed low-level i/o r/w functions and related docs

Author: psychogenic

README.md

@@ -446,9 +446,44 @@ tt.ui_in[4:2] = 0b101
 Again, it's worth noting that this acts as in verilog, so ui_in[4:2] includes bits 4,3 and 2.
 
 
+### Fast I/O
+
+All the I/O port abstractions and the cocotb compatibility aare nice, but sometimes there's a need for speed.
+
+To read or write a byte in a single, low-level, call, use the fast micropython native functions from the platform, e.g.
+
+```
+>>> import ttboard.util.platform as platform
+>>> platform.read_ui_in_byte()
+1
+>>> platform.write_ui_in_byte(4)
+>>> platform.read_ui_in_byte()
+4
+```
+
+The naming is read/write_u*_byte, so the available functions are
+
+  * read_ui_in_byte()
+  
+  * read_uio_byte()
+  
+  * read_uo_out_byte()
+  
+  * read_uio_outputenable()
+  
+  * write_ui_in_byte(VAL)
+  
+  * write_uio_byte(VAL)
+  
+  * write_uo_out_byte(VAL)
+  
+  * write_uio_outputenable(VAL)
+
+
+
 ### RP2040 pin objects
 
-It's recommended that you stick with reading and writing values using the u* ports as described above.
+It's recommended that you stick with reading and writing values using the u* ports or the low-level platform calls, as described above.
 
 Still, there may be cases where you want to play with micropython pin objects themselves, say to set pull-ups
 

src/ttboard/pins/pins.py

@@ -153,19 +153,19 @@ def _init_ioports(self):
         # Note: these are named according the the ASICs point of view
         # we can write ui_in, we read uo_out
         port_defs = [
-            ('uo_out',  8, platform.read_output_byte, None),
-            ('ui_in',   8, platform.read_input_byte, platform.write_input_byte),
-            ('uio_in',  8, platform.read_bidir_byte, platform.write_bidir_byte),
-            ('uio_out', 8, platform.read_bidir_byte, None)
+            ('uo_out',  8, platform.read_uo_out_byte, None),
+            ('ui_in',   8, platform.read_ui_in_byte, platform.write_ui_in_byte),
+            ('uio_in',  8, platform.read_uio_byte, platform.write_uio_byte),
+            ('uio_out', 8, platform.read_uio_byte, None)
             ]
         self._ports = dict()
         for pd in port_defs:
             setattr(self, pd[0], VerilogIOPort(*pd))
 
 
         self.uio_oe_pico = VerilogOEPort('uio_oe_pico', 8, 
-                                         platform.read_bidir_outputenable, 
-                                         platform.write_bidir_outputenable)
+                                         platform.read_uio_outputenable, 
+                                         platform.write_uio_outputenable)
 
 
 
@@ -199,8 +199,8 @@ def mode(self, set_mode:int):
         beginFunc = startupMap[set_mode]
         beginFunc()
         if set_mode == RPMode.ASIC_RP_CONTROL:
-            self.ui_in.byte_write = platform.write_input_byte
-            self.uio_in.byte_write = platform.write_bidir_byte
+            self.ui_in.byte_write = platform.write_ui_in_byte
+            self.uio_in.byte_write = platform.write_uio_byte
         else:
             self.ui_in.byte_write = None 
             self.uio_in.byte_write = None

src/ttboard/util/platform.py

@@ -117,7 +117,7 @@ def set_RP_system_clock(freqHz:int):
         machine.freq(int(freqHz))
 
     @micropython.native
-    def write_input_byte(val):
+    def write_ui_in_byte(val):
         # dump_portset('ui_in', val)
         # low level machine stuff
         # move the value bits to GPIO spots
@@ -131,12 +131,12 @@ def write_input_byte(val):
         machine.mem32[0xd000001c] = val
 
     @micropython.native
-    def read_input_byte():
+    def read_ui_in_byte():
         # just read the high and low nibbles from GPIO and combine into a byte
         return ( (machine.mem32[0xd0000004] & (0xf << 17)) >> (17-4)) | ((machine.mem32[0xd0000004] & (0xf << 9)) >> 9)
 
     @micropython.native
-    def write_bidir_byte(val):
+    def write_uio_byte(val):
         # dump_portset('uio', val)
         # low level machine stuff
         # move the value bits to GPIO spots
@@ -151,24 +151,24 @@ def write_bidir_byte(val):
 
 
     @micropython.native
-    def read_bidir_byte():
+    def read_uio_byte():
         return (machine.mem32[0xd0000004] & (0xff << 21)) >> 21
 
     @micropython.native
-    def read_bidir_outputenable():
+    def read_uio_outputenable():
         # GPIO_OE register, masked for our bidir pins
         return (machine.mem32[0xd0000020] & 0x1FE00000) >> 21
 
 
     @micropython.native
-    def write_bidir_outputenable(val):
+    def write_uio_outputenable(val):
         # dump_portset('uio_oe', val)
         # GPIO_OE register, clearing bidir pins and setting any enabled
         val = (val << 21)
         machine.mem32[0xd0000020] = (machine.mem32[0xd0000020] & ((1 << 21) - 1)) | val
 
     @micropython.native
-    def write_output_byte(val):
+    def write_uo_out_byte(val):
         # dump_portset('uo_out', val)
         # low level machine stuff
         # move the value bits to GPIO spots
@@ -181,7 +181,7 @@ def write_output_byte(val):
         machine.mem32[0xd000001c] = val
 
     @micropython.native
-    def read_output_byte():
+    def read_uo_out_byte():
 
         # sample code to deal with differences between 
         # PCBs, not actually required as we didn't move anything
@@ -228,47 +228,47 @@ def set_RP_system_clock(freqHz:int):
         RP2040SystemClockDefaultHz = freqHz
 
     _inbyte = 0
-    def write_input_byte(val):
+    def write_ui_in_byte(val):
         global _inbyte 
         print(f'Sim write_input_byte {val}')
         _inbyte = val
 
-    def read_input_byte():
+    def read_ui_in_byte():
         print('Sim read_output_byte')
         return _inbyte
 
 
     _uio_byte = 0
-    def write_bidir_byte(val):
+    def write_uio_byte(val):
         global _uio_byte
         print(f'Sim write_bidir_byte {val}')
         _uio_byte = val
 
 
 
-    def read_bidir_byte():
+    def read_uio_byte():
         print('Sim read_output_byte')
         return _uio_byte
 
     _outbyte = 0
-    def write_output_byte(val):
+    def write_uo_out_byte(val):
         global _outbyte 
         print(f'Sim write_output_byte {val}')
         _outbyte = val
 
-    def read_output_byte():
+    def read_uo_out_byte():
         global _outbyte 
         v = _outbyte 
         #_outbyte += 1
         print('Sim read_output_byte')
         return v
 
     _uio_oe_pico = 0
-    def read_bidir_outputenable():
+    def read_uio_outputenable():
         print('Sim read_bidir_outputenable')
         return _uio_oe_pico
 
-    def write_bidir_outputenable(val):
+    def write_uio_outputenable(val):
         global _uio_oe_pico
         print(f'Sim write_bidir_outputenable {val}')
         _uio_oe_pico = val