changeset 6:3a4c972c92ec

Add non-variable packet READ option It is clear that variable packets are inconvenient on high speed bitbanger implementations of the lwwire protocol. This update provides an alternative to the variable length READ option that does not require the use of variable length packets.
author William Astle <lost@l-w.ca>
date Sat, 11 Jun 2016 11:13:49 -0600
parents 422f5e8fff85
children 2e382e1a173e
files docs/extension-virtualports.txt
diffstat 1 files changed, 36 insertions(+), 0 deletions(-) [+]
line wrap: on
line diff
--- a/docs/extension-virtualports.txt	Sun May 29 21:59:29 2016 -0600
+++ b/docs/extension-virtualports.txt	Sat Jun 11 11:13:49 2016 -0600
@@ -165,3 +165,39 @@
 appropriate.
 
 
+06 VPORT_READFIXED
+
+This request reads bytes from a virtual port. The request looks as follows:
+
+Octet	Meaning
+-----	-------
+0-2	F3 00 04
+3	port number
+4	size to read in octets (N)
+
+The response is looks as follows:
+
+Octet	Meaning
+-----	-------
+0	status
+1	number of bytes returned (n)
+2-...	returned data
+
+In all cases, there will be exactly N octets in the returned data. Any bytes
+not filled by actual data are undefined but should be zero.
+
+If status is nonzero, then the read failed. This will usually be due to a
+lack of data (1) OR the port not being open (2). In this case, any
+subsequent octets in the packet can be ignored.
+
+If (n) is less than (N), then there will be extra octets in the returned
+data section which must be ignored.
+
+This option is provided as an alternative to the VPORT_READ call for systems
+which cannot easily handle a variable length packet safely. In particular, a
+115k "bitbanger" implementation on the Coco itself might choose to use this
+option to adding another 500+ bytes to its lwwire client driver. Ohter
+communication channels that do not have this limitation should prefer the
+variable length packet option with larger request sizes to minimize
+transaction count.
+