More SDP code improvements - responses to ServiceSearchAttribute service discovery requests should now be valid, even if they do not currently return the device's services and service attributes.

Added more documentation to the incomplete Bluetooth stack code.

3 files changed, 142 insertions, 64 deletions

diff --git a/Demos/Host/Incomplete/BluetoothHost/Lib/BluetoothACLPackets.h b/Demos/Host/Incomplete/BluetoothHost/Lib/BluetoothACLPackets.h
index cc0160ff7..d50f6b480 100644
--- a/Demos/Host/Incomplete/BluetoothHost/Lib/BluetoothACLPackets.h
+++ b/Demos/Host/Incomplete/BluetoothHost/Lib/BluetoothACLPackets.h
@@ -45,10 +45,14 @@
 	/* Macros: */
 		#define BT_ACL_DEBUG(l, s, ...)           do { if (ACL_DEBUG_LEVEL >= l) printf_P(PSTR("(ACL) " s "\r\n"), ##__VA_ARGS__); } while (0)
 		#define ACL_DEBUG_LEVEL                   0
-
+	
+		/** Lowest possible channel number for L2CAP data channels */
 		#define BT_CHANNELNUMBER_BASEOFFSET       0x0040
 
+		/** Bluetooth specification defined channel number for signalling commands */
 		#define BT_CHANNEL_SIGNALING              0x0001
+
+		/** Bluetooth specification defined channel number for connectionless data */
 		#define BT_CHANNEL_CONNECTIONLESS         0x0002
 		
 		#define BT_SIGNAL_COMMAND_REJECT          0x01
@@ -82,83 +86,97 @@
 		#define BT_ACL_FIRST_AUTOFLUSH            (1 << 13)
 		
 	/* Type Defines: */
+		/** Bluetooth ACL header structure, common to all ACL data packets. */
 		typedef struct
 		{
-			uint16_t ConnectionHandle;
-			uint16_t DataLength;
+			uint16_t ConnectionHandle; /**< Unique device connection handle of the ACL packet */
+			uint16_t DataLength; /**< Length of the packet payload, in bytes */
 		} BT_ACL_Header_t;
 
+		/** Bluetooth ACL data packet header structure, for ACL packets containing L2CAP data */
 		typedef struct
 		{
-			uint16_t PayloadLength;
-			uint16_t DestinationChannel;
+			uint16_t PayloadLength; /**< Size of the data payload, in bytes */
+			uint16_t DestinationChannel; /**< Destination channel in the device the data is directed to */
 		} BT_DataPacket_Header_t;
 		
+		/** Bluetooth signalling command header structure, for all ACL packets containing a signalling command */
 		typedef struct
 		{
-			uint8_t  Code;
-			uint8_t  Identifier;
-			uint16_t Length;
+			uint8_t  Code; /**< Signal code, a BT_SIGNAL_* mask value */
+			uint8_t  Identifier; /**< Unique signal command identifier to link requests and responses */
+			uint16_t Length; /**< Length of the signalling command data, in bytes */
 		} BT_Signal_Header_t;
 		
+		/** Connection Request signalling command structure, for channel connection requests. */
 		typedef struct
 		{
-			uint16_t PSM;
-			uint16_t SourceChannel;
+			uint16_t PSM; /**< Type of data the channel will carry, a CHANNEL_PSM_* mask value */
+			uint16_t SourceChannel; /**< Channel source on the sending device this channel will link to */
 		} BT_Signal_ConnectionReq_t;
 
+		/** Connection response signalling command structure, for responses to channel connection requests. */
 		typedef struct
 		{
-			uint16_t DestinationChannel;
-			uint16_t SourceChannel;
-			uint16_t Result;
-			uint16_t Status;
+			uint16_t DestinationChannel; /**< Destination device channel that the connection request was processed on */
+			uint16_t SourceChannel; /**< Source device channel address that the connection request came from */
+			uint16_t Result; /**< Connection result, a BT_CONNECTION_* mask value */
+			uint16_t Status; /**< Status of the request if the result was set to the Pending value */
 		} BT_Signal_ConnectionResp_t;
 
+		/** Disconnection request signalling command structure, for channel disconnection requests. */
 		typedef struct
 		{
-			uint16_t DestinationChannel;
-			uint16_t SourceChannel;
+			uint16_t DestinationChannel; /**< Destination channel address which is to be disconnected */
+			uint16_t SourceChannel; /**< Source channel address which is to be disconnected */
 		} BT_Signal_DisconnectionReq_t;
 		
+		/** Disconnection response signalling command structure, for responses to channel disconnection requests. */
 		typedef struct
 		{
-			uint16_t DestinationChannel;
-			uint16_t SourceChannel;
+			uint16_t DestinationChannel; /**< Destination channel address which was disconnected */
+			uint16_t SourceChannel; /**< Source channel address which was disconnected */
 		} BT_Signal_DisconnectionResp_t;		
 
+		/** Configuration Request signalling command structure, for channel configuration requests. */
 		typedef struct
 		{
-			uint16_t DestinationChannel;
-			uint16_t Flags;
+			uint16_t DestinationChannel; /**< Destination channel address which is to be disconnected */
+			uint16_t Flags; /**< Configuration flags for the request, including command continuation */
 		} BT_Signal_ConfigurationReq_t;
 
+		/** Configuration Response signalling command structure, for responses to channel configuration requests. */
 		typedef struct
 		{
-			uint16_t SourceChannel;
-			uint16_t Flags;
-			uint16_t Result;
+			uint16_t SourceChannel; /**< Source channel that the configuration request was directed at */
+			uint16_t Flags; /**< Configuration flags for the response, including response continuation */
+			uint16_t Result; /**< Configuration result, a BT_CONFIGURATION_* mask value */
 		} BT_Signal_ConfigurationResp_t;
 
+		/** Information Request signalling command structure, for device information requests. */
 		typedef struct
 		{
-			uint16_t InfoType;
+			uint16_t InfoType; /**< Data type that is being requested, a BT_INFOREQ_* mask value */
 		} BT_Signal_InformationReq_t;
 		
+		/** Information Response signalling command structure, for responses to information requests. */
 		typedef struct
 		{
-			uint16_t InfoType;
-			uint16_t Result;
+			uint16_t InfoType; /**< Data type that was requested, a BT_INFOREQ_* mask value */
+			uint16_t Result; /**< Result of the request, a BT_INFORMATION_* mask value */
 		} BT_Signal_InformationResp_t;
 		
+		/** Configuration Option header structure, placed at the start of each option in a Channel Configuration
+		 *  request's options list.
+		 */
 		typedef struct
 		{
-			uint8_t Type;
-			uint8_t Length;
+			uint8_t Type; /**< Option type, a BT_CONFIG_OPTION_* mask value */
+			uint8_t Length; /**< Length of the option's value, in bytes */
 		} BT_Config_Option_Header_t;
 
 	/* Function Prototypes: */
-		void    Bluetooth_ACLTask(void);
+		void Bluetooth_ACLTask(void);
 		
 		#if defined(INCLUDE_FROM_BLUETOOTH_ACLPACKETS_C)
 			static void Bluetooth_ProcessIncommingACLPackets(void);
diff --git a/Demos/Host/Incomplete/BluetoothHost/Lib/ServiceDiscoveryProtocol.c b/Demos/Host/Incomplete/BluetoothHost/Lib/ServiceDiscoveryProtocol.c
index 9e30a23bd..4eb262103 100644
--- a/Demos/Host/Incomplete/BluetoothHost/Lib/ServiceDiscoveryProtocol.c
+++ b/Demos/Host/Incomplete/BluetoothHost/Lib/ServiceDiscoveryProtocol.c
@@ -31,9 +31,13 @@
 #define  INCLUDE_FROM_SERVICEDISCOVERYPROTOCOL_C
 #include "ServiceDiscoveryProtocol.h"
 
+/** Service Discovery Protocol attribute, indicationg the service's name. */
 SERVICE_ATTRIBUTE_TEXT(SDP_Attribute_Name,         "SDP");
+/** Service Discovery Protocol attribute, indicationg the service's description. */
 SERVICE_ATTRIBUTE_TEXT(SDP_Attribute_Description,  "BT Service Discovery");
-SERVICE_ATTRIBUTE_LEN8(SDP_Attribute_Availability, SDP_DATATYPE_UNSIGNED_INT, 1, {0xFF});
+/** Service Discovery Protocol attribute, indicationg the service's availability. */
+SERVICE_ATTRIBUTE_LEN8(SDP_Attribute_Availability, SDP_DATATYPE_UnsignedInt, 1, {0xFF});
+/** Service Discovery Protocol attribute table, listing all supported attributes of the service. */
 const ServiceAttributeTable_t SDP_Attribute_Table[] PROGMEM =
 	{
 		{.AttributeID = SDP_ATTRIBUTE_NAME        , .Data = &SDP_Attribute_Name},
@@ -42,9 +46,13 @@ const ServiceAttributeTable_t SDP_Attribute_Table[] PROGMEM =
 		SERVICE_ATTRIBUTE_TABLE_TERMINATOR
 	};
 
+/** RFCOMM Service attribute, indicationg the service's name. */
 SERVICE_ATTRIBUTE_TEXT(RFCOMM_Attribute_Name,         "RFCOMM");
+/** RFCOMM Service attribute, indicationg the service's description. */
 SERVICE_ATTRIBUTE_TEXT(RFCOMM_Attribute_Description,  "Virtual Serial");
-SERVICE_ATTRIBUTE_LEN8(RFCOMM_Attribute_Availability, SDP_DATATYPE_UNSIGNED_INT, 1, {0xFF});
+/** RFCOMM Service attribute, indicationg the service's availability. */
+SERVICE_ATTRIBUTE_LEN8(RFCOMM_Attribute_Availability, SDP_DATATYPE_UnsignedInt, 1, {0xFF});
+/** RFCOMM Service attribute table, listing all supported attributes of the service. */
 const ServiceAttributeTable_t RFCOMM_Attribute_Table[] PROGMEM =
 	{
 		{.AttributeID = SDP_ATTRIBUTE_NAME        , .Data = &RFCOMM_Attribute_Name},
@@ -53,6 +61,9 @@ const ServiceAttributeTable_t RFCOMM_Attribute_Table[] PROGMEM =
 		SERVICE_ATTRIBUTE_TABLE_TERMINATOR
 	};
 
+/** Master service table, listing all supported services (and their attribute tables) of the device, including
+ *  each service's UUID.
+ */
 const ServiceTable_t SDP_Services_Table[] =
 	{
 		{   // 128-bit UUID for the SDP service
@@ -65,6 +76,7 @@ const ServiceTable_t SDP_Services_Table[] =
 		},
 	};
 
+/* Base UUID value common to all standardized Bluetooth services */
 const uint8_t BaseUUID[] = {BASE_96BIT_UUID, 0x00, 0x00, 0x00, 0x00};
 
 
@@ -117,18 +129,19 @@ static void ServiceDiscovery_ProcessServiceSearchAttribute(SDP_PDUHeader_t* SDPH
 	struct
 	{
 		SDP_PDUHeader_t SDPHeader;
+		uint16_t        AttributeListByteCount;
 		uint8_t         ResponseData[100];
 	} ResponsePacket;
 	
-	ResponsePacket.SDPHeader.PDU           = SDP_PDU_SERVICESEARCHATTRIBUTERESPONSE;
-	ResponsePacket.SDPHeader.TransactionID = SDPHeader->TransactionID;
-	
 	if (MaxAttributeSize > sizeof(ResponsePacket.ResponseData))
 	  MaxAttributeSize = sizeof(ResponsePacket.ResponseData);
 	  
-	ResponsePacket.SDPHeader.ParameterLength = ServiceDiscovery_ProcessAttributes(UUIDList, TotalUUIDs,
+	ResponsePacket.AttributeListByteCount    = ServiceDiscovery_ProcessAttributes(UUIDList, TotalUUIDs,
 	                                                                              ResponsePacket.ResponseData,
 	                                                                              MaxAttributeSize, &CurrentParameter);
+	ResponsePacket.SDPHeader.PDU             = SDP_PDU_SERVICESEARCHATTRIBUTERESPONSE;
+	ResponsePacket.SDPHeader.TransactionID   = SDPHeader->TransactionID;
+	ResponsePacket.SDPHeader.ParameterLength = (ResponsePacket.AttributeListByteCount + sizeof(ResponsePacket.AttributeListByteCount));
 
 	Bluetooth_SendPacket(&ResponsePacket, (sizeof(ResponsePacket.SDPHeader) + ResponsePacket.SDPHeader.ParameterLength),
 	                     Channel);
@@ -137,8 +150,8 @@ static void ServiceDiscovery_ProcessServiceSearchAttribute(SDP_PDUHeader_t* SDPH
 static uint8_t ServiceDiscovery_ProcessAttributes(uint8_t UUIDList[][UUID_SIZE_BYTES], const uint8_t TotalUUIDs, uint8_t* ResponseBuffer,
                                                   uint8_t MaxResponseSize, const void** CurrentParameter)
 {
-	uint8_t ElementHeaderSize;
-	uint8_t TotalResponseSize = 0;
+	uint16_t* AttributeResponseSize = ServiceDiscovery_AddDataElementHeader(&ResponseBuffer, SDP_DATATYPE_UnsignedInt);
+	uint8_t   ElementHeaderSize;
 
 	uint16_t AttributeIDListLength = ServiceDiscovery_GetDataElementSize(CurrentParameter, &ElementHeaderSize);
 	BT_SDP_DEBUG(2, "-- Total Attribute Length: 0x%04X", AttributeIDListLength);
@@ -147,20 +160,18 @@ static uint8_t ServiceDiscovery_ProcessAttributes(uint8_t UUIDList[][UUID_SIZE_B
 		uint8_t  AttributeLength = ServiceDiscovery_GetDataElementSize(CurrentParameter, &ElementHeaderSize);
 		uint32_t Attribute       = 0;
 		
-		memcpy(&Attribute, CurrentParameter, AttributeLength);
-		
+		memcpy(&((char*)&Attribute)[sizeof(uint32_t) - AttributeLength], *CurrentParameter, AttributeLength);
+
 		BT_SDP_DEBUG(2, "-- Attribute(%d): 0x%08lX", AttributeLength, Attribute);
 		
-		uint8_t TotalBytesAdded = ServiceDiscovery_GetAttribute(UUIDList, TotalUUIDs, Attribute, &ResponseBuffer,
-		                                                        MaxResponseSize);
-		TotalResponseSize += TotalBytesAdded;
-		MaxResponseSize   -= TotalBytesAdded;
+		*AttributeResponseSize += ServiceDiscovery_GetAttribute(UUIDList, TotalUUIDs, Attribute, &ResponseBuffer,
+		                                                        (MaxResponseSize - *AttributeResponseSize));
 	
 		AttributeIDListLength -= (AttributeLength + ElementHeaderSize);
-		CurrentParameter      += AttributeLength;
+		*CurrentParameter     += AttributeLength;
 	}
 	
-	return TotalResponseSize;
+	return *AttributeResponseSize;
 }
 
 static uint8_t ServiceDiscovery_GetAttribute(uint8_t UUIDList[][UUID_SIZE_BYTES], const uint8_t TotalUUIDs, const uint32_t Attribute,
@@ -174,7 +185,7 @@ static uint8_t ServiceDiscovery_GetAttribute(uint8_t UUIDList[][UUID_SIZE_BYTES]
 			{
 				const ServiceAttributeTable_t* AttributeTable = SDP_Services_Table[CurrTableItem].AttributeTable;
 
-				// Process attribute table
+				// TODO: Process attribute table
 				BT_SDP_DEBUG(2, "FOUND UUID IN TABLE");
 
 				break;
diff --git a/Demos/Host/Incomplete/BluetoothHost/Lib/ServiceDiscoveryProtocol.h b/Demos/Host/Incomplete/BluetoothHost/Lib/ServiceDiscoveryProtocol.h
index 4535b3561..ccbfed41e 100644
--- a/Demos/Host/Incomplete/BluetoothHost/Lib/ServiceDiscoveryProtocol.h
+++ b/Demos/Host/Incomplete/BluetoothHost/Lib/ServiceDiscoveryProtocol.h
@@ -59,28 +59,63 @@
 		#define SDP_ATTRIBUTE_PROVIDER                  0x0002
 		#define SDP_ATTRIBUTE_AVAILABILITY              0x0008
 		
-		#define SDP_DATATYPE_NIL                        (0x00 << 3)
-		#define SDP_DATATYPE_UNSIGNED_INT               (0x01 << 3)
-		#define SDP_DATATYPE_SIGNED_INT                 (0x02 << 3)
-		#define SDP_DATATYPE_UUID                       (0x03 << 3)
-		#define SDP_DATATYPE_TEXT                       (0x04 << 3)
-		#define SDP_DATATYPE_BOOLEAN                    (0x05 << 3)
-		#define SDP_DATATYPE_ELEMENT_SEQUENCE           (0x06 << 3)
-		#define SDP_DATATYPE_ELEMENT_ALTERNATIVE        (0x07 << 3)
-		#define SDP_DATATYPE_URL                        (0x08 << 3)
-		
 		#define UUID_SIZE_BYTES                         16
 		#define BASE_96BIT_UUID                         0xFB, 0x34, 0x9B, 0x5F, 0x80, 0x00, 0x00, 0x80, 0x00, 0x10, 0x00, 0x00
 		
-		#define SERVICE_ATTRIBUTE_TEXT(name, string)    SERVICE_ATTRIBUTE_LEN8(name, SDP_DATATYPE_TEXT, sizeof(string), string)
+		/** Defines a service attribute as a string of characters.
+		 *
+		 *  \param name    Name of the attribute (used to identify the attribute variable only)
+		 *  \param string  String of characters to associate with the attribute
+		 */
+		#define SERVICE_ATTRIBUTE_TEXT(name, string)    SERVICE_ATTRIBUTE_LEN8(name, SDP_DATATYPE_String, sizeof(string), string)
+
+		/** Defines a service attribute with a contents that can fit into an 8-bit integer.
+		 *
+		 *  \param name    Name of the attribute (used to identify the attribute variable only)
+		 *  \param type    Type of attribute contents, a value from the \ref ServiceDiscovery_DataTypes_t enum
+		 *  \param size    Size of the data, in bytes
+		 *  \param ...     Data to associate with the attribute
+		 */
 		#define SERVICE_ATTRIBUTE_LEN8(name, type, size, ...)  const ServiceAttributeData8Bit_t  name PROGMEM = \
 		                                                {.Header = (type | 5), .Size = size, .Data = __VA_ARGS__}
+
+		/** Defines a service attribute with a contents that can fit into an 16-bit integer.
+		 *
+		 *  \param name    Name of the attribute (used to identify the attribute variable only)
+		 *  \param type    Type of attribute contents, a value from the \ref ServiceDiscovery_DataTypes_t enum
+		 *  \param size    Size of the data, in bytes
+		 *  \param ...     Data to associate with the attribute
+		 */
 		#define SERVICE_ATTRIBUTE_LEN16(name, type, size, ...) const ServiceAttributeData16Bit_t name PROGMEM = \
 		                                                {.Header = (type | 6), .Size = size, .Data = __VA_ARGS__}
+
+		/** Defines a service attribute with a contents that can fit into an 32-bit integer.
+		 *
+		 *  \param name    Name of the attribute (used to identify the attribute variable only)
+		 *  \param type    Type of attribute contents, a value from the \ref ServiceDiscovery_DataTypes_t enum
+		 *  \param size    Size of the data, in bytes
+		 *  \param ...     Data to associate with the attribute
+		 */
 		#define SERVICE_ATTRIBUTE_LEN32(name, type, size, ...) const ServiceAttributeData32Bit_t name PROGMEM = \
 		                                                {.Header = (type | 7), .Size = size, .Data = __VA_ARGS__}
+
+		/** Terminator for a service attribute table of type \ref ServiceAttributeTable_t. */
 		#define SERVICE_ATTRIBUTE_TABLE_TERMINATOR      {.Data = NULL}
 
+	/* Enums: */
+		enum ServiceDiscovery_DataTypes_t
+		{
+			SDP_DATATYPE_Nill        = (0 << 3),
+			SDP_DATATYPE_UnsignedInt = (1 << 3),
+			SDP_DATATYPE_SignedInt   = (2 << 3),
+			SDP_DATATYPE_UUID        = (3 << 3),
+			SDP_DATATYPE_String      = (4 << 3),
+			SDP_DATATYPE_Boolean     = (5 << 3),
+			SDP_DATATYPE_Sequence    = (6 << 3),
+			SDP_DATATYPE_Alternative = (7 << 3),
+			SDP_DATATYPE_URL         = (8 << 3),
+		};
+
 	/* Type Defines: */
 		typedef struct
 		{
@@ -127,6 +162,27 @@
 			uint8_t Header;
 			uint8_t Data[];
 		} ServiceAttributeData_t;
+
+	/* Inline Functions: */
+		static inline uint16_t* ServiceDiscovery_AddDataElementHeader(uint8_t** BufferPos, const uint8_t Type)
+		{
+			**BufferPos = (6 | Type);	
+			*BufferPos += 1;
+
+			uint16_t* SizePos = (uint16_t*)*BufferPos;				
+			*SizePos = 0;
+
+			**BufferPos += 2;
+			
+			return SizePos;
+		}
+
+		static inline uint16_t ServiceDiscovery_Read16BitParameter(const void** AttributeHeader)
+		{
+			uint16_t ParamValue = *((uint16_t*)*AttributeHeader);
+			*AttributeHeader += sizeof(uint16_t);
+			return ParamValue;
+		}
 		
 	/* Function Prototypes: */
 		void ServiceDiscovery_ProcessPacket(void* Data, Bluetooth_Channel_t* Channel);
@@ -135,13 +191,6 @@
 			static void ServiceDiscovery_ProcessServiceSearch(SDP_PDUHeader_t* SDPHeader, Bluetooth_Channel_t* Channel);
 			static void ServiceDiscovery_ProcessServiceAttribute(SDP_PDUHeader_t* SDPHeader, Bluetooth_Channel_t* Channel);
 			static void ServiceDiscovery_ProcessServiceSearchAttribute(SDP_PDUHeader_t* SDPHeader, Bluetooth_Channel_t* Channel);
-			
-			static inline uint16_t ServiceDiscovery_Read16BitParameter(const void** AttributeHeader)
-			{
-				uint16_t ParamValue = *((uint16_t*)*AttributeHeader);
-				*AttributeHeader += sizeof(uint16_t);
-				return ParamValue;
-			}
 
 			static uint8_t ServiceDiscovery_ProcessAttributes(uint8_t UUIDList[][UUID_SIZE_BYTES], const uint8_t TotalUUIDs, 
 			                                                  uint8_t* ResponseBuffer, uint8_t MaxResponseSize,