BLE: Add ATT_MTU and Data Length docs

docs/api/bluetooth/Gap.md

@@ -52,6 +52,16 @@ 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, Maximum Transmission Unit (MTU) size also strongly affects throughput. Newer controllers allow you to negotiate bigger MTUs. Because each packet contains overhead, bigger packets maximize throughput.
+
+There are two separate MTUs to consider: the `ATT_MTU` (maximum attribute size) and data length. `GattServer` and `GattClient` affect `ATT_MTU`. `Gap` only deals with data length, which is the maximum size of the packet that carries attributes that are fragmented across many such packets.
+
+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.
+
+`ATT_MTU` and data length are independent of each other. 
+
 ### 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

@@ -1,6 +1,6 @@
 ## GattClient
 
-GattClient defines procedures required for interacting with a remote GattServer.
+Generic Attribute Profile (GATT) is used to discover services, characteristics and descriptors and to perform operations on them. The interaction happens between two peers, one of which is the client (who initiates interactions) and the other the server (which responds). Attribute Protocol (ATT) is used to implement this interaction. `GattClient` defines procedures required for interacting with a remote `GattServer`.
 
 #### Discovery procedures
 
@@ -16,6 +16,16 @@ 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.
 
+#### Attribute Protocol Maximum Transmission Unit (ATT_MTU)
+
+ATT_MTU is the maximum size of the attribute protocol packet. Operation on attributes too large to fit into a single packet will be split across multiple operations.
+
+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 containing the attribute protocol packet will be fragmented over many such packets if required.
+
+Only `GattClient` can trigger the exchange of ATT_MTU between client and server. Depending on the implementation of the bluetooth stack the client may trigger the exchange upon connection. The exchange 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

@@ -1,6 +1,8 @@
 ## GattServer
 
-A GattServer is a collection of GattServices. These services contain characteristics that a peer connected to the device may read or write. These characteristics may also emit updates to subscribed clients when their values change.
+Generic Attribute Profile (GATT) is used to discover services, characteristics and descriptors and to perform operations on them. The interaction happens between two peers, one of which is the client (who initiates interactions) and the other the server (which responds). Attribute Protocol (ATT) is used to implement this interaction.
+
+'GattServer' is a collection of GattServices. These services contain characteristics that a `GattClient` on the peer connected to the device may read or write. These characteristics may also emit updates to subscribed clients when their values change.
 
 #### Server layout
 
@@ -14,6 +16,16 @@ 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.
 
+#### Attribute Protocol Maximum Transmission Unit (ATT_MTU)
+
+ATT_MTU is the maximum size of the attribute protocol packet. Operation on attributes too large to fit into a single packet will be split across multiple operations.
+
+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 containing the attribute protocol 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: