feat: Added NetBSD man pages

1 files changed, 384 insertions, 0 deletions

diff --git a/static/netbsd/man9/bluetooth.9 b/static/netbsd/man9/bluetooth.9
new file mode 100644
index 00000000..d58d1576
--- /dev/null
+++ b/static/netbsd/man9/bluetooth.9
@@ -0,0 +1,384 @@
+.\"	$NetBSD: bluetooth.9,v 1.6 2017/07/03 21:28:48 wiz Exp $
+.\"
+.\" Copyright (c) 2006 Itronix Inc.
+.\" All rights reserved.
+.\"
+.\" Written by Iain Hibbert for Itronix Inc.
+.\"
+.\" Redistribution and use in source and binary forms, with or without
+.\" modification, are permitted provided that the following conditions
+.\" are met:
+.\" 1. Redistributions of source code must retain the above copyright
+.\"    notice, this list of conditions and the following disclaimer.
+.\" 2. Redistributions in binary form must reproduce the above copyright
+.\"    notice, this list of conditions and the following disclaimer in the
+.\"    documentation and/or other materials provided with the distribution.
+.\" 3. The name of Itronix Inc. may not be used to endorse
+.\"    or promote products derived from this software without specific
+.\"    prior written permission.
+.\"
+.\" THIS SOFTWARE IS PROVIDED BY ITRONIX INC. ``AS IS'' AND
+.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
+.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
+.\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL ITRONIX INC. BE LIABLE FOR ANY
+.\" DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+.\" (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
+.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
+.\" ON ANY THEORY OF LIABILITY, WHETHER IN
+.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+.\" POSSIBILITY OF SUCH DAMAGE.
+.\"
+.\"
+.Dd November 20, 2007
+.Dt BLUETOOTH 9
+.Os
+.Sh NAME
+.Nm BLUETOOTH
+.Nd Bluetooth Device/Protocol API
+.Sh SYNOPSIS
+.In netbt/bluetooth.h
+.In netbt/hci.h
+.In netbt/l2cap.h
+.In netbt/rfcomm.h
+.Ft struct hci_unit *
+.Fn hci_attach "const struct hci_if *hci_if" "device_t dev" "uint16_t flags"
+.Ft void
+.Fn hci_detach "struct hci_unit *unit"
+.Ft void
+.Fn hci_input_event "struct hci_unit *unit" "struct mbuf *m"
+.Ft void
+.Fn hci_input_acl "struct hci_unit *unit" "struct mbuf *m"
+.Ft void
+.Fn hci_input_sco "struct hci_unit *unit" "struct mbuf *m"
+.Ft int
+.Fn btproto_attach "btproto_handle *" "const struct btproto *proto" "void *ref"
+.Ft int
+.Fn btproto_bind "btproto_handle" "struct sockaddr_bt *addr"
+.Ft int
+.Fn btproto_sockaddr "btproto_handle" "struct sockaddr_bt *addr"
+.Ft int
+.Fn btproto_connect "btproto_handle" "struct sockaddr_bt *addr"
+.Ft int
+.Fn btproto_peeraddr "btproto_handle" "struct sockaddr_bt *addr"
+.Ft int
+.Fn btproto_disconnect "btproto_handle" "int linger"
+.Ft int
+.Fn btproto_detach "btproto_handle *"
+.Ft int
+.Fn btproto_listen "btproto_handle"
+.Ft int
+.Fn btproto_send "btproto_handle" "struct mbuf *mbuf"
+.Ft int
+.Fn btproto_rcvd "btproto_handle" "size_t space"
+.Ft int
+.Fn btproto_setopt "btproto_handle" "int optarg" "void *arg"
+.Ft int
+.Fn btproto_getopt "btproto_handle" "int optarg" "void *arg"
+.Sh DESCRIPTION
+The Bluetooth Protocol Stack provides socket based access to Bluetooth
+Devices.
+This document describes device driver access to the stack from
+below, and also the general Bluetooth Protocol/Service API for layering
+above existing Bluetooth Protocols.
+.Sh DATA TYPES
+Device drivers attaching to the Bluetooth Protocol Stack should pass a
+pointer to a
+.Fa struct hci_if
+defined in
+.In netbt/hci.h
+containing the driver information as follows:
+.Bd -literal
+struct hci_if {
+	int	(*enable)(device_t);
+	void	(*disable)(device_t);
+	void	(*output_cmd)(device_t, struct mbuf *);
+	void	(*output_acl)(device_t, struct mbuf *);
+	void	(*output_sco)(device_t, struct mbuf *);
+	void	(*get_stats)(device_t, struct bt_stats *, int);
+	int	ipl;
+};
+.Ed
+.Pp
+Statistics counters should be updated by the device after packets have
+been transmitted or received, or when errors occur.
+.Bd -literal
+struct bt_stats {
+	uint32_t	err_tx;
+	uint32_t	err_rx;
+	uint32_t	cmd_tx;
+	uint32_t	evt_rx;
+	uint32_t	acl_tx;
+	uint32_t	acl_rx;
+	uint32_t	sco_tx;
+	uint32_t	sco_rx;
+	uint32_t	byte_tx;
+	uint32_t	byte_rx;
+};
+.Ed
+.Pp
+Bluetooth Protocol layers attaching above the Bluetooth Protocol Stack
+will make use of the
+.Fa struct btproto
+data type, which is defined in
+.In netbt/bluetooth.h
+and contains the following function callbacks which
+should be initialized by the protocol layer before attaching to the
+protocol which it uses:
+.Bd -literal
+struct btproto {
+	void (*connecting)(void *);
+	void (*connected)(void *);
+	void (*disconnected)(void *, int);
+	void *(*newconn)(void *, struct sockaddr_bt *, struct sockaddr_bt *);
+	void (*complete)(void *, int);
+	void (*linkmode)(void *, int);
+	void (*input)(void *, struct mbuf *);
+};
+.Ed
+.Sh FUNCTIONS
+The following functions are related to the Bluetooth Device API.
+.Bl -tag -width XXXX
+.It Fn hci_attach "hci_if" "dev"
+Attach Bluetooth HCI device
+.Ar dev
+to the protocol stack in the manner described by
+.Ar hci_if .
+Driver quirks may be registered by passing the corresponding
+.Dv BTF_xxxx
+flag in the
+.Ar flags
+argument.
+.Pp
+.Fn hci_attach
+will return a
+.Fa struct hci_unit
+handle to be passed to the protocol stack in other calls.
+.It Fn hci_detach "unit"
+Detach Bluetooth HCI
+.Ar unit
+from the device.
+.It Fn hci_input_event "unit" "mbuf"
+This function should be called by the device when it has an event
+packet to present to the protocol stack.
+It may be called from an interrupt routine at the
+.Fa ipl
+value given in the
+.Ar hci_if
+descriptor.
+.It Fn hci_input_acl "unit" "mbuf"
+This function should be called by the device when it has an ACL data
+packet to present to the protocol stack.
+It may be called from an interrupt routine at the
+.Fa ipl
+value given in the
+.Ar hci_if
+descriptor.
+.It Fn hci_input_sco "unit" "mbuf"
+This function should be called by the device when it has an SCO data
+packet to present to the protocol stack.
+It may be called from an interrupt routine at the
+.Fa ipl
+value given in the
+.Ar hci_if
+descriptor.
+.It Fn "(*enable)" "dev"
+This will be called when the protocol stack wishes to enable the device.
+.It Fn "(*disable)" "dev"
+This will be called when the protocol stack wishes to disable the device.
+.It Fn "(*output_cmd)" "dev" "mbuf"
+Will be called to output command packets on the device.
+The device is responsible for arbitrating access to the output queue, and
+output commands should be sent asynchronously.
+The device owns the
+.Ar mbuf
+and should release it when sent.
+.It Fn "(*output_acl)" "dev" "mbuf"
+Will be called to output ACL data packets on the device.
+The device is responsible for arbitrating access to the output queue, and
+ACL data packets should be sent asynchronously.
+The device owns the
+.Ar mbuf
+and should release it when sent.
+.It Fn "(*output_sco)" "dev" "mbuf"
+Will be called to output SCO data packets on the device.
+The device is responsible for arbitrating access to the output queue, and
+SCO data packets should be sent asynchronously.
+When the SCO data packet has been placed on the device and the
+.Ar mbuf
+is no longer required, it should be returned to the Bluetooth protocol
+stack via the
+.Fn hci_complete_sco
+call.
+.It Fn "(*get_stats)" "dev" "dest" "flush"
+Will be called when IO statistics are requested.
+The
+.Fa bt_stats
+structure
+.Ar dest
+should be filled in, and if the
+.Ar flush
+argument is true, statistics should be reset.
+.El
+.Pp
+The following function definitions are related to the Bluetooth Protocol API.
+Note that the "btproto" prefix is representative only, the protocol being
+used will have a more specific prefix with prototypes being declared in
+the appropriate
+.In netbt/btproto.h
+file.
+.Bl -tag -width XXXX
+.It Fn btproto_attach "handle_ptr" "proto" "ref"
+Allocate and initialize a new protocol object at the
+.Ar handle_ptr
+address that should subsequently be passed into the other functions.
+.Ar proto
+is a pointer to the
+.Fa btproto
+structure as described above containing relevant callbacks, and
+.Ar ref
+is the argument that will be supplied to those calls.
+.It Fn btproto_bind "handle" "addr"
+Set the local address of the protocol object described by
+.Ar handle
+to
+.Ar addr .
+.It Fn btproto_sockaddr "handle" "addr"
+Copy the local address of the protocol object described by
+.Ar handle
+into
+.Ar addr
+.It Fn btproto_connect "handle" "addr"
+Initiate a connection by the protocol object described by
+.Ar handle
+to the remote device described by
+.Ar addr .
+This will result in a call to either
+.Fn proto->connected
+or
+.Fn proto->disconnected ,
+and optionally
+.Fn proto->connecting
+with the appropriate reference as given to
+.Fn btproto_attach .
+.It Fn btproto_peeraddr "handle" "addr"
+Copy the remote address of the protocol object described by
+.Ar handle
+into
+.Ar addr .
+.It Fn btproto_disconnect "handle" "linger"
+Schedule a disconnection by the protocol object described by
+.Ar handle .
+This will result in a call to
+.Fn proto->disconnected
+with the appropriate reference when the connection is torn
+down.
+If linger is zero, the disconnection will be initiated
+immediately and any outstanding data may be lost.
+.It Fn btproto_detach "handle_ptr"
+Detach the protocol object described by the value in the location of
+.Ar handle_ptr ,
+and free any related memory.
+The pointer in the location is cleared.
+.It Fn btproto_listen "handle"
+Use the protocol object described by
+.Ar handle
+as a listening post.
+This will result in calls to the
+.Fn proto->newconn
+function when incoming connections are detected.
+.It Fn btproto_send "handle" "mbuf"
+Send data on the connection described by the protocol object.
+.It Fn btproto_rcvd "handle" "space"
+Indicate to the protocol that
+.Ar space
+is now available in the input buffers so that flow control may be
+deasserted.
+This should also be called to indicate initial buffer space.
+Note that
+.Ar space
+is an absolute value.
+.It Fn btproto_setopt "handle" "optarg" "arg"
+Set options on the protocol object described by
+.Ar handle .
+.It Fn btproto_getopt "handle" "optarg" "arg"
+Get options for the protocol object described by
+.Ar handle .
+.It Fn "(*connecting)" "ref"
+This function will be called when the protocol receives information
+that the connection described by
+.Ar ref
+is pending.
+.It Fn "(*connected)" "ref"
+This function will be called when the connection described by
+.Ar ref
+is successful and indicates that data may now be sent.
+.It Fn "(*disconnected)" "ref" "error"
+This function will be called when the connection described by
+.Ar ref
+is disconnected.
+.It Fn "*(*newconn)" "ref" "laddr" "raddr"
+This function will be called when the protocol receives a new incoming
+connection on the local device described by
+.Ar laddr
+from the remote device described by
+.Ar raddr .
+The protocol should decide if it wishes to accept the connection and
+should attach and return a new instance of the relevant protocol handle
+or NULL.
+.It Fn "(*complete)" "ref" "count"
+This function will be called when the protocol has completed sending
+data.
+Complete will usually mean that the data has successfully left
+the device though for guaranteed protocols it can mean that the data
+has arrived at the other end and been acknowledged, and that
+.Ar count
+amount of data can be removed from the socket buffer.
+The units of the
+.Ar count
+value will be dependent on the protocol being used (e.g. RFCOMM is bytes,
+but L2CAP is packets)
+.It Fn "(*linkmode)" "ref" "mode"
+This function will be called for established connections, when the link mode
+of the baseband link has changed.
+.Ar mode
+is the new mode.
+.It Fn "(*input)" "ref" "mbuf"
+This function is called to supply new data on the connection described by
+.Ar ref .
+.El
+.Sh CODE REFERENCES
+The Bluetooth Protocol Stack is contained in the
+.Pa sys/netbt
+directory.
+.Pp
+The Bluetooth Device API as described above is contained
+in the
+.Pa sys/netbt/hci_unit.c
+file.
+.Pp
+For examples of the Bluetooth Protocol API see the interaction between
+the L2CAP upper layer in
+.Pa sys/netbt/l2cap_upper.c
+and either the L2CAP socket layer in
+.Pa sys/netbt/l2cap_socket.c
+or the
+.Xr bthidev 4
+pseudo-device in
+.Pa sys/dev/bluetooth/bthidev.c .
+.Pp
+Also, the RFCOMM upper layer in
+.Pa sys/netbt/rfcomm_upper.c
+and the RFCOMM socket layer in
+.Pa sys/netbt/rfcomm_socket.c .
+.Sh SEE ALSO
+.Xr bluetooth 4 ,
+.Xr bt3c 4 ,
+.Xr bthidev 4 ,
+.Xr ubt 4
+.Sh HISTORY
+This Bluetooth Protocol Stack was written for
+.Nx 4.0
+by
+.An Iain Hibbert ,
+under the sponsorship of Itronix, Inc.