Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
NG_L2CAP(4)		    Kernel Interfaces Manual		   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, segmenta-
       tion and	reassembly operation, and group	abstractions.	L2CAP  permits
       higher  level  protocols	and applications to transmit and receive L2CAP
       data packets 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
		  available at the Baseband layer.  The	Baseband  always  per-
		  forms	 data integrity	checks when requested and resends data
		  until	it has been successfully acknowledged or a timeout oc-
		  curs.	 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
       channel identifier.  Channel identifiers	(CIDs) are local names	repre-
       senting	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	simultaneous L2CAP channels between a local  device  and  some
       remote device.

       CID  assignment is relative to a	particular device and a	device can as-
       sign CIDs independently from other devices.  Thus, even if the same CID
       value has been assigned to (remote) channel endpoints by	several	remote
       devices connected to a single local device, the local device can	 still
       uniquely	associate each remote CID with a different device.

   Channel Operational States
       NG_L2CAP_CLOSED
	    In this state, there is no channel associated with this CID.  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 Con-
	    nect Indication has	been sent to the upper layer and the  part  of
	    the	 local	L2CAP entity processing	the received L2CAP Connect Re-
	    quest waits	for the	corresponding response.	 The response may  re-
	    quire 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 traffic 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  re-
	    ceived  a  positive	response to its	final request and it has posi-
	    tively responded to	the final request from the remote device.

       NG_L2CAP_OPEN
	    In this state, the connection has been established and configured,
	    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 be-
       ing multiplexed above it.  L2CAP	is able	to distinguish	between	 upper
       layer  protocols	 such  as  the	Service	Discovery Protocol, RFCOMM and
       Telephony Control.

   Segmentation	and Reassembly
       The data	packets	defined	by the Baseband	Protocol are limited in	 size.
       Large  L2CAP  packets  must be segmented	into multiple smaller Baseband
       packets prior to	their transmission over	the air.  Similarly,  multiple
       received	Baseband packets may be	reassembled into a single larger L2CAP
       packet.

   Quality of Service
       The  L2CAP  connection establishment process allows the exchange	of in-
       formation regarding the quality of service (QoS)	expected  between  two
       Bluetooth units.

   Groups
       The Baseband Protocol supports the concept of a piconet,	a group	of de-
       vices  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 in-
		 tegrity, 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  re-
       sponse  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 process-
       ing.  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 ac-
       knowledgment.

       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	remote
	    device that	issued the connection request, the  local  CID	repre-
	    senting  the  channel being	requested, the Identifier contained in
	    the	request, and the PSM value the request is targeting.

       NGM_L2CAP_L2CA_CON_RSP
	    Issues a response to a connection request event indication.	 Input
	    parameters are the remote device's 48-bit address, Identifier sent
	    in the request, local CID, the Response code, and the  Status  at-
	    tached  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 chan-
	    nel	 to a new set of channel parameters.  Input parameters are the
	    local CID endpoint,	new incoming receivable	MTU (InMTU), new  out-
	    going  flow	 spec-ification,  and flush and	link timeouts.	Output
	    parameters are the Result, accepted	incoming MTU (InMTU), the  re-
	    mote 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 parameter is
	    Result.  Result is zero if an L2CAP	 Disconnect  Response  is  re-
	    ceived,  otherwise	a non-zero value is returned.  Once disconnec-
	    tion has been requested, no	process	will be	able  to  successfully
	    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  re-
	    ceived  from  appropriate upstream hook and	must be	prepended with
	    header defined as follows.

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

	    The	output parameters are Result and Length	of data	written.

       NGM_L2CAP_L2CA_GRP_CREATE
	    Requests the creation of a CID to represent	a  logical  connection
	    to	multiple  devices.   Input parameter is	the PSM	value that the
	    outgoing connectionless traffic is labelled	with, and  the	filter
	    used for incoming traffic.	Output parameter is the	CID represent-
	    ing	 the  local endpoint.  On creation, the	group is empty but in-
	    coming traffic destined for	the PSM	value is readable.   This  re-
	    quest 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 parameter
	    includes  the  CID	representing  the group	and the	BD_ADDR	of the
	    group member to be added.  The output  parameter  Result  confirms
	    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 Re-
	    sult confirms the success or failure of the	operation.  If the Re-
	    sult is successful,	BD_ADDR_Lst is a list  of  the	Bluetooth  ad-
	    dresses  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 parame-
	    ters 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  follow-
       ing:

       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
	    This command takes an integer  argument  and  sets	current	 debug
	    level for the node.

       NGM_L2CAP_NODE_GET_CON_LIST
	    Returns list of active baseband connections	(i.e., ACL links).

       NGM_L2CAP_NODE_GET_CHAN_LIST
	    Returns list of active L2CAP channels.

       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.

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>

BUGS
       Most likely.  Please report if found.

FreeBSD	14.3			 July 4, 2002			   NG_L2CAP(4)

Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=ng_l2cap&sektion=4&manpath=FreeBSD+14.3-RELEASE+and+Ports>

home | help