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


Detailed Description

Implements communication over acl layer.

Author:
Martin Hinz <btnode@hinz.ch>
Date:
26.7.2004
Every pkt can be given a service number. An application can get the acl pkts on the basis of this service number.

pkt structs definition for better understanding :)

bt_stack:
                       -----------------------------------
struct bt_hci_pkt_acl: |type|       header       |payload|
                       -----------------------------------
                         1   HCI_ACL_DATA_PKT_HDR    1

bt_acl_com_stack:
                       ------------------------------------------------------------------------
bt_acl_com_pkt_t     : | 1  |HCI_ACL_DATA_PKT_HDR|BT_ACL_COM_HEADER_LEN|BT_MAX_ACL_COM_PAYLOAD|
(array of u_char)      ------------------------------------------------------------------------

                                                 ----------------------------------------------
bt_acl_com_t         :                           |  len  | service nr. |       payload        |
                                                 ----------------------------------------------
                                                     2          2       BT_MAX_ACL_COM_PAYLOAD

#include <sys/types.h>
#include <bt/bt_defs.h>

Data Structures

struct  _bt_acl_com_buffer_entry
struct  _bt_acl_com_service
struct  _bt_acl_com_stack

Defines

#define BT_ACL_COM_HEADER_LEN   4
#define BT_ERR_ACL_COM_TIMEOUT   -2
#define BT_ERR_ACL_PAYLOAD_OVERFLOW   -3
#define BT_ERR_BUFFER_OVERFLOW   8
#define BT_ERR_FRAGMENTED_ACL_PKT   4
#define BT_ERR_INVALID_HANDLE   2
#define BT_ERR_INVALID_SERV_NR   1
#define BT_ERR_SERV_NR_OUT_OF_BOUNDS   -1
#define BT_MAX_ACL_COM_PAYLOAD   117
#define HCI_PACKET_TYPE   BT_HCI_PACKET_TYPE_DM3
#define MAX_SERVICE_NR   8

Typedefs

typedef _bt_acl_com_buffer_entry bt_acl_com_buffer_entry_t
typedef u_char bt_acl_com_pkt_t [1+HCI_ACL_DATA_PKT_HDR+BT_ACL_COM_HEADER_LEN+BT_MAX_ACL_COM_PAYLOAD]
typedef _bt_acl_com_service bt_acl_com_service_t
typedef _bt_acl_com_stack bt_acl_com_stack_t

Functions

void bt_acl_com_dump_data (u_char *data, u_short len)
long bt_acl_com_free_packet (bt_acl_com_stack_t *_bt_acl_com_stack, bt_acl_com_pkt_t *pkt)
 To free the buffer of a acl communication pkt.
u_charbt_acl_com_get_data_pointer (bt_acl_com_pkt_t *pkt)
 Returns the pointer to the start of the acl com data area.
char bt_acl_com_get_packet (bt_acl_com_stack_t *_bt_acl_com_stack, u_char service_nr, bt_acl_com_pkt_t **p_p_pkt, bt_hci_con_handle_t *con_handle, u_short *len, u_long timeout_ms)
 To access the packet this function will return a pointer to the buffer of the packet with service number nr via the argument pointer.
u_char bt_acl_com_get_status (bt_acl_com_stack_t *_bt_acl_com_stack)
 Errors that occure during receiving an acl pkt can be accessed with this function.
bt_acl_com_stack_tbt_acl_com_init (struct btstack *bt_stack, u_char nr_buffer)
void bt_acl_com_print_bt_addr (bt_addr_t addr)
void bt_acl_com_print_bt_addr_m (bt_addr_t addr)
long bt_acl_com_send_packet (bt_acl_com_stack_t *_bt_acl_com_stack, bt_acl_com_pkt_t *pkt, bt_hci_con_handle_t con_handle, u_short service_nr, u_short len)
 Function to send a acl communication packet.


Define Documentation

#define BT_ACL_COM_HEADER_LEN   4

defines the length of the acl communication header

#define BT_ERR_ACL_COM_TIMEOUT   -2

acl pkt error: timeout occured, no pkt with given service number arrived in given time.

#define BT_ERR_ACL_PAYLOAD_OVERFLOW   -3

acl pkt error: playload to large

#define BT_ERR_BUFFER_OVERFLOW   8

ack pkt arriving error: internal buffer for ack pkt overflow (due to error pkts that arrived)

Examples:
bt-lego/bt-lego.c.

#define BT_ERR_FRAGMENTED_ACL_PKT   4

acl pkt arriving error: pkt fragmentation (due to wrong pkt type, use HCI_PACKET_TYPE!)

Examples:
bt-lego/bt-lego.c.

#define BT_ERR_INVALID_HANDLE   2

acl pkt arriving error: invalid connection handle (due to communication problems)

Examples:
bt-lego/bt-lego.c.

#define BT_ERR_INVALID_SERV_NR   1

acl pkt arriving error: invalid service number (due to communication problems)

Examples:
bt-lego/bt-lego.c.

#define BT_ERR_SERV_NR_OUT_OF_BOUNDS   -1

acl pkt error: service number out of bounds

#define BT_MAX_ACL_COM_PAYLOAD   117

for not having fragmented pkts we limit the payload of acl for packet type DM3 to 117!! because DM3 acl payload limited to 4+117=121 bytes

#define HCI_PACKET_TYPE   BT_HCI_PACKET_TYPE_DM3

Use this packet type to send pkts with a payload up to BT_MAX_ACL_COM_PAYLOAD.
DM3 means three slots are used for one pkt. Smaller amount of slots can lead to fragmented pkts

Examples:
btstreamer/receiver/btreceiver.c.

#define MAX_SERVICE_NR   8

defines the maximal service nr 0 - (MAX_SERVICE_NR-1) that can be given the acl pkts


Typedef Documentation

typedef struct _bt_acl_com_buffer_entry bt_acl_com_buffer_entry_t

struct starts with the acl pkt. the con handle holds the handle where the pkt arrived. the state tells about the usage of this buffer entry and the next value points to next entry with same service nr

typedef u_char bt_acl_com_pkt_t[1+HCI_ACL_DATA_PKT_HDR+BT_ACL_COM_HEADER_LEN+BT_MAX_ACL_COM_PAYLOAD]

this typedef allocates just enough memory for a acl com pkt with all the header space needed

Examples:
bt-lego/bt-lego.c.

typedef struct _bt_acl_com_service bt_acl_com_service_t

struct to hold for every service (max MAX_SERVICE_NR) a registered event handle to notify a thread and a list of pointer to packets waiting for this thread. service nr equal to the position in the services array!

typedef struct _bt_acl_com_stack bt_acl_com_stack_t

holds all the data needed by the acl communication driver


Function Documentation

void bt_acl_com_dump_data ( u_char data,
u_short  len 
)

to dump buffer data of length len

long bt_acl_com_free_packet ( bt_acl_com_stack_t _bt_acl_com_stack,
bt_acl_com_pkt_t pkt 
)

To free the buffer of a acl communication pkt.

It is important to free the receive buffer again after usage!

Parameters:
_bt_acl_com_stack Pointer to the acl communication stack
pkt Packet to be freed
Examples:
bt-lego/bt-lego.c.

char bt_acl_com_get_packet ( bt_acl_com_stack_t _bt_acl_com_stack,
u_char  service_nr,
bt_acl_com_pkt_t **  p_p_pkt,
bt_hci_con_handle_t con_handle,
u_short len,
u_long  timeout_ms 
)

To access the packet this function will return a pointer to the buffer of the packet with service number nr via the argument pointer.

After usage of the packet it is important to call the bt_acl_com_free_packet to avoid acl packet-buffer overflow!
Use bt_acl_com_get_data_pointer to get to the payload data pointer!

Attention:
But always pass the original bt_hci_pkt_acl pointer to all functions!
Parameters:
_bt_acl_com_stack Pointer to the acl communication stack
service_nr Requested service number (0 - (MAX_SERVICE_NR - 1))
p_p_pkt Pass the address of the pointer to a acl com pkt
con_handle The connection handle where the pkt arrived on
len length of payload of this pkt
timeout_ms timeout in milliseconds. Use NUT_WAIT_INFINITE or 0 for no timeout or 1 to check the availability of packets
Returns:
0 or possible errors:
Examples:
bt-lego/bt-lego.c.

u_char bt_acl_com_get_status ( bt_acl_com_stack_t _bt_acl_com_stack  ) 

Errors that occure during receiving an acl pkt can be accessed with this function.

After the call the internal error status will be set to 0 again.
Possible errors:

Examples:
bt-lego/bt-lego.c.

bt_acl_com_stack_t* bt_acl_com_init ( struct btstack bt_stack,
u_char  nr_buffer 
)

to initialize the acl com stack.

Parameters:
bt_stack Pointer to btstack
nr_buffer Number of receive-buffer for acl com packets
Returns:
pointer to bt acl stack

void bt_acl_com_print_bt_addr ( bt_addr_t  addr  ) 

prints the bt_addr with format: 00:00:00:00:00:00 using normal DEBUGT() call

See also:
btn-terminal.h

void bt_acl_com_print_bt_addr_m ( bt_addr_t  addr  ) 

prints the bt_addr with format: 00:00:00:00:00:00 using special DEBUGT_M() call

See also:
btn-terminal.h

long bt_acl_com_send_packet ( bt_acl_com_stack_t _bt_acl_com_stack,
bt_acl_com_pkt_t pkt,
bt_hci_con_handle_t  con_handle,
u_short  service_nr,
u_short  len 
)

Function to send a acl communication packet.

Alloc new bt_acl_com_pkt_t and use bt_acl_com_get_data_pointer to access the acl com data area. Send the packet to the connection with con_handle passing the pointer to the bt_acl_com_pkt_t the service number and the length of the acl-com-payload!
e.g.:

bt_acl_com_pkt_t acl_com_pkt;
u_char* data = bt_acl_com_get_data_pointer(&acl_com_pkt);
strcpy(data, "hello world");
bt_acl_com_send_packet(&acl_com_pkt, <con_handle>, <serv_nr>, 12);
Parameters:
_bt_acl_com_stack Pointer to the acl communication stack
pkt ACL communication packet to be sent
con_handle Handle of the connection for sending
service_nr service number (0 - (MAX_SERVICE_NR-1))
len length of the acl pkt payload
Returns:
0 or possible errors:
Examples:
bt-lego/bt-lego.c.


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