btnut/btnode/include/bt/bt_psm.h File Reference


Detailed Description

Bluetooth protocol/service multiplexor.

Author:
Kevin Martin <kevmarti@tik.ee.ethz.ch>
Date:
2006/03/23
The protocol/service multiplexor is the entity that delivers incoming packets to different application services.

Service Registration
Services on the receiving side are identified by a "PSM", a unique number which is included in every data packet. Thus, to receive data, applications have to register a service routine that processes incoming data, together with a "PSM" identifier at the protocol/service multiplexor. See bt_psm_service_register for further details.

Packet Processing
Incoming packets are encapsulated in ACL packet buffers bt_acl_pkt_buf. For every received buffer, a free buffer has to be passed back to the protocol/service multiplexor for that it does not run out of free buffers. This has to be done whenever a service rotine exits, see BT_PSM_DATA_CB.

See also:
bt_acl_pkt_buf.h
l2cap_cl.h
mhop_cl.h

#include <bt/bt_acl_pkt_buf.h>

Defines

#define BT_PSM_DATA_CB
 Service Routine Definition.
Errors
#define BT_PSM_ERR_BUF_OVERFLOW   -7
#define BT_PSM_ERR_INVALID_PSM   -1
#define BT_PSM_ERR_INVALID_SERVICE_NR   -5
#define BT_PSM_ERR_NO_SERVICE_REGISTERED   -6
#define BT_PSM_ERR_PSM_IN_USE   -2
#define BT_PSM_ERR_SERVICE_PORTS_EXHAUSTED   -3

Typedefs

typedef bt_acl_pkt_buf *(*) bt_psm_data_cb_t (bt_acl_pkt_buf *pkt_buf, u_char *data, u_short len, u_short service_nr, void *cb_arg)
typedef bt_psm_s bt_psm_t
 Protocol / service multiplexor typedef.

Functions

short bt_psm_deliver_msg (bt_psm_t *mux, bt_acl_pkt_buf *pkt_buf, u_char *data, u_short len, u_short psm, bt_acl_pkt_buf **free_buf_p)
 Delivers a received message to a registered service.
u_short bt_psm_get_nr_default_bufs (bt_psm_t *psmux)
 Returns the number of the free ACL packet buffers available.
bt_psm_data_cb_t bt_psm_service_patch (bt_psm_t *psmux, u_short psm, bt_psm_data_cb_t data_cb)
 Patch registered service.
Initialization
bt_psm_tbt_psm_init (struct btstack *bt_stack, u_short nr_services, u_short nr_bufs)
Application Interface
short bt_psm_service_clear (bt_psm_t *mux, u_short service_nr)
 Clears a previousely registered service.
long bt_psm_service_register (bt_psm_t *psmux, u_short psm, BT_PSM_DATA_CB, void *cb_arg)
 Registers a higher layer service at the protocol / service multiplexor.
short bt_psm_service_set_buffers (bt_psm_t *mux, u_short service_nr, bt_acl_pkt_buf **free_bufs)
 Sets the packet buffers a registered service shall use.


Define Documentation

#define BT_PSM_DATA_CB

Value:

bt_acl_pkt_buf* (*data_cb) (bt_acl_pkt_buf* pkt_buf, \
                                u_char* data, \
                                u_short len, \
                                u_short service_nr, \
                                void* cb_arg)
Service Routine Definition.

A service routine handles incoming data and has to be specified by the application during service registration (see bt_psm_service_register). This defines how a service routine has to look like.

Parameters:
msg Pointer to the received ACL packet buffer (incoming packets are encapsulated in ACL packet buffers)
data Pointer to the payload of the packet
len Size of the packet's payload
service_nr Number of the service this callback corresponds to
arg Pointer to the (optional) callback argument.
Returns:
Pointer to a free ACL packet buffer. Usually, just pass the message obtained.
Note: Keep execution time of your service routines as short as possible for that other services are not blocked too long. I.e. try to avoid NutSleep- and NutEventWait statements, as well as unnecessary thread-switches.

See also:
bt_psm_service_register
bt_acl_pkt_buf_t
bt_acl_pkt_buf

#define BT_PSM_ERR_BUF_OVERFLOW   -7

The service to deliver does not provide enough free buffers

#define BT_PSM_ERR_INVALID_PSM   -1

The psm specified is not valid

#define BT_PSM_ERR_INVALID_SERVICE_NR   -5

The service number passed does not identify a registered service

#define BT_PSM_ERR_NO_SERVICE_REGISTERED   -6

The psm field in the data packet received is valid but there is no service registered on that psm

#define BT_PSM_ERR_PSM_IN_USE   -2

The psm specified is used by another registered service

#define BT_PSM_ERR_SERVICE_PORTS_EXHAUSTED   -3

No more services can be registered to the connection-less data channel


Typedef Documentation

typedef bt_acl_pkt_buf*(*) bt_psm_data_cb_t(bt_acl_pkt_buf *pkt_buf, u_char *data, u_short len, u_short service_nr, void *cb_arg)

BT_PSM_DATA_CB as type bt_psm_data_cb_t


Function Documentation

short bt_psm_deliver_msg ( bt_psm_t mux,
bt_acl_pkt_buf pkt_buf,
u_char data,
u_short  len,
u_short  psm,
bt_acl_pkt_buf **  free_buf_p 
)

Delivers a received message to a registered service.

Delivers the received message msg to the service registered at PSM psm. The parameters data and len are passed to the higher layer service via the registered data callback (see BT_PSM_DATA_CB). Thus, data should be a pointer to the payload of the packet, while data_len should be set to the lenght of the payload.

Note: applications typically do not call this function! This function is used by lower layer protocols (e.g. l2cap connection-less) to deliver received messages to higher layer protocols / services (e.g. multi-hop layer, application service).

Parameters:
mux Pointer to the protocol / service multiplexor
msg Pointer to the message to be delivered
data Pointer to the payload of the message
len Size of the payload
psm The PSM the message msg will be delivered to
free_msg Reference to a free packet buffer pointer: the protocol / service multiplexor will store a pointer to a free message buffer in the reference passed. If there is no free packet buffer available, the buffer msg passed will be returned.
Returns:
0 or possible errors:
  • BT_PSM_ERR_INVALID_PSM
  • BT_PSM_ERR_NO_SERVICE_REGISTERED
  • BT_PSM_ERR_BUF_OVERFLOW

u_short bt_psm_get_nr_default_bufs ( bt_psm_t psmux  )  [inline]

Returns the number of the free ACL packet buffers available.

See also:
bt_psm_service_set_buffers

bt_psm_t* bt_psm_init ( struct btstack bt_stack,
u_short  nr_services,
u_short  nr_bufs 
)

Initializes a protocol / service multiplexor.

Note: The bt-stack, and the ACL layer, have to be initialized before calling this function. Thus, make shure that:

Parameters:
bt_stack Pointer to the bt-stack to use
nr_services Defines the maximal number of services the multiplexor can handle.
nr_bufs Number of packet buffers to use
Returns:
Pointer to the created multiplexor
Examples:
bt-lego/bt-lego.c, and mhop_blink/mhop_blink.c.

short bt_psm_service_clear ( bt_psm_t mux,
u_short  service_nr 
)

Clears a previousely registered service.

Clears the registered service with service nr service_nr.

Note: dedicated buffers beloning to the service to be cleared are not destroyed.

Parameters:
stack Pointer to the connection-less l2cap stack
service_nr Service number of the service to clear

bt_psm_data_cb_t bt_psm_service_patch ( bt_psm_t psmux,
u_short  psm,
bt_psm_data_cb_t  data_cb 
)

Patch registered service.

Parameters:
stack Pointer to the connection-less l2cap stack
psm of service to intercept
BT_PSM_DATA_CB Data callback function to register.
Returns:
0 if no service registered for this psm, else pointer to previous data callback function

long bt_psm_service_register ( bt_psm_t psmux,
u_short  psm,
BT_PSM_DATA_CB  ,
void *  cb_arg 
)

Registers a higher layer service at the protocol / service multiplexor.

After calling this function, packets received on PSM psm are passed to the registering service. That is, each time a packet is received, the registered service is signalled by calling the service routine BT_PSM_DATA_CB.

Parameters:
psmux Pointer to the multiplexor to use
psm The PSM to register on
BT_PSM_DATA_CB Data callback function to register.
cb_arg Callback argument
Example:
// PSM your service uses
#define SERVICE_PSM 0x1009

// data reception funtion of your service
_service_data_rcv_cb(...) {
    ...
}

int main(void) {
	bt_psm_t* psmux;
	long service_nr;
	
	...
	
	// initialize protocol/service multiplexor
	psmux = bt_psm_init(bt_stack, 6, 6);

	// register your service
	servic_nr =
		bt_psm_service_register(psmux, SERVICE_PSM, _service_data_rcv_cb, NULL);
	
	...
}
Data can then be sent to a service by sending data to the corresponding PSM using one of the connection-less transport protocols, e.g.
u_char data[12];
strcpy(data, "hello world");
l2cap_cl_send(data, <con_handle>, SERVICE_PSM, 12);

See also:
BT_PSM_DATA_CB
l2cap_cl.h
mhop_cl.h
Examples:
mhop_blink/mhop_blink.c.

short bt_psm_service_set_buffers ( bt_psm_t mux,
u_short  service_nr,
bt_acl_pkt_buf **  free_bufs 
)

Sets the packet buffers a registered service shall use.

Call this function if your service needs extra buffers or if you'd like to turn off packet buffering completely. If extra buffers are defined, incoming messages are buffered as long as free buffers can be found in free_bufs.

Parameters:
mux Pointer to the protocol/service multiplexor
servic_nr Service number of the registered service
free_bufs Pointer to an initialized packet buffer queue (see bt_acl_pkt_queue_create). Pass NULL if buffering shall be disabled.
Example:
// PSM your service uses
#define SERVICE_PSM 0x1009

// pointer to extra buffers
bt_acl_pkt_buf* bufs;

// data reception funtion of your service
bt_msg_t* _service_data_rcv_cb(...) {
    ...
}

int main(void) {
	bt_psm_t* psmux;
	long service_nr;
	
	...
	
	// initialize protocol/service multiplexor
	psmux = bt_psm_init(bt_stack, 6, 6);

	// register your service
	servic_nr =
		bt_psm_service_register(psmux, SERVICE_PSM, _service_data_rcv_cb, NULL);
	// create extra buffers
	bufs = bt_acl_pkt_que_create(6);
	bt_psm_service_set_buffers(psmux, service_nr, bufs);
	
	...
}
Examples:
mhop_blink/mhop_blink.c.


Generated on Wed Apr 29 11:12:29 2009 for BTnut System Software by doxygen 1.5.1