# HG changeset patch
# User William Astle <lost@l-w.ca>
# Date 1465665229 21600
# Node ID 3a4c972c92ec556d048f98e2b33562bd235fa874
# Parent  422f5e8fff85b74eb4a3258bd63d445fd014feec
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.

diff -r 422f5e8fff85 -r 3a4c972c92ec docs/extension-virtualports.txt
--- 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.
+