FreeBSD Man Pages

ng_l2cap(4)

NAME

     ng_l2cap -- Netgraph node type that implements Bluetooth Logical Link
     Control and Adaptation Protocol (L2CAP)

SYNOPSIS

     #include <sys/types.h>
     #include <netgraph/bluetooth/include/ng_hci.h>
     #include <netgraph/bluetooth/include/ng_l2cap.h>

DESCRIPTION

     The l2cap node type is a Netgraph node type that implements Bluetooth
     Logical Link Control and Adaptation Protocol as per chapter D of the
     Bluetooth Specification Book v1.1.

     L2CAP provides connection-oriented and connectionless data services to
     upper layer protocols with protocol multiplexing capability, segmentation
     and reassembly operation, and group abstractions.	L2CAP permits higher
     level protocols and applications to transmit and receive L2CAP data pack-
     ets up to 64 kilobytes in length.

   L2CAP Assumptions
	   1.	The ACL link between two units is set up.  The Baseband pro-
		vides orderly delivery of data packets, although there might
		be individual packet corruption and duplicates.  No more than
		one ACL link exists between any two devices.

	   2.	The Baseband always provides the impression of full-duplex
		communication channels.  This does not imply that all L2CAP
		communications are bi-directional.  Multicasts and unidirec-
		tional traffic (e.g., video) do not require duplex channels.

	   3.	L2CAP provides a reliable channel using the mechanisms avail-
		able at the Baseband layer.  The Baseband always performs data
		integrity checks when requested and resends data until it has
		been successfully acknowledged or a timeout occurs.  As
		acknowledgements may be lost, timeouts may occur even after
		the data has been successfully sent.

L2CAP GENERAL OPERATION

     The Logical Link Control and Adaptation Protocol (L2CAP) is based around
     the concept of ``channels''.  Each channel is bound to a single protocol
     in a many-to-one fashion.	Multiple channels can be bound to the same
     protocol, but a channel cannot be bound to multiple protocols.  Each
     L2CAP packet received on a channel is directed to the appropriate higher
     level protocol.

     Each one of the end-points of an L2CAP channel is referred to by a chan-
     nel identifier.  Channel identifiers (CIDs) are local names representing
     a logical channel end-point on the device.  Identifiers from 0x0001 to
     0x003F are reserved for specific L2CAP functions.	The null identifier
     (0x0000) is defined as an illegal identifier and must never be used as a
     destination end-point.  All L2CAP signalling commands are sent to CID
     0x0001.  CID 0x0002 is reserved for group-oriented channel.  The same CID
     must not be reused as a local L2CAP channel endpoint for multiple simul-
     taneous L2CAP channels between a local device and some remote device.

     CID assignment is relative to a particular device and a device can assign
	     This is the only state when a link level connection (Baseband)
	     may not exist.  Link disconnection forces all other states into
	     the NG_L2CAP_CLOSED state.

     NG_L2CAP_W4_L2CAP_CON_RSP
	     In this state, the CID represents a local end-point and an L2CAP
	     Connect Request message has been sent referencing this endpoint
	     and it is now waiting for the corresponding L2CAP Connect
	     Response message.

     NG_L2CAP_W4_L2CA_CON_RSP
	     In this state, the remote end-point exists and an L2CAP Connect
	     Request has been received by the local L2CAP entity.  An L2CA
	     Connect Indication has been sent to the upper layer and the part
	     of the local L2CAP entity processing the received L2CAP Connect
	     Request waits for the corresponding response.  The response may
	     require a security check to be performed.

     NG_L2CAP_CONFIG
	     In this state, the connection has been established but both sides
	     are still negotiating the channel parameters.  The Configuration
	     state may also be entered when the channel parameters are being
	     renegotiated.  Prior to entering the NG_L2CAP_CONFIG state, all
	     outgoing data traffic is suspended since the traffic parameters
	     of the data traffic are to be renegotiated.  Incoming data traf-
	     fic is accepted until the remote channel endpoint has entered the
	     NG_L2CAP_CONFIG state.  In the NG_L2CAP_CONFIG state, both sides
	     will issue L2CAP Configuration Request messages if only defaults
	     are being used, a null message will be sent.  If a large amount
	     of parameters need to be negotiated, multiple messages will be
	     sent to avoid any MTU limitations and negotiate incrementally.
	     Moving from the NG_L2CAP_CONFIG state to the NG_L2CAP_OPEN state
	     requires both sides to be ready.  An L2CAP entity is ready when
	     it has received a positive response to its final request and it
	     has positively responded to the final request from the remote
	     device.

     NG_L2CAP_OPEN
	     In this state, the connection has been established and config-
	     ured, and data flow may proceed.

     NG_L2CAP_W4_L2CAP_DISCON_RSP
	     In this state, the connection is shutting down and an L2CAP Dis-
	     connect Request message has been sent.  This state is now waiting
	     for the corresponding response.

     NG_L2CAP_W4_L2CA_DISCON_RSP
	     In this state, the connection on the remote endpoint is shutting
	     down and an L2CAP Disconnect Request message has been received.
	     An L2CA Disconnect Indication has been sent to the upper layer to
	     notify the owner of the CID that the remote endpoint is being
	     closed.  This state is now waiting for the corresponding response
	     from the upper layer before responding to the remote endpoint.

   Protocol Multiplexing
     L2CAP supports protocol multiplexing because the Baseband Protocol does
     not support any ``type'' field identifying the higher layer protocol
     being multiplexed above it.  L2CAP is able to distinguish between upper
     packet.

   Quality of Service
     The L2CAP connection establishment process allows the exchange of infor-
     mation regarding the quality of service (QoS) expected between two Blue-
     tooth units.

   Groups
     The Baseband Protocol supports the concept of a piconet, a group of
     devices synchronously hopping together using the same clock.  The L2CAP
     group abstraction permits implementations to efficiently map protocol
     groups on to piconets.

     The following features are outside the scope of L2CAP responsibilities:

	   -   L2CAP does not transport audio designated for SCO links.

	   -   L2CAP does not enforce a reliable channel or ensure data
	       integrity, that is, L2CAP performs no retransmissions or check-
	       sum calculations.

	   -   L2CAP does not support a reliable multicast channel.

	   -   L2CAP does not support the concept of a global group name.

HOOKS

     This node type supports the following hooks:

     hci     Bluetooth Host Controller Interface downstream hook.

     l2c     Upper layer protocol upstream hook.  Usually the Bluetooth L2CAP
	     socket layer is connected to the hook.

     ctl     Control hook.  Usually the Bluetooth raw L2CAP sockets layer is
	     connected to the hook.

INTERFACE TO THE UPPER LAYER PROTOCOLS (L2CA CONTROL MESSAGES)

     Bluetooth specification says that L2CA request must block until response
     is ready.	L2CAP node uses token field from Netgraph message header to
     match L2CA request and response.  The upper layer protocol must populate
     token.  L2CAP node will queue request and start processing.  Later, when
     response is ready or timeout has occurred, L2CAP node will create new
     Netgraph message, set token and NFG_RESP flag and send message to the
     upper layer.  Note that L2CA indication messages will not populate token
     and will not set NGF_RESP flag.  There is no reason for this, because
     they are just notifications and do not require acknowledgment.

     NGM_L2CAP_L2CA_CON
	     Requests the creation of a channel representing a logical connec-
	     tion to a physical address.  Input parameters are the target pro-
	     tocol (PSM) and remote device's 48-bit address (BD_ADDR).	Output
	     parameters are the local CID (LCID) allocated by the local L2CAP
	     entity, and Result of the request.  If Result indicates a pending
	     notification, the Status value may contain more information of
	     what processing is delaying the establishment of the connection.

     NGM_L2CAP_L2CA_CON_IND
	     This message includes the parameters for the address of the
	     fier sent in the request, local CID, the Response code, and the
	     Status attached to the Response code.  The output parameter is
	     the Result of the service request.  This primitive must be called
	     no more than once after receiving the indication.

     NGM_L2CAP_L2CA_CFG
	     Requests the initial configuration (or reconfiguration) of a
	     channel to a new set of channel parameters.  Input parameters are
	     the local CID endpoint, new incoming receivable MTU (InMTU), new
	     outgoing flow spec-ification, and flush and link timeouts.  Out-
	     put parameters are the Result, accepted incoming MTU (InMTU), the
	     remote side's flow requests, and flush and link timeouts.

     NGM_L2CAP_L2CA_CFG_IND
	     This message includes the parameters indicating the local CID of
	     the channel the request has been sent to, the outgoing MTU size
	     (maximum packet that can be sent across the channel) and the
	     flowspec describing the characteristics of the incoming data.
	     All other channel parameters are set to their default values if
	     not provided by the remote device.

     NGM_L2CAP_L2CA_CFG_RSP
	     Issues a response to a configuration request event indication.
	     Input parameters include the local CID of the endpoint being con-
	     figured, outgoing transmit MTU (which may be equal or less to the
	     OutMTU parameter in the configuration indication event) and the
	     accepted flowspec for incoming traffic.  The output parameter is
	     the Result value.

     NGM_L2CAP_L2CA_QOS_IND
	     This message includes the parameter indicating the address of the
	     remote Bluetooth device where the QoS contract has been violated.

     NGM_L2CAP_L2CA_DISCON
	     Requests the disconnection of the channel.  Input parameter is
	     the CID representing the local channel endpoint.  Output parame-
	     ter is Result.  Result is zero if an L2CAP Disconnect Response is
	     received, otherwise a non-zero value is returned.	Once discon-
	     nection has been requested, no process will be able to success-
	     fully read or write from the CID.

     NGM_L2CAP_L2CA_DISCON_IND
	     This message includes the parameter indicating the local CID the
	     request has been sent to.

     NGM_L2CAP_L2CA_WRITE
	     Response to transfer of data request.  Actual data must be
	     received from appropriate upstream hook and must be prepended
	     with header defined as follows.

		   /* L2CA data packet header */
		   typedef struct {
			   u_int32_t token;  /* token to use in L2CAP_L2CA_WRITE */
			   u_int16_t length; /* length of the data */
			   u_int16_t lcid;   /* local channel ID */
		   } __attribute__ ((packed)) ng_l2cap_l2ca_hdr_t;

	     The output parameters are Result and Length of data written.
	     request has not been implemented.

     NGM_L2CAP_L2CA_GRP_CLOSE
	     The use of this message closes down a Group.  This request has
	     not been implemented.

     NGM_L2CAP_L2CA_GRP_ADD_MEMBER
	     Requests the addition of a member to a group.  The input parame-
	     ter includes the CID representing the group and the BD_ADDR of
	     the group member to be added.  The output parameter Result con-
	     firms the success or failure of the request.  This request has
	     not been implemented.

     NGM_L2CAP_L2CA_GRP_REM_MEMBER
	     Requests the removal of a member from a group.  The input parame-
	     ters include the CID representing the group and BD_ADDR of the
	     group member to be removed.  The output parameter Result confirms
	     the success or failure of the request.  This request has not been
	     implemented.

     NGM_L2CAP_L2CA_GRP_MEMBERSHIP
	     Requests a report of the members of a group.  The input parameter
	     CID represents the group being queried.  The output parameter
	     Result confirms the success or failure of the operation.  If the
	     Result is successful, BD_ADDR_Lst is a list of the Bluetooth
	     addresses of the N members of the group.  This request has not
	     been implemented.

     NGM_L2CAP_L2CA_PING
	     Initiates an L2CA Echo Request message and the reception of the
	     corresponding L2CAP Echo Response message.  The input parameters
	     are remote Bluetooth device BD_ADDR, Echo Data and Length of the
	     echo data.  The output parameters are Result, Echo Data and
	     Length of the echo data.

     NGM_L2CAP_L2CA_GET_INFO
	     Initiates an L2CA Information Request message and the reception
	     of the corresponding L2CAP Info Response message.	The input
	     parameters are remote Bluetooth device BD_ADDR and Information
	     Type.  The output parameters are Result, Information Data and
	     Size of the information data.

     NGM_L2CAP_L2CA_ENABLE_CLT
	     Request to disable (enable) the reception of connectionless pack-
	     ets.  The input parameter is the PSM value indicating service
	     that should be blocked (unblocked) and Enable flag.

NETGRAPH CONTROL MESSAGES

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

     NGM_L2CAP_NODE_GET_FLAGS
	     Returns current state for the node.

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

     NGM_L2CAP_NODE_SET_DEBUG

     NGM_L2CAP_NODE_GET_AUTO_DISCON_TIMO
	     Returns an integer containing the current value of the auto dis-
	     connect timeout (in sec).

     NGM_L2CAP_NODE_SET_AUTO_DISCON_TIMO
	     This command accepts an integer and sets the value of the auto
	     disconnect timeout (in sec).  The special value of 0 (zero) dis-
	     ables auto disconnect timeout.

SHUTDOWN

     This node shuts down upon receipt of an NGM_SHUTDOWN control message, or
     when all hooks have been disconnected.

BUGS

     Most likely.  Please report if found.

SEE ALSO

     netgraph(4), l2control(8), l2ping(8), ngctl(8)

HISTORY

     The l2cap node type was implemented in FreeBSD 5.0.

AUTHORS

     Maksim Yevmenkin <m_evmenkin@yahoo.com>

FreeBSD 5.4			 July 4, 2002			   FreeBSD 5.4

SPONSORED LINKS