1.\" Copyright (c) 2001-2002 Maksim Yevmenkin <m_evmenkin@yahoo.com> 2.\" All rights reserved. 3.\" 4.\" Redistribution and use in source and binary forms, with or without 5.\" modification, are permitted provided that the following conditions 6.\" are met: 7.\" 1. Redistributions of source code must retain the above copyright 8.\" notice, this list of conditions and the following disclaimer. 9.\" 2. Redistributions in binary form must reproduce the above copyright 10.\" notice, this list of conditions and the following disclaimer in the 11.\" documentation and/or other materials provided with the distribution. 12.\" 13.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 14.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 15.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 16.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 17.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 18.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 19.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 20.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 21.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 22.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 23.\" SUCH DAMAGE. 24.\" 25.\" $Id: ng_ubt.4,v 1.3 2003/05/21 19:37:35 max Exp $ 26.\" $FreeBSD$ 27.\" 28.Dd June 14, 2002 29.Dt NG_UBT 4 30.Os 31.Sh NAME 32.Nm ng_ubt 33.Nd Netgraph node type that is also a driver for Bluetooth USB devices 34.Sh SYNOPSIS 35.In sys/types.h 36.In netgraph/bluetooth/include/ng_ubt.h 37.Sh DESCRIPTION 38The 39.Nm ubt 40node type is both a persistent Netgraph node type and a driver for 41Bluetooth USB devices. 42It implements a Bluetooth USB transport layer 43as per chapter H2 of the Bluetooth Specification Book v1.1. 44A new node is created when supported USB device is plugged. 45.Pp 46The node has a single hook called 47.Dv hook . 48Incoming bytes received on the device are re-assembled into HCI frames 49(according to the length). 50Full HCI frames are sent out on the hook. 51The node will add HCI frame indicator if device did not send it. 52HCI frames received on 53.Dv hook 54are transmitted out. 55The node will drop HCI frame indicator unless device 56requires it to be present. 57.Sh HOOKS 58This node type supports the following hooks: 59.Bl -tag -width indent 60.It Dv hook 61single HCI frame contained in single 62.Vt mbuf 63structure. 64.El 65.Sh CONTROL MESSAGES 66This node type supports the generic control messages, plus the following: 67.Bl -tag -width indent 68.It Dv NGM_UBT_NODE_GET_DEBUG 69Returns an integer containing the current debug level for the node. 70.It Dv NGM_UBT_NODE_SET_DEBUG 71This command takes an integer argument and sets current debug level 72for the node. 73.It Dv NGM_UBT_NODE_GET_QLEN 74This command takes a parameter that specifies queue number and returns 75current maximal length of the queue for the node. 76.It Dv NGM_UBT_NODE_SET_QLEN 77This command takes two parameters that specify queue number and maximum 78length of the queue and sets maximal length of the queue for the node. 79.It Dv NGM_UBT_NODE_GET_STAT 80Returns various statistic information for the node, such as: number of 81bytes (frames) sent, number of bytes (frames) received and number of 82input (output) errors. 83.It Dv NGM_UBT_NODE_RESET_STAT 84Reset all statistic counters to zero. 85.It Dv NGM_UBT_NODE_DEV_NODES 86This command takes single integer parameter. 87If the parameter's value is not zero, then the driver will create device nodes 88for the control, interrupt, bulk-in and bulk-out endpoints. 89If the parameter's value is zero, then the driver will destroy device nodes 90for the endpoints. 91The device nodes interface is mutually exclusive with Netgraph interface. 92.El 93.Sh DEVICE NODES INTERFACE 94The 95.Nm ubt 96driver can create or destroy endpoint device nodes on request. 97This feature can be used to implement external firmware download utility. 98.Pp 99The control transfers can only happen on the control endpoint which 100is always endpoint 0. 101Control requests are issued by 102.Xr ioctl 2 103calls. 104.Pp 105Only incoming transfers are supported on an interrupt endpoint. 106To perform I/O on an interrupt endpoint, 107.Xr read 2 108should be used. 109All I/O operations on an interrupt endpoint are unbuffered. 110.Pp 111The bulk transfers can be in or out depending on the endpoint. 112To perform I/O on a bulk endpoint, 113.Xr read 2 114and 115.Xr write 2 116should be used. 117All I/O operations on a bulk endpoint are unbuffered. 118.Pp 119The control endpoint (endpoint 0) handles the following 120.Xr ioctl 2 121calls: 122.Bl -tag -width indent 123.It Dv USB_GET_DEVICE_DESC Pq Vt usb_device_descriptor_t 124Return the device descriptor. 125.It Dv USB_GET_STRING_DESC Pq Vt "struct usb_string_desc" 126Get a string descriptor for the given language ID and string index. 127.Bd -literal 128struct usb_string_desc { 129 int string_index; 130 int language_id; 131 usb_string_descriptor_t desc; 132}; 133.Ed 134.It Dv USB_DO_REQUEST Pq Vt "struct usb_ctl_request" 135Send a USB request to the device on the control endpoint. 136Any data sent to/from the device is located at 137.Va data . 138The size of the transferred data is determined from the 139.Va request . 140The 141.Va addr 142field is ignored in this call. 143The 144.Va flags 145field can be used to flag that the request is allowed to 146be shorter than the requested size, and the 147.Va actlen 148will contain the actual size on completion. 149.Bd -literal 150struct usb_ctl_request { 151 int addr; 152 usb_device_request_t request; 153 void *data; 154 int flags; 155#define USBD_SHORT_XFER_OK 0x04 /* allow short reads */ 156 int actlen; /* actual length transferred */ 157}; 158.Ed 159This is a dangerous operation in that it can perform arbitrary operations 160on the device. 161Some of the most dangerous (e.g., changing the device address) are not allowed. 162.It Dv USB_GET_DEVICEINFO Pq Vt "struct usb_device_info" 163Get an information summary for the device. 164This call will not issue any USB transactions. 165.El 166.Sh SHUTDOWN 167This node shuts down when the corresponding USB device is un-plugged. 168.Sh BUGS 169Isochronous USB transfers are broken. 170It means that USB device will not be able to transfer SCO data (voice). 171USB interrupt transfers are implemented as bulk-in transfers (not really a bug). 172.Sh FILES 173.Bl -tag -width ".Pa /dev/ubt Ns Ar N Ns Pa \&. Ns Ar EE" -compact 174.It Pa /dev/ubt Ns Ar N Ns Pa \&. Ns Ar EE 175Endpoint 176.Ar EE 177of device 178.Ar N . 179.El 180.Sh SEE ALSO 181.Xr netgraph 4 , 182.Xr ugen 4 , 183.Xr usb 4 , 184.Xr ngctl 8 185.Sh HISTORY 186The 187.Nm ubt 188node type was implemented in 189.Fx 5.0 . 190.Sh AUTHORS 191.An Maksim Yevmenkin Aq m_evmenkin@yahoo.com 192