Update docs

MaJerle · Dec 28, 2019 · 94d4801 · 94d4801
1 parent 5f28ebb
commit 94d4801
Show file tree

Hide file tree

Showing 13 changed files with 149 additions and 27 deletions.
diff --git a/docs/api-reference/config.rst b/docs/api-reference/config.rst
@@ -0,0 +1,12 @@
+.. _api_ow_config:
+
+OW Configuration
+================
+
+This is the default configuration of the middleware.
+When any of the settings shall be modified, it shall be done in dedicated application config ``ow_config.h`` file.
+
+.. note::
+	Check :ref:`get_started` to create configuration file.
+
+.. doxygengroup:: OW_CONFIG
diff --git a/docs/api-reference/index.rst b/docs/api-reference/index.rst
@@ -7,8 +7,8 @@ List of all the modules:
 
 .. toctree::
 	:maxdepth: 2
-	:glob:
 
-	*
-	*/index
-
+	ow
+	config
+	port/index
+	devices/index
diff --git a/docs/api-reference/ow_config.rst b/docs/api-reference/ow_config.rst
diff --git a/docs/api-reference/ow_sys.rst b/docs/api-reference/ow_sys.rst
diff --git a/docs/api-reference/port/index.rst b/docs/api-reference/port/index.rst
@@ -0,0 +1,13 @@
+.. _api_ow_port:
+
+Platform specific
+=================
+
+List of all the modules:
+
+.. toctree::
+	:maxdepth: 2
+
+	ll
+	sys
+
diff --git a/docs/api-reference/ow_ll.rst → docs/api-reference/port/ll.rst b/docs/api-reference/ow_ll.rst → docs/api-reference/port/ll.rst
@@ -1,6 +1,6 @@
 .. _api_ow_ll:
 
-Low-level functions
-===================
+Low-level driver
+================
 
 .. doxygengroup:: OW_LL
diff --git a/docs/api-reference/port/sys.rst b/docs/api-reference/port/sys.rst
@@ -0,0 +1,15 @@
+.. _api_ow_sys:
+
+System functions
+================
+
+System function are used in conjunction with thread safety.
+These are required when operating system is used and multiple threads
+want to access to the same OneWire instance.
+
+.. tip::
+	Check :ref:`um_thread_safety` and :ref:`um_porting_guide` for instructions on how to port.
+
+Below is a list of function prototypes and its implementation details.
+
+.. doxygengroup:: OW_SYS
diff --git a/docs/user-manual/how-it-works.rst b/docs/user-manual/how-it-works.rst
@@ -1,9 +1,18 @@
-.. _how_it_works:
+.. _um_how_it_works:
 
 How it works
 ============
 
+OneWire-UART library tends to use *UART* hardware of any microcontroller/embedded system,
+to generate timing clock for OneWire signals.
 
+Nowaways embedded systems allow many UART ports, usually many more vs requirements for the final application.
+OneWire protocol needs precise timings and embedded systems (in 99.9%) do not have specific hardware to handle communication of this type.
+
+Fortunately, OneWire timings match with UART timings at ``9600`` and ``115200`` bauds.
+
+.. note::
+	Check `detailed tutorial from Maxim <https://www.maximintegrated.com/en/design/technical-documents/tutorials/2/214.html>`_ for more information.
 
 .. toctree::
     :maxdepth: 2
diff --git a/docs/user-manual/hw_connection.rst → docs/user-manual/hw-connection.rst b/docs/user-manual/hw_connection.rst → docs/user-manual/hw-connection.rst
diff --git a/docs/user-manual/index.rst b/docs/user-manual/index.rst
@@ -8,5 +8,6 @@ User manual
 
     how-it-works
     thread-safety
-    hw_connection
-    uart_timing
+    hw-connection
+    uart-timing
+    porting-guide
diff --git a/docs/user-manual/porting-guide.rst b/docs/user-manual/porting-guide.rst
@@ -0,0 +1,87 @@
+.. _um_porting_guide:
+
+Porting guide
+=============
+
+Implement low-level driver
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Implementation of low-level driver is an essential part.
+It links middleware with actual hardware design of the device.
+
+Its implementation must provide ``4`` functions:
+
+* To open/configure UART hardware
+* To set UART baudrate on the fly
+* To transmit/receive data over UART
+* To close/de-init UART hardware
+
+After these functions have been implemented (check below for references),
+driver must link these functions to single driver structure of type :cpp:type:`ow_ll_drv_t`,
+later used during instance initialization.
+
+.. tip::
+	Check :ref:`api_ow_ll` for function prototypes.
+
+Implement system functions
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+System functions are required only if operating system mode is enabled, with :c:macro:`OW_CFG_OS`.
+
+Its implementation structure is not the same as for low-level driver,
+customer needs to implement fixed functions, with pre-defined name, starting with ``ow_sys_`` name.
+
+System function must only support OS mutex management and has to provide:
+
+* :cpp:func:`ow_sys_mutex_create` function to create new mutex
+* :cpp:func:`ow_sys_mutex_delete` function to delete existing mutex
+* :cpp:func:`ow_sys_mutex_wait` function to wait for mutex to be available
+* :cpp:func:`ow_sys_mutex_release` function to release (give) mutex back
+
+.. warning::
+	Application must define :c:macro:`OW_CFG_OS_MUTEX_HANDLE` for mutex type.
+	This shall be done in ``ow_config.h`` file.
+
+.. tip::
+	Check :ref:`api_ow_sys` for function prototypes.
+
+Example: Low-level driver for WIN32
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Example code for low-level porting on `WIN32` platform.
+It uses native *Windows* features to open *COM* port and read/write from/to it.
+
+.. literalinclude:: ../../onewire_uart/src/system/ow_ll_win32.c
+    :language: c
+    :linenos:
+    :caption: Actual implementation of low-level driver for WIN32
+
+Example: Low-level driver for STM32
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Example code for low-level porting on `STM32` platform.
+
+.. literalinclude:: ../../onewire_uart/src/system/ow_ll_stm32.c
+    :language: c
+    :linenos:
+    :caption: Actual implementation of low-level driver for STM32
+
+Example: System functions for WIN32
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. literalinclude:: ../../onewire_uart/src/system/ow_sys_win32.c
+    :language: c
+    :linenos:
+    :caption: Actual implementation of system functions for WIN32
+
+Example: System functions for CMSIS-OS
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. literalinclude:: ../../onewire_uart/src/system/ow_sys_cmsis_os.c
+    :language: c
+    :linenos:
+    :caption: Actual implementation of system functions for CMSIS-OS
+
+
+.. toctree::
+    :maxdepth: 2
diff --git a/docs/user-manual/thread-safety.rst b/docs/user-manual/thread-safety.rst
@@ -1,4 +1,4 @@
-.. _thread_safety:
+.. _um_thread_safety:
 
 Thread safety
 =============

diff --git a/docs/user-manual/uart_timing.rst → docs/user-manual/uart-timing.rst b/docs/user-manual/uart_timing.rst → docs/user-manual/uart-timing.rst
@@ -1,7 +1,7 @@
-.. _uart_timing:
+.. _um_uart_timing:
 
 UART and 1-Wire timing relation
-================================
+===============================
 
 This part is explaining how UART and 1-Wire timings are connected together and what is important to take into consideration for stable and reliable communication.