BLE: Add ATT_MTU and Data Length docs

docs/api/bluetooth/Gap.md

@@ -52,6 +52,14 @@ You may set preferred PHYs (separately for RX and TX) using `setPreferredPhys()`
 
 You may query the currently used PHY using `readPhy()`, which returns the result through a call to the registered event handler. You may register the handler with `setEventHandler()`. The events inform about the currently used PHY and of any changes to PHYs, which the controller or the peer may trigger autonomously.
 
+#### Data Length (over-the-air MTU)
+
+In addition to modulation schemes, MTU (Maximum Transmission Unit) size also strongly affects throughput. Newer controllers will allow you to negotiate bigger MTUs. Since each packet contains overhead bigger packets maximise throughput.
+
+There are two separate MTUs to consider: the ATT_MTU (maximum attribute size) and Data Length. ATT_MTU is dealt with in `GattServer` and `GattClient`. `Gap` only deals with Data Length which is the maximum size of the packet that carries attributes which are fragmented across many such packets. ATT_MTU and Data Length are independent of each other.
+
+The default value of Data Length supported by all controllers is 23 octets. If both controllers support Data Length Extension and a higher value is negotiated `onDataLengthChange` in the `Gap::EventHandler` will be called. 
+
 ### GAP class reference
 
 [![View code](https://www.mbed.com/embed/?type=library)](https://os.mbed.com/docs/development/mbed-os-api-doxy/class_gap.html)

docs/api/bluetooth/GattClient.md

@@ -16,6 +16,14 @@ As a result of the discovery process, the client can start interacting with the
 
 Mbed BLE abstracts read and write operations to offer a single API that can be used to read or write characteristic values. The application code does not have to handle the necessary fragmentation or reassembly process if the attribute value to be transported can't fit in a single data packet.
 
+#### ATT_MTU
+
+ATT_MTU is the maximum size of the attribute that can fit in an L2CAP packet. This is independent of the Data Length which controls the over-the-air packet payload size (which is dealt with in the GAP). An L2CAP packet will be fragmented over many such packets if required.
+
+Only `GattClient` can trigger the exchange of ATT_MTU between client and server. The host may trigger the exchange which may also be requested manually using `negotiateAttMtu`. If an exchange happens the biggest value possible across both devices will be used. Negotiation is only a best effort process and does not guarantee a higher value being set. 
+
+ATT_MTU is at least 23 octets by default. If a larger size is negotiated the user application will be informed through the `onAttMtuChange` function called in the `GattClient::EventHandler` (`GattServer::EventHandler` will also be informed).
+
 #### Server initiated events
 
 When a server updates a characteristic value, it can forward the new value to any registered clients. Clients may register for these updates on a per-characteristic basis. The server sends the updates by using notifications (no confirmation from client) or indications (client confirms receipt). This mechanism minimizes the number of transactions between a client and a server by avoiding polling.

docs/api/bluetooth/GattServer.md

@@ -14,6 +14,14 @@ You must access values of the characteristic and the characteristic descriptor p
 
 You can query the server by invoking the function `areUpdatesEnabled()` to find out if a client has subscribed to a given characteristic's value update.
 
+#### ATT_MTU
+
+ATT_MTU is the maximum size of the attribute that can fit in an L2CAP packet. This is independent of the Data Length which controls the over-the-air packet payload size (which is dealt with in the GAP). An L2CAP packet will be fragmented over many such packets if required.
+
+Only `GattClient` can trigger the exchange of ATT_MTU between client and server. If an exchange happens the biggest value possible across both devices will be used. 
+
+ATT_MTU is at least 23 octets by default. If a larger size is negotiated the user application will be informed through the `onAttMtuChange` function called in the `GattServer::EventHandler` (`GattClient::EventHandler` will also be informed).
+
 #### Events
 
 You can register several event handlers with the GattServer that it will call to notify you of client (remote application connected to the server) and server activities: