Document the Bluetooth ACL layer. Remove unneeded parameters from the signalling...
[pub/USBasp.git] / Demos / Host / Incomplete / BluetoothHost / Lib / BluetoothACLPackets.c
index 10560f9..d18e643 100644 (file)
 #define  INCLUDE_FROM_BLUETOOTH_ACLPACKETS_C\r
 #include "BluetoothACLPackets.h"\r
 \r
+/** Bluetooth ACL processing task. This task should be called repeatedly the main Bluetooth\r
+ *  stack task to manage the ACL processing state.\r
+ */\r
 void Bluetooth_ACLTask(void)\r
 {\r
-       Bluetooth_ProcessACLPackets();\r
+       /* Process incomming ACL packets, if any */\r
+       Bluetooth_ProcessIncommingACLPackets();\r
        \r
+       /* Check for any half-open channels, send configuration details to the remote device if found */\r
        for (uint8_t i = 0; i < BLUETOOTH_MAX_OPEN_CHANNELS; i++)\r
        {\r
                Bluetooth_Channel_t* ChannelData = &Bluetooth_Connection.Channels[i];\r
        \r
                bool MustSendConfigReq = true;\r
        \r
+               /* Check if we are in a channel state which requires a configuration request to be sent */\r
                switch (ChannelData->State)\r
                {\r
                        case Channel_Config_WaitConfig:\r
@@ -54,6 +60,7 @@ void Bluetooth_ACLTask(void)
                                break;\r
                }\r
                \r
+               /* Only send a configuration request if it the channel was in a state which required it */\r
                if (MustSendConfigReq)\r
                {\r
                        struct\r
@@ -68,10 +75,13 @@ void Bluetooth_ACLTask(void)
                                } Option_LocalMTU;\r
                        } PacketData;\r
                        \r
+                       /* Fill out the Signal Command header in the response packet */\r
                        PacketData.SignalCommandHeader.Code            = BT_SIGNAL_CONFIGURATION_REQUEST;\r
                        PacketData.SignalCommandHeader.Identifier      = ++Bluetooth_Connection.SignallingIdentifier;\r
                        PacketData.SignalCommandHeader.Length          = sizeof(PacketData.ConfigurationRequest) +\r
                                                                         sizeof(PacketData.Option_LocalMTU);\r
+\r
+                       /* Fill out the Configuration Request in the response packet, including local MTU information */\r
                        PacketData.ConfigurationRequest.DestinationChannel = ChannelData->RemoteNumber;\r
                        PacketData.ConfigurationRequest.Flags          = 0;\r
                        PacketData.Option_LocalMTU.Header.Type         = BT_CONFIG_OPTION_MTU;\r
@@ -86,7 +96,11 @@ void Bluetooth_ACLTask(void)
        }\r
 }\r
 \r
-static void Bluetooth_ProcessACLPackets(void)\r
+/** Incomming ACL packet processing task. This task is called by the main ACL processing task to read in and process\r
+ *  any incomming ACL packets to the device, handling signal requests as they are received or passing along channel\r
+ *  data to the user application.\r
+ */\r
+static void Bluetooth_ProcessIncommingACLPackets(void)\r
 {\r
        BT_ACL_Header_t        ACLPacketHeader;\r
        BT_DataPacket_Header_t DataHeader;\r
@@ -100,6 +114,7 @@ static void Bluetooth_ProcessACLPackets(void)
                return;\r
        }\r
          \r
+       /* Read in the received ACL packet headers when it has been discovered that a packet has been received */\r
        Pipe_Read_Stream_LE(&ACLPacketHeader, sizeof(ACLPacketHeader));\r
        Pipe_Read_Stream_LE(&DataHeader, sizeof(DataHeader));\r
 \r
@@ -110,36 +125,39 @@ static void Bluetooth_ProcessACLPackets(void)
        BT_ACL_DEBUG(2, "-- Destination Channel: 0x%04X", DataHeader.DestinationChannel);\r
        BT_ACL_DEBUG(2, "-- Payload Length: 0x%04X", DataHeader.PayloadLength);\r
 \r
+       /* Check the packet's destination channel - signalling channel should be processed by the stack internally */\r
        if (DataHeader.DestinationChannel == BT_CHANNEL_SIGNALING)\r
        {\r
+               /* Read in the Signal Command header of the incomming packet */\r
                BT_Signal_Header_t SignalCommandHeader;\r
                Pipe_Read_Stream_LE(&SignalCommandHeader, sizeof(SignalCommandHeader));\r
                \r
+               /* Dispatch to the appropriate handler function based on the Signal message code */\r
                switch (SignalCommandHeader.Code)\r
                {\r
                        case BT_SIGNAL_CONNECTION_REQUEST:\r
-                               Bluetooth_Signal_ConnectionReq(&ACLPacketHeader, &DataHeader, &SignalCommandHeader);\r
+                               Bluetooth_Signal_ConnectionReq(&SignalCommandHeader);\r
                                break;\r
                        case BT_SIGNAL_CONNECTION_RESPONSE:\r
-                               Bluetooth_Signal_ConnectionResp(&ACLPacketHeader, &DataHeader, &SignalCommandHeader);\r
+                               Bluetooth_Signal_ConnectionResp(&SignalCommandHeader);\r
                                break;\r
                        case BT_SIGNAL_CONFIGURATION_REQUEST:\r
-                               Bluetooth_Signal_ConfigurationReq(&ACLPacketHeader, &DataHeader, &SignalCommandHeader);\r
+                               Bluetooth_Signal_ConfigurationReq(&SignalCommandHeader);\r
                                break;\r
                        case BT_SIGNAL_CONFIGURATION_RESPONSE:\r
-                               Bluetooth_Signal_ConfigurationResp(&ACLPacketHeader, &DataHeader, &SignalCommandHeader);\r
+                               Bluetooth_Signal_ConfigurationResp(&SignalCommandHeader);\r
                                break;\r
                        case BT_SIGNAL_DISCONNECTION_REQUEST:\r
-                               Bluetooth_Signal_DisconnectionReq(&ACLPacketHeader, &DataHeader, &SignalCommandHeader);\r
+                               Bluetooth_Signal_DisconnectionReq(&SignalCommandHeader);\r
                                break;\r
                        case BT_SIGNAL_DISCONNECTION_RESPONSE:\r
-                               Bluetooth_Signal_DisconnectionResp(&ACLPacketHeader, &DataHeader, &SignalCommandHeader);\r
+                               Bluetooth_Signal_DisconnectionResp(&SignalCommandHeader);\r
                                break;\r
                        case BT_SIGNAL_ECHO_REQUEST:\r
-                               Bluetooth_Signal_EchoReq(&ACLPacketHeader, &DataHeader, &SignalCommandHeader);\r
+                               Bluetooth_Signal_EchoReq(&SignalCommandHeader);\r
                                break;\r
                        case BT_SIGNAL_INFORMATION_REQUEST:\r
-                               Bluetooth_Signal_InformationReq(&ACLPacketHeader, &DataHeader, &SignalCommandHeader);\r
+                               Bluetooth_Signal_InformationReq(&SignalCommandHeader);\r
                                break;\r
                        case BT_SIGNAL_COMMAND_REJECT:\r
                                BT_ACL_DEBUG(1, "<< Command Reject", NULL);\r
@@ -163,28 +181,39 @@ static void Bluetooth_ProcessACLPackets(void)
        }\r
        else\r
        {\r
-               Bluetooth_PacketReceived(&DataHeader.PayloadLength, Bluetooth_GetChannelData(DataHeader.DestinationChannel, false));\r
-       \r
-               Pipe_SelectPipe(BLUETOOTH_DATA_IN_PIPE);\r
-               Pipe_Discard_Stream(DataHeader.PayloadLength);\r
+               /* Non-signalling packet received, read in the packet contents and pass to the user application */\r
+               uint8_t PacketData[DataHeader.PayloadLength];\r
+               Pipe_Read_Stream_LE(PacketData, DataHeader.PayloadLength);\r
                Pipe_ClearIN();\r
                Pipe_Freeze();\r
+\r
+               Bluetooth_PacketReceived(PacketData, DataHeader.PayloadLength, Bluetooth_GetChannelData(DataHeader.DestinationChannel, false));\r
        }\r
 }\r
 \r
+/** Sends a packet to the remote device on the specified channel.\r
+ *\r
+ * \param Data     Pointer to a buffer where the data is to be sourced from\r
+ * \param DataLen  Length of the data to send\r
+ * \param Channel  Channel information structure containing the destination channel's information, NULL to send\r
+ *                 to the remote device's signalling channel\r
+ *\r
+ * \return A value from the \ref BT_SendPacket_ErrorCodes_t enum\r
+ */\r
 uint8_t Bluetooth_SendPacket(void* Data, uint16_t DataLen, Bluetooth_Channel_t* Channel)\r
 {\r
        BT_ACL_Header_t        ACLPacketHeader;\r
        BT_DataPacket_Header_t DataHeader;\r
 \r
+       /* A remote device must be connected before a packet transmission is attempted */\r
        if (!(Bluetooth_Connection.IsConnected))\r
          return BT_SENDPACKET_NotConnected;\r
 \r
+       /* If the destination channel is not the signalling channel and it is not currently fully open, abort */\r
        if ((Channel != NULL) && (Channel->State != Channel_Open))\r
          return BT_SENDPACKET_ChannelNotOpen;\r
 \r
-       // TODO: Add packet fragmentation here after retrieving the device's signal channel MTU\r
-\r
+       /* Fill out the packet's header from the remote device connection information structure */\r
        ACLPacketHeader.ConnectionHandle      = (Bluetooth_Connection.ConnectionHandle | BT_ACL_FIRST_AUTOFLUSH);\r
        ACLPacketHeader.DataLength            = sizeof(DataHeader) + DataLen;\r
        DataHeader.PayloadLength              = DataLen;\r
@@ -193,6 +222,7 @@ uint8_t Bluetooth_SendPacket(void* Data, uint16_t DataLen, Bluetooth_Channel_t*
        Pipe_SelectPipe(BLUETOOTH_DATA_OUT_PIPE);\r
        Pipe_Unfreeze();\r
        \r
+       /* Write the packet contents to the pipe so that it can be sent to the remote device */\r
        Pipe_Write_Stream_LE(&ACLPacketHeader, sizeof(ACLPacketHeader));\r
        Pipe_Write_Stream_LE(&DataHeader, sizeof(DataHeader));\r
        Pipe_Write_Stream_LE(Data, DataLen);\r
@@ -210,23 +240,40 @@ uint8_t Bluetooth_SendPacket(void* Data, uint16_t DataLen, Bluetooth_Channel_t*
        return BT_SENDPACKET_NoError;\r
 }\r
 \r
+/** Opens a bluetooth channel to the currently connected remote device, so that data can be exchanged.\r
+ *\r
+ *  \note The channel is not immediately opened when this function returns - it must undergo a two way\r
+ *        connection and configuration process first as the main Bluetooth stack processing task is\r
+ *        repeatedly called. The returned channel is unusable by the user application until its State\r
+ *        element has progressed to the Open state.\r
+ *\r
+ *  \param PSM  PSM of the service that the channel is to be opened for\r
+ *\r
+ *  \return Pointer to the channel information structure of the opened channel, or NULL if no free channels\r
+ */\r
 Bluetooth_Channel_t* Bluetooth_OpenChannel(uint16_t PSM)\r
 {\r
        Bluetooth_Channel_t* ChannelData = NULL;\r
 \r
+       /* Search through the channel information list for a free channel item */\r
        for (uint8_t i = 0; i < BLUETOOTH_MAX_OPEN_CHANNELS; i++)\r
        {\r
                if (Bluetooth_Connection.Channels[i].State == Channel_Closed)\r
                {\r
-                       ChannelData = &Bluetooth_Connection.Channels[i];                                \r
+                       ChannelData = &Bluetooth_Connection.Channels[i];\r
+                       \r
+                       /* Set the new channel structure's local channel number to a unique value within the connection orientated\r
+                          channel address space */\r
                        ChannelData->LocalNumber = (BT_CHANNELNUMBER_BASEOFFSET + i);\r
                        break;\r
                }\r
        }\r
 \r
+       /* If no free channel item was found in the list, all channels are occupied - abort */\r
        if (ChannelData == NULL)\r
          return NULL;\r
 \r
+       /* Reset and fill out the allocated channel's information structure with defaults */\r
        ChannelData->RemoteNumber = 0;\r
        ChannelData->PSM          = PSM;\r
        ChannelData->LocalMTU     = MAXIMUM_CHANNEL_MTU;\r
@@ -238,9 +285,12 @@ Bluetooth_Channel_t* Bluetooth_OpenChannel(uint16_t PSM)
                BT_Signal_ConnectionReq_t ConnectionRequest;\r
        } PacketData;\r
 \r
+       /* Fill out the Signal Command header in the response packet */\r
        PacketData.SignalCommandHeader.Code              = BT_SIGNAL_CONNECTION_REQUEST;\r
        PacketData.SignalCommandHeader.Identifier        = ++Bluetooth_Connection.SignallingIdentifier;\r
        PacketData.SignalCommandHeader.Length            = sizeof(PacketData.ConnectionRequest);\r
+       \r
+       /* Fill out the Connection Request in the response packet */\r
        PacketData.ConnectionRequest.PSM                 = PSM;\r
        PacketData.ConnectionRequest.SourceChannel       = ChannelData->LocalNumber;\r
        \r
@@ -253,11 +303,23 @@ Bluetooth_Channel_t* Bluetooth_OpenChannel(uint16_t PSM)
        return ChannelData;\r
 }\r
 \r
+/** Closes a bluetooth channel that is open to the currently connected remote device, so that no further data\r
+ *  can be exchanged.\r
+ *\r
+ *  \note The channel is not immediately closed when this function returns - it must undergo an asynchronous\r
+ *        disconnection process first as the main Bluetooth stack processing task is repeatedly called. The\r
+ *        returned channel is unusable by the user application upon return however the channel is not completely\r
+ *        closed until its State element has progressed to the Closed state.\r
+ *\r
+ * \param Channel  Channel information structure of the channel to close\r
+ */\r
 void Bluetooth_CloseChannel(Bluetooth_Channel_t* Channel)\r
 {\r
+       /* Don't try to close a non-existing or already closed channel */\r
        if ((Channel == NULL) || (Channel->State == Channel_Closed))\r
          return;\r
-         \r
+\r
+       /* Set the channel's state to the start of the teardown process */\r
        Channel->State = Channel_WaitDisconnect;\r
 \r
        struct\r
@@ -266,9 +328,12 @@ void Bluetooth_CloseChannel(Bluetooth_Channel_t* Channel)
                BT_Signal_DisconnectionReq_t DisconnectionRequest;\r
        } PacketData;\r
        \r
+       /* Fill out the Signal Command header in the response packet */\r
        PacketData.SignalCommandHeader.Code            = BT_SIGNAL_DISCONNECTION_REQUEST;\r
        PacketData.SignalCommandHeader.Identifier      = ++Bluetooth_Connection.SignallingIdentifier;\r
        PacketData.SignalCommandHeader.Length          = sizeof(PacketData.DisconnectionRequest);\r
+\r
+       /* Fill out the Disconnection Request in the response packet */\r
        PacketData.DisconnectionRequest.DestinationChannel = Channel->RemoteNumber;\r
        PacketData.DisconnectionRequest.SourceChannel = Channel->LocalNumber;\r
 \r
@@ -279,9 +344,11 @@ void Bluetooth_CloseChannel(Bluetooth_Channel_t* Channel)
        BT_ACL_DEBUG(2, "-- Source Channel: 0x%04X", PacketData.DisconnectionRequest.SourceChannel);    \r
 }\r
 \r
-static inline void Bluetooth_Signal_ConnectionReq(BT_ACL_Header_t*        ACLPacketHeader,\r
-                                                  BT_DataPacket_Header_t* DataHeader,\r
-                                                  BT_Signal_Header_t*     SignalCommandHeader)\r
+/** Internal Bluetooth stack Signal Command processing routine for a Connection Request command.\r
+ *\r
+ *  \param  SignalCommandHeader  Pointer to the start of the received packet's Signal Command header\r
+ */\r
+static inline void Bluetooth_Signal_ConnectionReq(BT_Signal_Header_t* SignalCommandHeader)\r
 {\r
        BT_Signal_ConnectionReq_t ConnectionRequest;\r
        \r
@@ -294,21 +361,28 @@ static inline void Bluetooth_Signal_ConnectionReq(BT_ACL_Header_t*        ACLPac
        BT_ACL_DEBUG(2, "-- PSM: 0x%04X", ConnectionRequest.PSM);\r
        BT_ACL_DEBUG(2, "-- Source Channel: 0x%04X", ConnectionRequest.SourceChannel);\r
        \r
+       /* Try to retrieve the existing channel's information structure if it exists */\r
        Bluetooth_Channel_t* ChannelData = Bluetooth_GetChannelData(ConnectionRequest.SourceChannel, true);\r
 \r
+       /* If an existing channel item with the correct remote channel number was not found, find a free channel entry */\r
        if (ChannelData == NULL)\r
        {\r
+               /* Look through the channel information list for a free entry */\r
                for (uint8_t i = 0; i < BLUETOOTH_MAX_OPEN_CHANNELS; i++)\r
                {\r
                        if (Bluetooth_Connection.Channels[i].State == Channel_Closed)\r
                        {\r
-                               ChannelData = &Bluetooth_Connection.Channels[i];                                \r
+                               ChannelData = &Bluetooth_Connection.Channels[i];\r
+\r
+                               /* Set the new channel structure's local channel number to a unique value within the connection orientated\r
+                                  channel address space */\r
                                ChannelData->LocalNumber = (BT_CHANNELNUMBER_BASEOFFSET + i);\r
                                break;\r
                        }\r
                }\r
        }\r
 \r
+       /* Reset the channel item contents only if a channel entry was found for it */\r
        if (ChannelData != NULL)\r
        {\r
                ChannelData->RemoteNumber = ConnectionRequest.SourceChannel;\r
@@ -323,9 +397,12 @@ static inline void Bluetooth_Signal_ConnectionReq(BT_ACL_Header_t*        ACLPac
                BT_Signal_ConnectionResp_t ConnectionResponse;\r
        } ResponsePacket;\r
 \r
+       /* Fill out the Signal Command header in the response packet */\r
        ResponsePacket.SignalCommandHeader.Code              = BT_SIGNAL_CONNECTION_RESPONSE;\r
        ResponsePacket.SignalCommandHeader.Identifier        = SignalCommandHeader->Identifier;\r
        ResponsePacket.SignalCommandHeader.Length            = sizeof(ResponsePacket.ConnectionResponse);\r
+\r
+       /* Fill out the Connection Response in the response packet */\r
        ResponsePacket.ConnectionResponse.DestinationChannel = ChannelData->LocalNumber;\r
        ResponsePacket.ConnectionResponse.SourceChannel      = ChannelData->RemoteNumber;\r
        ResponsePacket.ConnectionResponse.Result             = (ChannelData == NULL) ? BT_CONNECTION_REFUSED_RESOURCES :\r
@@ -340,9 +417,11 @@ static inline void Bluetooth_Signal_ConnectionReq(BT_ACL_Header_t*        ACLPac
        BT_ACL_DEBUG(2, "-- Source Channel: 0x%04X", ResponsePacket.ConnectionResponse.SourceChannel);\r
 }\r
 \r
-static inline void Bluetooth_Signal_ConnectionResp(BT_ACL_Header_t* ACLPacketHeader,\r
-                                                   BT_DataPacket_Header_t* DataHeader,\r
-                                                   BT_Signal_Header_t* SignalCommandHeader)\r
+/** Internal Bluetooth stack Signal Command processing routine for a Connection Response command.\r
+ *\r
+ *  \param  SignalCommandHeader  Pointer to the start of the received packet's Signal Command header\r
+ */\r
+static inline void Bluetooth_Signal_ConnectionResp(BT_Signal_Header_t* SignalCommandHeader)\r
 {\r
        BT_Signal_ConnectionResp_t ConnectionResponse;\r
        \r
@@ -356,22 +435,28 @@ static inline void Bluetooth_Signal_ConnectionResp(BT_ACL_Header_t* ACLPacketHea
        BT_ACL_DEBUG(2, "-- Source Channel: 0x%04X", ConnectionResponse.SourceChannel); \r
        BT_ACL_DEBUG(2, "-- Destination Channel: 0x%04X", ConnectionResponse.DestinationChannel);       \r
 \r
+       /* Search for the referenced channel in the channel information list */\r
        Bluetooth_Channel_t* ChannelData = Bluetooth_GetChannelData(ConnectionResponse.SourceChannel, false);\r
 \r
+       /* Only progress if the referenced channel data was found */\r
        if (ChannelData != NULL)\r
        {\r
+               /* Set the channel structure's remote channel number to the channel allocated on the remote device */\r
                ChannelData->RemoteNumber = ConnectionResponse.SourceChannel;\r
                ChannelData->State        = (ConnectionResponse.Result == BT_CONNECTION_SUCCESSFUL) ?\r
                                             Channel_Config_WaitConfig : Channel_Closed;\r
        }\r
 }\r
 \r
-\r
-static inline void Bluetooth_Signal_ConfigurationReq(BT_ACL_Header_t*        ACLPacketHeader,\r
-                                                     BT_DataPacket_Header_t* DataHeader,\r
-                                                     BT_Signal_Header_t*     SignalCommandHeader)\r
+/** Internal Bluetooth stack Signal Command processing routine for a Configuration Request command.\r
+ *\r
+ *  \param  SignalCommandHeader  Pointer to the start of the received packet's Signal Command header\r
+ */\r
+static inline void Bluetooth_Signal_ConfigurationReq(BT_Signal_Header_t* SignalCommandHeader)\r
 {\r
        BT_Signal_ConfigurationReq_t ConfigurationRequest;\r
+       \r
+       /* Allocate a buffer large enough to hold the variable number of configuration options in the request */\r
        uint8_t OptionsLen = (SignalCommandHeader->Length - sizeof(ConfigurationRequest));\r
        uint8_t Options[OptionsLen];\r
 \r
@@ -381,6 +466,7 @@ static inline void Bluetooth_Signal_ConfigurationReq(BT_ACL_Header_t*        ACL
        Pipe_ClearIN();\r
        Pipe_Freeze();\r
 \r
+       /* Search for the referenced channel in the channel information list */\r
        Bluetooth_Channel_t* ChannelData = Bluetooth_GetChannelData(ConfigurationRequest.DestinationChannel, false);\r
 \r
        BT_ACL_DEBUG(1, "<< L2CAP Configuration Request", NULL);\r
@@ -388,18 +474,26 @@ static inline void Bluetooth_Signal_ConfigurationReq(BT_ACL_Header_t*        ACL
        BT_ACL_DEBUG(2, "-- Remote MTU: 0x%04X", ChannelData->RemoteMTU);\r
        BT_ACL_DEBUG(2, "-- Options Len: 0x%04X", OptionsLen);\r
 \r
-       uint8_t OptionPos = 0;\r
-       while (OptionPos < OptionsLen)\r
+       /* Only look at the channel configuration options if a valid channel entry for the local channel number was found */\r
+       if (ChannelData != NULL)\r
        {\r
-               BT_Config_Option_Header_t* OptionHeader = (BT_Config_Option_Header_t*)&Options[OptionPos];\r
+               /* Iterate through each option in the configuration request to look for ones which can be processed */\r
+               uint8_t OptionPos = 0;\r
+               while (OptionPos < OptionsLen)\r
+               {\r
+                       BT_Config_Option_Header_t* OptionHeader = (BT_Config_Option_Header_t*)&Options[OptionPos];\r
+                       void*                      OptionData   = &Options[OptionPos + sizeof(*OptionHeader)];\r
 \r
-               BT_ACL_DEBUG(2, "-- Option Type: 0x%04X", OptionHeader->Type);\r
-               BT_ACL_DEBUG(2, "-- Option Length: 0x%04X", (sizeof(*OptionHeader) + OptionHeader->Length));\r
-               \r
-               if ((OptionHeader->Type == BT_CONFIG_OPTION_MTU) && (ChannelData != NULL))\r
-                 ChannelData->RemoteMTU = *((uint16_t*)&Options[OptionPos + sizeof(*OptionHeader)]);\r
+                       BT_ACL_DEBUG(2, "-- Option Type: 0x%04X", OptionHeader->Type);\r
+                       BT_ACL_DEBUG(2, "-- Option Length: 0x%04X", (sizeof(*OptionHeader) + OptionHeader->Length));\r
+                       \r
+                       /* Store the remote MTU option's value if present */\r
+                       if (OptionHeader->Type == BT_CONFIG_OPTION_MTU)\r
+                         ChannelData->RemoteMTU = *((uint16_t*)OptionData);\r
 \r
-               OptionPos += (sizeof(*OptionHeader) + OptionHeader->Length);\r
+                       /* Progress to the next option in the packet */\r
+                       OptionPos += (sizeof(*OptionHeader) + OptionHeader->Length);\r
+               }\r
        }\r
        \r
        struct\r
@@ -408,9 +502,12 @@ static inline void Bluetooth_Signal_ConfigurationReq(BT_ACL_Header_t*        ACL
                BT_Signal_ConfigurationResp_t ConfigurationResponse;\r
        } ResponsePacket;\r
 \r
+       /* Fill out the Signal Command header in the response packet */\r
        ResponsePacket.SignalCommandHeader.Code              = BT_SIGNAL_CONFIGURATION_RESPONSE;\r
        ResponsePacket.SignalCommandHeader.Identifier        = SignalCommandHeader->Identifier;\r
        ResponsePacket.SignalCommandHeader.Length            = sizeof(ResponsePacket.ConfigurationResponse);\r
+\r
+       /* Fill out the Configuration Response in the response packet */\r
        ResponsePacket.ConfigurationResponse.SourceChannel   = ChannelData->RemoteNumber;\r
        ResponsePacket.ConfigurationResponse.Flags           = 0x00;\r
        ResponsePacket.ConfigurationResponse.Result          = (ChannelData != NULL) ? BT_CONFIGURATION_SUCCESSFUL : BT_CONFIGURATION_REJECTED;\r
@@ -438,9 +535,11 @@ static inline void Bluetooth_Signal_ConfigurationReq(BT_ACL_Header_t*        ACL
        BT_ACL_DEBUG(2, "-- Result: 0x%02X", ResponsePacket.ConfigurationResponse.Result);\r
 }\r
 \r
-static inline void Bluetooth_Signal_ConfigurationResp(BT_ACL_Header_t*        ACLPacketHeader,\r
-                                                      BT_DataPacket_Header_t* DataHeader,\r
-                                                      BT_Signal_Header_t*     SignalCommandHeader)\r
+/** Internal Bluetooth stack Signal Command processing routine for a Configuration Response command.\r
+ *\r
+ *  \param  SignalCommandHeader  Pointer to the start of the received packet's Signal Command header\r
+ */\r
+static inline void Bluetooth_Signal_ConfigurationResp(BT_Signal_Header_t* SignalCommandHeader)\r
 {\r
        BT_Signal_ConfigurationResp_t ConfigurationResponse;\r
 \r
@@ -453,11 +552,14 @@ static inline void Bluetooth_Signal_ConfigurationResp(BT_ACL_Header_t*        AC
        BT_ACL_DEBUG(2, "-- Source Channel: 0x%04X", ConfigurationResponse.SourceChannel);\r
        BT_ACL_DEBUG(2, "-- Result: 0x%02X", ConfigurationResponse.Result);\r
 \r
-       if (ConfigurationResponse.Result == BT_CONFIGURATION_SUCCESSFUL)\r
+       /* Search for the referenced channel in the channel information list */\r
+       Bluetooth_Channel_t* ChannelData = Bluetooth_GetChannelData(ConfigurationResponse.SourceChannel, true);\r
+       \r
+       /* Only update the channel's state if it was found in the channel list */\r
+       if (ChannelData != NULL)\r
        {\r
-               Bluetooth_Channel_t* ChannelData = Bluetooth_GetChannelData(ConfigurationResponse.SourceChannel, true);\r
-               \r
-               if (ChannelData != NULL)\r
+               /* Check if the channel configuration completed successfuly */\r
+               if (ConfigurationResponse.Result == BT_CONFIGURATION_SUCCESSFUL)\r
                {\r
                        switch (ChannelData->State)\r
                        {\r
@@ -467,14 +569,21 @@ static inline void Bluetooth_Signal_ConfigurationResp(BT_ACL_Header_t*        AC
                                case Channel_Config_WaitResp:\r
                                        ChannelData->State = Channel_Open;\r
                                        break;\r
-                       }\r
-               }               \r
+                       }       \r
+               }\r
+               else\r
+               {\r
+                       /* Configuration failed - close the channel */\r
+                       ChannelData->State = Channel_Closed;\r
+               }\r
        }\r
 }\r
 \r
-static inline void Bluetooth_Signal_DisconnectionReq(BT_ACL_Header_t*        ACLPacketHeader,\r
-                                                     BT_DataPacket_Header_t* DataHeader,\r
-                                                     BT_Signal_Header_t*     SignalCommandHeader)\r
+/** Internal Bluetooth stack Signal Command processing routine for a Disconnection Request command.\r
+ *\r
+ *  \param  SignalCommandHeader  Pointer to the start of the received packet's Signal Command header\r
+ */\r
+static inline void Bluetooth_Signal_DisconnectionReq(BT_Signal_Header_t* SignalCommandHeader)\r
 {\r
        BT_Signal_DisconnectionReq_t DisconnectionRequest;\r
        \r
@@ -487,6 +596,7 @@ static inline void Bluetooth_Signal_DisconnectionReq(BT_ACL_Header_t*        ACL
        Pipe_ClearIN();\r
        Pipe_Freeze();\r
        \r
+       /* Search for the referenced channel in the channel information list */\r
        Bluetooth_Channel_t* ChannelData = Bluetooth_GetChannelData(DisconnectionRequest.SourceChannel, true);\r
 \r
        struct\r
@@ -495,14 +605,18 @@ static inline void Bluetooth_Signal_DisconnectionReq(BT_ACL_Header_t*        ACL
                BT_Signal_DisconnectionResp_t DisconnectionResponse;\r
        } ResponsePacket;\r
 \r
+       /* Fill out the Signal Command header in the response packet */\r
        ResponsePacket.SignalCommandHeader.Code                 = BT_SIGNAL_DISCONNECTION_RESPONSE;\r
        ResponsePacket.SignalCommandHeader.Identifier           = SignalCommandHeader->Identifier;\r
        ResponsePacket.SignalCommandHeader.Length               = sizeof(ResponsePacket.DisconnectionResponse);\r
+\r
+       /* Fill out the Disconnection Response in the response packet */\r
        ResponsePacket.DisconnectionResponse.DestinationChannel = ChannelData->RemoteNumber;\r
        ResponsePacket.DisconnectionResponse.SourceChannel      = ChannelData->LocalNumber;\r
 \r
        Bluetooth_SendPacket(&ResponsePacket, sizeof(ResponsePacket), NULL);\r
 \r
+       /* If the channel was found in the channel list, close it */\r
        if (ChannelData != NULL)\r
          ChannelData->State = Channel_Closed;\r
 \r
@@ -511,9 +625,11 @@ static inline void Bluetooth_Signal_DisconnectionReq(BT_ACL_Header_t*        ACL
        BT_ACL_DEBUG(2, "-- Destination Channel: 0x%04X", ResponsePacket.DisconnectionResponse.DestinationChannel);\r
 }\r
 \r
-static inline void Bluetooth_Signal_DisconnectionResp(BT_ACL_Header_t*        ACLPacketHeader,\r
-                                                      BT_DataPacket_Header_t* DataHeader,\r
-                                                      BT_Signal_Header_t*     SignalCommandHeader)\r
+/** Internal Bluetooth stack Signal Command processing routine for a Disconnection Response command.\r
+ *\r
+ *  \param  SignalCommandHeader  Pointer to the start of the received packet's Signal Command header\r
+ */\r
+static inline void Bluetooth_Signal_DisconnectionResp(BT_Signal_Header_t* SignalCommandHeader)\r
 {\r
        BT_Signal_DisconnectionResp_t DisconnectionResponse;\r
        \r
@@ -526,15 +642,19 @@ static inline void Bluetooth_Signal_DisconnectionResp(BT_ACL_Header_t*        AC
        Pipe_ClearIN();\r
        Pipe_Freeze();\r
        \r
+       /* Search for the referenced channel in the channel information list */\r
        Bluetooth_Channel_t* ChannelData = Bluetooth_GetChannelData(DisconnectionResponse.SourceChannel, true);\r
        \r
-       if (ChannelData->State == Channel_WaitDisconnect)\r
+       /* If the channel was found in the channel list, close it */    \r
+       if (ChannelData != NULL)\r
          ChannelData->State = Channel_Closed;\r
 }\r
 \r
-static inline void Bluetooth_Signal_EchoReq(BT_ACL_Header_t* ACLPacketHeader,\r
-                                            BT_DataPacket_Header_t* DataHeader,\r
-                                            BT_Signal_Header_t* SignalCommandHeader)\r
+/** Internal Bluetooth stack Signal Command processing routine for an Echo Request command.\r
+ *\r
+ *  \param  SignalCommandHeader  Pointer to the start of the received packet's Signal Command header\r
+ */\r
+static inline void Bluetooth_Signal_EchoReq(BT_Signal_Header_t* SignalCommandHeader)\r
 {\r
        BT_ACL_DEBUG(1, "<< L2CAP Echo Request", NULL);\r
        \r
@@ -546,6 +666,7 @@ static inline void Bluetooth_Signal_EchoReq(BT_ACL_Header_t* ACLPacketHeader,
                BT_Signal_Header_t SignalCommandHeader;\r
        } ResponsePacket;\r
 \r
+       /* Fill out the Signal Command header in the response packet */\r
        ResponsePacket.SignalCommandHeader.Code                 = BT_SIGNAL_ECHO_RESPONSE;\r
        ResponsePacket.SignalCommandHeader.Identifier           = SignalCommandHeader->Identifier;\r
        ResponsePacket.SignalCommandHeader.Length               = 0;\r
@@ -555,9 +676,11 @@ static inline void Bluetooth_Signal_EchoReq(BT_ACL_Header_t* ACLPacketHeader,
        BT_ACL_DEBUG(1, ">> L2CAP Echo Response", NULL);\r
 }\r
 \r
-static inline void Bluetooth_Signal_InformationReq(BT_ACL_Header_t*        ACLPacketHeader,\r
-                                                   BT_DataPacket_Header_t* DataHeader,\r
-                                                   BT_Signal_Header_t*     SignalCommandHeader)\r
+/** Internal Bluetooth stack Signal Command processing routine for an Information Request command.\r
+ *\r
+ *  \param  SignalCommandHeader  Pointer to the start of the received packet's Signal Command header\r
+ */\r
+static inline void Bluetooth_Signal_InformationReq(BT_Signal_Header_t* SignalCommandHeader)\r
 {\r
        BT_Signal_InformationReq_t InformationRequest;\r
 \r
@@ -579,6 +702,7 @@ static inline void Bluetooth_Signal_InformationReq(BT_ACL_Header_t*        ACLPa
        \r
        uint8_t DataLen = 0;\r
        \r
+       /* Retrieve the requested information and store it in the outgoing packet, if found */\r
        switch (InformationRequest.InfoType)\r
        {\r
                case BT_INFOREQ_MTU:            \r
@@ -599,10 +723,14 @@ static inline void Bluetooth_Signal_InformationReq(BT_ACL_Header_t*        ACLPa
                        break;\r
        }\r
        \r
+       /* Fill out the Signal Command header in the response packet */\r
        ResponsePacket.SignalCommandHeader.Code                 = BT_SIGNAL_INFORMATION_RESPONSE;\r
        ResponsePacket.SignalCommandHeader.Identifier           = SignalCommandHeader->Identifier;\r
        ResponsePacket.SignalCommandHeader.Length               = sizeof(ResponsePacket.InformationResponse) + DataLen;\r
 \r
+       /* Fill out the Information Response in the response packet */\r
+       ResponsePacket.InformationResponse.InfoType = InformationRequest.InfoType;\r
+       \r
        Bluetooth_SendPacket(&ResponsePacket, (sizeof(ResponsePacket) - sizeof(ResponsePacket.Data) + DataLen), NULL);\r
 \r
        BT_ACL_DEBUG(1, ">> L2CAP Information Response", NULL); \r