home | help 
NG_UBT(4)		     Kernel Interfaces Manual		       NG_UBT(4)

NAME
     ng_ubt  --  Netgraph  node type that is also a driver for Bluetooth USB de-
     vices

SYNOPSIS
     #include <sys/types.h>
     #include <netgraph/bluetooth/include/ng_ubt.h>

DESCRIPTION
     The ubt node type is both a persistent Netgraph node type and a driver  for
     Bluetooth	USB  devices.	It implements a Bluetooth USB transport layer as
     per chapter H2 of the Bluetooth Specification Book v1.1.	A  new	node  is
     created when supported USB device is plugged.

     The node has a single hook called hook.  Incoming bytes received on the de-
     vice  are re-assembled into HCI frames (according to the length).	Full HCI
     frames are sent out on the hook.  The node will add HCI frame indicator  if
     device  did  not send it.	HCI frames received on hook are transmitted out.
     The node will drop HCI frame indicator unless  device  requires  it  to  be
     present.

HOOKS
     This node type supports the following hooks:

     hook    single HCI frame contained in single mbuf structure.

CONTROL MESSAGES
     This node type supports the generic control messages, plus the following:

     NGM_UBT_NODE_GET_DEBUG
	     Returns an integer containing the current debug level for the node.

     NGM_UBT_NODE_SET_DEBUG
	     This command takes an integer argument and sets current debug level
	     for the node.

     NGM_UBT_NODE_GET_QLEN
	     This  command takes a parameter that specifies queue number and re-
	     turns current maximal length of the queue for the node.

     NGM_UBT_NODE_SET_QLEN
	     This command takes two parameters that  specify  queue  number  and
	     maximum  length  of  the queue and sets maximal length of the queue
	     for the node.

     NGM_UBT_NODE_GET_STAT
	     Returns various statistic information for the node, such as: number
	     of bytes (frames) sent, number of bytes (frames) received and  num-
	     ber of input (output) errors.

     NGM_UBT_NODE_RESET_STAT
	     Reset all statistic counters to zero.

     NGM_UBT_NODE_DEV_NODES
	     This  command  takes  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 parame-
	     ter's value is zero, then the driver will destroy device nodes  for
	     the  endpoints.   The  device nodes interface is mutually exclusive
	     with Netgraph interface.

DEVICE NODES INTERFACE
     The ubt driver can create or destroy  endpoint  device  nodes  on	request.
     This feature can be used to implement external firmware download utility.

     The  control transfers can only happen on the control endpoint which is al-
     ways endpoint 0.  Control requests are issued by ioctl(2) calls.

     Only incoming transfers are supported on an interrupt endpoint.  To perform
     I/O on an interrupt endpoint, read(2) should be used.  All  I/O  operations
     on an interrupt endpoint are unbuffered.

     The  bulk transfers can be in or out depending on the endpoint.  To perform
     I/O on a bulk endpoint, read(2) and write(2) should be used.  All I/O oper-
     ations on a bulk endpoint are unbuffered.

     The control endpoint (endpoint 0) handles the following ioctl(2) calls:

     USB_GET_DEVICE_DESC (usb_device_descriptor_t)
	     Return the device descriptor.

     USB_GET_STRING_DESC (struct usb_string_desc)
	     Get a string descriptor for the given language ID and string index.

	     struct usb_string_desc {
		     int		     string_index;
		     int		     language_id;
		     usb_string_descriptor_t desc;
	     };

     USB_DO_REQUEST (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 data.  The size of the trans-
	     ferred data is determined from the request.  The addr field is  ig-
	     nored  in	this call.  The flags field can be used to flag that the
	     request is allowed to be shorter than the requested size,	and  the
	     actlen will contain the actual size on completion.

	     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 */
	     };
	     This  is a dangerous operation in that it can perform arbitrary op-
	     erations on the device.  Some of the most dangerous (e.g., changing
	     the device address) are not allowed.

     USB_GET_DEVICEINFO (struct usb_device_info)
	     Get an information summary for the device.  This call will not  is-
	     sue any USB transactions.

SHUTDOWN
     This node shuts down when the corresponding USB device is un-plugged.

BUGS
     Isochronous USB transfers are broken.  It means that USB device will not be
     able to transfer SCO data (voice).  USB interrupt transfers are implemented
     as bulk-in transfers (not really a bug).

FILES
     /dev/ubtN.EE  Endpoint EE of device N.

SEE ALSO
     netgraph(4), ugen(4), usb(4), ngctl(8)

HISTORY
     The ubt node type was implemented in FreeBSD 5.0.

AUTHORS
     Maksim Yevmenkin <m_evmenkin@yahoo.com>

FreeBSD 5.2.1			  June 14, 2002 		       NG_UBT(4)
home | help