ng_ubt(4) no longer provides device nodes interface. Update the

man page to document this.

MFC after:	3 days

3 files changed, 155 insertions, 88 deletions

diff --git a/share/man/man4/Makefile b/share/man/man4/Makefile
index a6d3b62..8efe54c 100644
--- a/share/man/man4/Makefile
+++ b/share/man/man4/Makefile
@@ -331,6 +331,7 @@ MAN=	aac.4 \
 	vge.4 \
 	vinum.4 \
 	vinumdebug.4 \
+	vkbd.4 \
 	vlan.4 \
 	vpo.4 \
 	vr.4 \
diff --git a/share/man/man4/ng_ubt.4 b/share/man/man4/ng_ubt.4
index 75e3113..4083a45 100644
--- a/share/man/man4/ng_ubt.4
+++ b/share/man/man4/ng_ubt.4
@@ -102,86 +102,6 @@ bytes (frames) sent, number of bytes (frames) received and number of
 input (output) errors.
 .It Dv NGM_UBT_NODE_RESET_STAT
 Reset all statistic counters to zero.
-.It Dv NGM_UBT_NODE_DEV_NODES
-This command takes a single integer parameter.
-If the parameter's value is not zero, then the driver will create device nodes
-for the control, interrupt, bulk-in and bulk-out endpoints.
-If the parameter's value is zero, then the driver will destroy the device nodes
-for the endpoints.
-The device nodes interface is mutually exclusive with the Netgraph interface.
-.El
-.Sh DEVICE NODES INTERFACE
-The
-.Nm ubt
-driver can create or destroy endpoint device nodes on request.
-This feature can be used to implement an external firmware download utility.
-.Pp
-Control transfers can only happen on the control endpoint which
-is always endpoint 0.
-Control requests are issued by
-.Xr ioctl 2
-calls.
-.Pp
-Only incoming transfers are supported on an interrupt endpoint.
-To perform I/O on an interrupt endpoint,
-.Xr read 2
-should be used.
-All I/O operations on an interrupt endpoint are unbuffered.
-.Pp
-The bulk transfers can be in or out depending on the endpoint.
-To perform I/O on a bulk endpoint,
-.Xr read 2
-and
-.Xr write 2
-should be used.
-All I/O operations on a bulk endpoint are unbuffered.
-.Pp
-The control endpoint (endpoint 0) handles the following
-.Xr ioctl 2
-calls:
-.Bl -tag -width indent
-.It Dv USB_GET_DEVICE_DESC Pq Vt usb_device_descriptor_t
-Return the device descriptor.
-.It Dv USB_GET_STRING_DESC Pq Vt "struct usb_string_desc"
-Get a string descriptor for the given language ID and string index.
-.Bd -literal
-struct usb_string_desc {
-        int                     string_index;
-        int                     language_id;
-        usb_string_descriptor_t desc;
-};
-.Ed
-.It Dv USB_DO_REQUEST Pq Vt "struct usb_ctl_request"
-Send a USB request to the device on the control endpoint.
-Any data sent to/from the device is located at
-.Va data .
-The size of the transferred data is determined from the
-.Va request .
-The
-.Va addr
-field is ignored in this call.
-The
-.Va flags
-field can be used to flag that the request is allowed to
-be shorter than the requested size, and the
-.Va actlen
-will contain the actual size on completion.
-.Bd -literal
-struct usb_ctl_request {
-        int                  addr;
-        usb_device_request_t request;
-        void                 *data;
-        int                  flags;
-#define USBD_SHORT_XFER_OK   0x04    /* allow short reads */
-        int                  actlen; /* actual length transferred */
-};
-.Ed
-This is a dangerous operation in that it can perform arbitrary operations
-on the device.
-Some of the most dangerous (e.g., changing the device address) are not allowed.
-.It Dv USB_GET_DEVICEINFO Pq Vt "struct usb_device_info"
-Get an information summary for the device.
-This call will not issue any USB transactions.
 .El
 .Sh SHUTDOWN
 This node shuts down when the corresponding USB device is un-plugged.
@@ -189,14 +109,6 @@ This node shuts down when the corresponding USB device is un-plugged.
 Isochronous USB transfers are broken.
 This means that the USB device will not be able to transfer SCO data (voice).
 USB interrupt transfers are implemented as bulk-in transfers (not really a bug).
-.Sh FILES
-.Bl -tag -width ".Pa /dev/ubt Ns Ar N Ns Pa \&. Ns Ar EE" -compact
-.It Pa /dev/ubt Ns Ar N Ns Pa \&. Ns Ar EE
-Endpoint
-.Ar EE
-of device
-.Ar N .
-.El
 .Sh SEE ALSO
 .Xr netgraph 4 ,
 .Xr ugen 4 ,
diff --git a/share/man/man4/vkbd.4 b/share/man/man4/vkbd.4
new file mode 100644
index 0000000..9c003d0
--- /dev/null
+++ b/share/man/man4/vkbd.4
@@ -0,0 +1,154 @@
+.\" $Id: vkbd.4,v 1.3 2004/08/13 18:23:53 max Exp $
+.\" $FreeBSD$
+.\"
+.Dd August 12, 2004
+.Os
+.Dt VKBD 4
+.Sh NAME
+.Nm vkbd
+.Nd the virtual AT keyboard interface
+.Sh SYNOPSIS
+.Cd device vkbd
+.Sh DESCRIPTION
+The
+.Nm
+interface is a software loopback mechanism that can be loosely
+described as the virtual AT keyboard analog of the
+.Xr pty 4 ,
+that is,
+.Nm
+does for virtual AT keyboards what the
+.Nm pty
+driver does for terminals.
+.Pp
+The
+.Nm
+driver, like the
+.Nm pty
+driver, provides two interfaces: a keyboard interface like the usual
+facility it is simulating (a virtual AT keyboard in the case of
+.Nm ,
+or a terminal for
+.Nm pty ) ,
+and a character-special device
+.Dq control
+interface.
+.Pp
+The virtual AT keyboards are named
+.Dq Li vkbd0 ,
+.Dq Li vkbd1 ,
+etc., one for each control device that has been opened.
+.Pp
+The
+.Nm
+interface permits opens on the special control device
+.Pa /dev/vkbdctl .
+When this device is opened,
+.Nm
+will return a handle for the lowest unused
+.Nm vkbdctl
+device (use
+.Xr devname 3
+to determine which).
+.Pp
+Each virtual AT keyboad supports the usual keyboard interface
+.Xr ioctl 2 Ns s ,
+and thus can be used with
+.Xr kbdcontrol 1
+like any other keyboard.
+The control device supports exactly the same
+.Xr ioctl 2 Ns s
+as the virtual AT keyboad device.
+Writing AT scan codes to the control device generates an input on
+the virtual AT keyboard, as if the
+(non-existent)
+hardware had just received it.
+.Pp
+The virtual AT kerboard control device, normally
+.Pa /dev/vkbdctl Ns Sy N ,
+is exclusive-open
+(it cannot be opened if it is already open)
+and is restricted to the super-user.
+A
+.Fn read
+call will return the virtual AT keyboard status structure
+(defined in
+.In dev/vkbd/vkbd_var.h )
+if one is available;
+if not, it will either block until one is or return
+.Er EWOULDBLOCK ,
+depending on whether non-blocking I/O has been enabled.
+.Pp
+A
+.Xr write 2
+call passes AT scan codes to be
+.Dq received
+from the virtual AT keyboard.
+Each AT scan code must be passed as unsigned
+.Vt int .
+Although AT scan codes must be passes as unsigned
+.Vt int Ns s ,
+the size of the buffer passed to
+.Xr write 2
+still should be in bytes, i.e.
+.Bd -literal -offset indent
+static unsigned int     codes[] =
+{
+/*      Make    Break */
+        0x1e,   0x9e
+};
+
+int
+main(void)
+{
+        int     fd, len;
+
+        fd = open("/dev/vkbdctl0", O_RDWR);
+        if (fd < 0)
+                err(1, "open");
+
+        /* Note sizeof(codes) - not 2! */
+        len = write(fd, codes, sizeof(codes));
+        if (len < 0)
+                err(1, "write");
+
+        close(fd);
+
+        return (0);
+}
+.Ed
+.Pp
+Write will block if there is not enough space in the input queue.
+.Pp
+The control device also supports
+.Xr select 2
+for read and write.
+.Pp
+On the last close of the control device, the virtual AT keyboard is removed.
+All queued scan codes are thrown away.
+.Sh SEE ALSO
+.Xr kbdcontrol 1 ,
+.Xr atkbdc 4 ,
+.Xr pcvt 4 ,
+.Xr psm 4 ,
+.Xr syscons 4
+.Sh CAVEAT
+The
+.Nm
+interface is a software loopback mechanism, and, thus
+.Xr ddb 4
+will not work with it.
+Current implementation of the
+.Xr syscons 4
+driver can accept input from only one keyboard, even if it is virtual.
+Thus is it not possible to have both wired and virtual keyboard to be active
+at the same time. It is, however, in principal possible to obtain AT scan
+codes from the different sources and write them into the same virtual keyboard.
+The virtual keyboard state synchronization is the user's responsibility.
+.Sh HISTORY
+The
+.Nm
+module was implemented in
+.Fx 5.0 .
+.Sh AUTHORS
+.An Maksim Yevmenkin Aq m_evmenkin@yahoo.com