docs: start collecting migration info

doc/manual/docs/appendix/migration.md

@@ -0,0 +1,108 @@
+BTstack has grown organically since its creation and mostly kept the APIs compatible.
+After the second listing with the Bluetooth SIG, we decided that it's time for a major overhaul of the API - making easier for new users. This version will be released as v1.0.
+
+In the following, we provide an overview of the changes and guidelines for updating an existing code base.
+
+# Changes
+
+## Project structure
+
+### include folder
+The header files had been split between *src/* and *include/btstack*/. Now, the *include/* folder is gone and the headers are provided in *src/*, *src/classic/*, *src/ble/* or by the *platform/* folders. There's a new "btstack.h" header that includes all BTstack headers.
+
+### Defines
+All defines that originate from the Bluetooth Specification are now in *src/bluetooth.h*. BTstack defines are collected in *src/btstack_defines.h*
+
+### Plural folder names
+Folder with plural names have been renamed to singular, examples: *doc*, *chipset*, *platform*, *tool*.
+
+### ble and src folders
+The *ble* folder has been renamed into *src/ble*. Files only relevant for using BTstack in Classic mode, have been moved to *src/classic*. Files in *src* that are specific to individual platforms are moved to *platform* or *port*.
+
+### platform and port
+The *platforms* folder has been cleaned up. Now, the *port* folder contains a complete port of BTstack for a specific setup consisting of a MCU and a Bluetooth chipset. Code that didn't belong to the BTstack core in *src* have been moved to *platform* or *port*
+
+## Function and file names
+- The _internal suffix has been an artefact from the iOS port. All public functions with the _internal suffix have been stripped of this suffix.
+- Types with generic names like linked_list have been prefixed with btstack_ (e.g. btstack_linked_list) to avoid problems when integrating with other environments like vendor SDKs.
+
+## Event names
+All events names have the form MODULE_EVENT_NAME now.
+
+## Packet Handlers
+We streamlined the use of packet handlers and their types. Most callbacks are now of type *btstack_packet_handler_t* and receive a pointer to an HCI Event packet. Often a void * connection was the first argument - this has been removed resp. pushed up into the BTstack Daemon.
+
+To facilitate working with HCI Events and get rid of manually calculating offsets into packets, we're providing the auto-generated getters for all fields of all elements in *src/hci_event.h*. All functions are defined as static inline, so they are not wasting any program memory.
+
+Feel free to start using these getters as needed. 
+
+## Event forwarding
+In the past, events have been forwarded up the stack with the effect that an app that used the *att_server* and the *security_manager* would get each HCI event twice. This has been cleaned up by providing a way to register multiple listeners for HCI events. 	
+
+## remote_device_db.h
+Has been split into *src/classic/btstack_link_key_db*, *platform/daemon/btstack_device_name_db*, and *platform/daemon/rfcomm_service_db*.
+
+## bt_control.h
+Has been split into *src/btstack_chipset.h* and *src/bstack_control.h*
+
+## Security Manager
+- In all Security Manager calls that refer to an active connection, pass in the current handle instead of addr + addr type.
+- All Security Manager events are now regular HCI Events instead of sm_* structs
+- Multiple packet handler can be registered with sm_add_event_handler()
+
+## RFCOMM
+- Packet handler per service and outgoing connection
+
+## HCI / GAP
+- In hci_init() only the HCI Transport and it's configuration have to be provided. A link key db can be set via hci_set_link_key_db. Similar, hci_set_chipset() and hci_set_control can be called if needed.
+- HCI Event handlers can be registered with hci_add_event_handler
+- HCI functions that are commonly placed in GAP have been moved from *src/hci.h* to *src/gap.h*
+
+## btstack_util.h
+- The functions to read/store values in little/bit endian have been renamed into bit/little_endian_read/write_16/24/32.
+- swapX -> reverse_x
+
+## Linked List
+- Renamed to btstack_linked_list
+- Removed user data field
+
+## Timers
+- Added context field
+
+## Run Loop
+- Run loop type selection via implementation run_loop_t struct (see run_loop_NAME_instance())
+
+## GATT Client
+- All GATT Client events are now regular HCI Events instead of gatt_* structs.
+- The subclient_id has been replaced by a complete handler for GATT Client requests
+
+## ANCS Client
+Renamed to *src/ble/ancs_client*
+
+## SDP Server
+- Has been renamed to */src/sdp_server*.
+- The API for adding a service record was different for 
+
+## SDP Client
+- SDP Query structs have been repalced by HCI events
+
+
+## btstack_config.h
+- *btstack-config.h* is now *btstack_config.h*
+- Defines have been sorted. HAVE_ specify features that are particular to your port. ENABLE_ features can then be added as needed
+- EMBEDDED dropped
+
+## Flow control / DAEMON_EVENT_PACKET_SENT
+- TODO -- don't hand out local credits
+
+## Daemon
+- Moved into *platform/daemon/*. Not tested yet.
+- Header for clients: *platform/daemon/btstack_client.h*
+- Java bindings are now at *platform/daemon/bindings*
+
+## Unsorted
+
+
+
+# Migration
+

doc/manual/mkdocs.yml

@@ -1,6 +1,6 @@
 site_name: BTstack Manual v1.0
 site_dir: btstack
-docs_dir: docs_final
+docs_dir: docs
 pages:
 - [index.md, Welcome]
 - [quick_start.md, Quick Start]
@@ -13,4 +13,5 @@ pages:
 - [integration.md, Integrating with Existing Systems]
 - [appendix/apis.md, APIs]
 - [appendix/events_errors.md, Events and Errors]
-theme: readthedocs
+- [appendix/migration.md, Migration to v1.0]
+theme: readthedocs