Added Doxygen Support & mostly documented pin.h please check ./build/html/index.html

CMakeLists.txt

@@ -74,6 +74,29 @@ endif()
 add_custom_command(TARGET ${EXECUTABLE}
         POST_BUILD
 		COMMAND ${CMAKE_SIZE} ${EXECUTABLE})
+
+####################################################################################################
+#DOXYGEN
+####################################################################################################
+find_package(Doxygen)
+if (DOXYGEN_FOUND)
+    # set input and output files
+    set(DOXYGEN_IN ${CMAKE_CURRENT_SOURCE_DIR}/doxyfile.in)
+    set(DOXYGEN_OUT ${CMAKE_CURRENT_BINARY_DIR}/doxyfile)
+
+    # request to configure the file
+    configure_file(${DOXYGEN_IN} ${DOXYGEN_OUT} @ONLY)
+    message("Doxygen build started")
+
+    # note the option ALL which allows to build the docs together with the application
+    add_custom_target( doc_doxygen ALL
+        COMMAND ${DOXYGEN_EXECUTABLE} ${DOXYGEN_OUT}
+        WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}
+        COMMENT "Generating API documentation with Doxygen"
+        VERBATIM )
+else (DOXYGEN_FOUND)
+  message("Doxygen need to be installed to generate the doxygen documentation")
+endif (DOXYGEN_FOUND)
 ####################################################################################################
 #CUSTOM Comments from dev.
 ####################################################################################################

bsl/csl/interfaces/pin.h

@@ -1,21 +1,25 @@
-/************************************************************************************************
+/**
- * Authors	: Kerem Yollu & Edwin Koch
+  **************************************************************************************************
- * Date		: 01.11.2021
+  * @file		pin.h
- * Version	: 1.0
+  * @author		Kerem Yollu & Edwin Koch
- *
+  * @date		01.11.2021
- * Description : 
+  * @version	1.0
- * This header file for pin control is based on the most common configuation options
+  ************************************************************************************************** 
- * curenty awailable for modern hardware. 
+  * @brief		pin functionalities description and implementation template
- * Depending of the used Chip, some function may vary or be unawailable. 
+  * 
- * Please take a minute to go and explore the according Chips pin.c file to see woh each function 
+  * **Detailed Description :**
- * is implmented.  
+  * 
- *
+  * This header file for pin control is based on the most common configuation options
- * TODO: 
+  * curenty awailable for modern hardware. 
- *  - 01.11.2021 : Should we add a seprate header in the cls layer containing the pinNo_t ?
+  * Depending of the used Chip, some function may vary or be unawailable. 
- *	- 01.11.2021 : Depending on request implment a pinLock() function
+  * Please take a minute to go and explore the according Chips pin.c file to see woh each function 
- *	 
+  * is implmented.  
- * LICENCE	: Please check the end of this file
+  *
-************************************************************************************************/
+  * @todo 
+  * - 01.11.2021 : Should we add a seprate header in the cls layer containing the pinNo_t ?
+  *	- 01.11.2021 : Depending on request implment a pinLock() function
+  **************************************************************************************************
+*/
 
 #ifndef _GPIO_H_
 #define _GPIO_H_
@@ -24,94 +28,98 @@
 extern "C" {
 #endif
 
-#include <unistd.h>
 #include <stdint.h>
 
-
 #ifdef ARM_MCU
 #include "../stm32f042/Drivers/CMSIS/Device/ST/STM32F0xx/Include/stm32f042x6.h"
+	/*! Enum of the awailable pins for this package */
 	typedef enum 
 	{
-	//	NAME  = BASE ADDR   | PORT | PIN NO
+	//  NAME  = BASE ADDR   | PORT | PIN NO
-		pinA0 = GPIOA_BASE  | 0x00 | 0,
+		pinA0 = GPIOA_BASE  | 0x00 | 0, /*!< Port: A Pin: 0  -> GPIOA_BASE | Port A Mask | Pin Mask */
-		pinA1 = GPIOA_BASE	| 0x00 | 1,
+		pinA1 = GPIOA_BASE	| 0x00 | 1,	/*!< Port: A Pin: 1  -> GPIOA_BASE | Port A Mask | Pin Mask */
-		pinA2 = GPIOA_BASE	| 0x00 | 2,
+		pinA2 = GPIOA_BASE	| 0x00 | 2,	/*!< Port: A Pin: 2  -> GPIOA_BASE | Port A Mask | Pin Mask */
-		pinA3 = GPIOA_BASE	| 0x00 | 3,
+		pinA3 = GPIOA_BASE	| 0x00 | 3,	/*!< Port: A Pin: 3  -> GPIOA_BASE | Port A Mask | Pin Mask */
-		pinA4 = GPIOA_BASE	| 0x00 | 4,
+		pinA4 = GPIOA_BASE	| 0x00 | 4,	/*!< Port: A Pin: 4  -> GPIOA_BASE | Port A Mask | Pin Mask */
-		pinA5 = GPIOA_BASE	| 0x00 | 5,
+		pinA5 = GPIOA_BASE	| 0x00 | 5,	/*!< Port: A Pin: 5  -> GPIOA_BASE | Port A Mask | Pin Mask */
-		pinA6 = GPIOA_BASE	| 0x00 | 6,
+		pinA6 = GPIOA_BASE	| 0x00 | 6,	/*!< Port: A Pin: 6  -> GPIOA_BASE | Port A Mask | Pin Mask */
-		pinA7 = GPIOA_BASE	| 0x00 | 7,
+		pinA7 = GPIOA_BASE	| 0x00 | 7,	/*!< Port: A Pin: 7  -> GPIOA_BASE | Port A Mask | Pin Mask */
-		pinA8 = GPIOA_BASE	| 0x00 | 8,
+		pinA8 = GPIOA_BASE	| 0x00 | 8,	/*!< Port: A Pin: 8  -> GPIOA_BASE | Port A Mask | Pin Mask */
-		pinA9 = GPIOA_BASE	| 0x00 | 9,
+		pinA9 = GPIOA_BASE	| 0x00 | 9,	/*!< Port: A Pin: 9  -> GPIOA_BASE | Port A Mask | Pin Mask */
-		pinA10 = GPIOA_BASE | 0x00 | 10,
+		pinA10 = GPIOA_BASE | 0x00 | 10,/*!< Port: A Pin: 10 -> GPIOA_BASE | Port A Mask | Pin Mask */
-		pinA11 = GPIOA_BASE | 0x00 | 11,
+		pinA11 = GPIOA_BASE | 0x00 | 11,/*!< Port: A Pin: 11 -> GPIOA_BASE | Port A Mask | Pin Mask */
-		pinA12 = GPIOA_BASE | 0x00 | 12,
+		pinA12 = GPIOA_BASE | 0x00 | 12,/*!< Port: A Pin: 12 -> GPIOA_BASE | Port A Mask | Pin Mask */
-		pinA13 = GPIOA_BASE | 0x00 | 13,
+		pinA13 = GPIOA_BASE | 0x00 | 13,/*!< Port: A Pin: 13 -> GPIOA_BASE | Port A Mask | Pin Mask */
-		pinA14 = GPIOA_BASE | 0x00 | 14,
+		pinA14 = GPIOA_BASE | 0x00 | 14,/*!< Port: A Pin: 14 -> GPIOA_BASE | Port A Mask | Pin Mask */
-		pinA15 = GPIOA_BASE | 0x00 | 15,
+		pinA15 = GPIOA_BASE | 0x00 | 15,/*!< Port: A Pin: 15 -> GPIOA_BASE | Port A Mask | Pin Mask */
-
+
-		pinB0 = GPIOB_BASE	| 0x10 | 0,
+		pinB0 = GPIOB_BASE	| 0x10 | 0,	/*!< Port: B Pin: 0  -> GPIOB_BASE | Port B Mask | Pin Mask */
-		pinB1 = GPIOB_BASE	| 0x10 | 1,
+		pinB1 = GPIOB_BASE	| 0x10 | 1,	/*!< Port: B Pin: 1  -> GPIOB_BASE | Port B Mask | Pin Mask */
-		pinB3 = GPIOB_BASE	| 0x10 | 3,
+		pinB3 = GPIOB_BASE	| 0x10 | 3,	/*!< Port: B Pin: 3  -> GPIOB_BASE | Port B Mask | Pin Mask */
-		pinB4 = GPIOB_BASE	| 0x10 | 4,
+		pinB4 = GPIOB_BASE	| 0x10 | 4,	/*!< Port: B Pin: 4  -> GPIOB_BASE | Port B Mask | Pin Mask */
-		pinB5 = GPIOB_BASE	| 0x10 | 5,
+		pinB5 = GPIOB_BASE	| 0x10 | 5,	/*!< Port: B Pin: 5  -> GPIOB_BASE | Port B Mask | Pin Mask */
-		pinB6 = GPIOB_BASE	| 0x10 | 6,
+		pinB6 = GPIOB_BASE	| 0x10 | 6,	/*!< Port: B Pin: 6  -> GPIOB_BASE | Port B Mask | Pin Mask */
-		pinB7 = GPIOB_BASE	| 0x10 | 7,
+		pinB7 = GPIOB_BASE	| 0x10 | 7,	/*!< Port: B Pin: 7  -> GPIOB_BASE | Port B Mask | Pin Mask */
-		pinB8 = GPIOB_BASE	| 0x10 | 8,
+		pinB8 = GPIOB_BASE	| 0x10 | 8,	/*!< Port: B Pin: 8  -> GPIOB_BASE | Port B Mask | Pin Mask */
-
+
-		pinF0 = GPIOF_BASE	| 0x20 | 0,
+		pinF0 = GPIOF_BASE	| 0x20 | 0,	/*!< Port: F Pin: 0  -> GPIOF_BASE | Port F Mask | Pin Mask */
-		pinF1 = GPIOF_BASE	| 0x20 | 1
+		pinF1 = GPIOF_BASE	| 0x20 | 1	/*!< Port: F Pin: 1  -> GPIOF_BASE | Port F Mask | Pin Mask */
 	}pinNo_t;
 #endif
 
 #ifdef RASPBERRY
 #endif
 
+/*! Enum of possible Pin Modes */
 typedef enum 
 {
-	undefined,
+	undefined,	/*!< Is the **default** mode */
-	input, 
+	input,		/*!< Set pin as **Input** */
-	output, 
+	output, 	/*!< Set pin as **Output** */
-	analog, 
+	analog, 	/*!< Set pin as **Analog** */
-	alternate
+	alternate	/*!< Set pin as **Alternate** */
-}mode;
+}mode_t;
-
+
+/*! Enum of possible Outpout Stages */
 typedef enum 
 {
-	floating, 
+	floating, /*!< Set ouput stage to **Floating** */
-	pushPull, 
+	pushPull, /*!< Set ouput stage to **Push Pull** */
-	openDrain 
+	openDrain /*!< Set ouput stage to **Open Drain** */
-}stage;
+}stage_t;
 
+/*! Enum for the internal Pull-Up/Down resistors */
 typedef enum 
 {
-	none,
+	none,		/*!< **Disbales** internal resistance */
-	pullUp,
+	pullUp,		/*!< Set internal resistance as **Pull-Up** */
-	pullDown
+	pullDown	/*!< Set internal resistance as **Pull-Down** */
-}pullUpDown;
+}pullUpDown_t;
 
+/*! Enum to set the pin's speed*/
 typedef enum 
 {
-	slow, 
+	slow,		/*!< set pin's speed to **Slow** */
-	normal, 
+	normal,		/*!< set pin's speed to **Normal** */ 
-	fast, 
+	fast,		/*!< set pin's speed to **Fast** */
-	veryFast
+	veryFast	/*!< set pin's speed to **Very Fast** */
-}speed;
+}speed_t;
 
 typedef enum 
 {
 	disabled,
 	enabled 
-}interrupt;
+}interrupt_t;
 
 typedef struct 
 {
-	mode md; 
+	mode_t md; 
-	stage st;
+	stage_t st;
-	pullUpDown pud;
+	pullUpDown_t pud;
-	speed sp;
+	speed_t sp;
-	interrupt intr; 
+	interrupt_t intr; 
-}configuration;
+}configuration_t;
+
 
 typedef enum 
 {
@@ -127,45 +135,85 @@ typedef enum
 	Bocked, 
 	AlreadyUsed,
 	NotGpio
-}errors;
+}errors_t;
-
+
-// Configuration function that will call all the necessary function for an sucessfull pin initialisation
+/** 
-void pinConfig(pinNo_t pinNo, mode mode, stage stage, pullUpDown resistance, speed speed); 
+ * @brief Configuration function that will call all the necessary function for an sucessfull pin initialisation
-// Modes to set the direction or function of the pin
+ * @param pinNo_t mode_t 
-void pinSetMode(pinNo_t pinNo, mode mode);
+ * @retval none
-// Output Stage Push-Pull High-z ect...
+ */
-void pinSetOutputStage(pinNo_t pinNo, stage stage); 
+void pinConfig(pinNo_t pinNo, mode_t mode, stage_t stage, pullUpDown_t resistance, speed_t speed); 
-// Depending of the hardare it is able to select the speed of given pins
+
-void pinSetSpeed(pinNo_t pinNo, speed speed); 
+/**
-// If internal Pull-up or Pull-donws are wailable
+ * @brief Modes to set the direction or function of the pin
-void pinSetPullUpDonw(pinNo_t pinNo, pullUpDown resistance); 
+ */
-// If pin is set as alternate this function will modify the pins functionality
+void pinSetMode(pinNo_t pinNo, mode_t mode);
-// If pin isn't set as alternate this function will set the pin to alternate mode. 
+
+/**
+ * @brief Output Stage Push-Pull High-z ect...
+ */
+void pinSetOutputStage(pinNo_t pinNo, stage_t stage); 
+
+/**
+* @brief  Depending of the hardare it is able to select the speed of given pins
+*/
+void pinSetSpeed(pinNo_t pinNo, speed_t speed); 
+
+/**
+* @brief  If internal Pull-up or Pull-donws are wailable
+*/
+void pinSetPullUpDonw(pinNo_t pinNo, pullUpDown_t resistance); 
+
+/**
+* @brief  If pin is set as alternate this function will modify the pins functionality
+* If pin isn't set as alternate this function will set the pin to alternate mode. 
+*/
 void pinSetAlternate(pinNo_t pinNo, uint16_t alternate); 
 
-// Reads the pin's current value 
+/**
+* @brief  Reads the pin's current value 
+*/
 uint8_t pinRead(pinNo_t pinNo);
-// Toggles th pin's value
+
+/**
+* @brief  Toggles th pin's value
+*/
 void pinToggle(pinNo_t pinNo);
-// Sets the pin hihg or low.
+
+/**
+* @brief  Sets the pin hihg or low.
+*/
 void pinWrite(pinNo_t pinNo, uint8_t state);
 
-// Initiates all the preriferals needed for the given pin
+/**
+* @brief  Initiates all the preriferals needed for the given pin
+*/
 void pinInit(pinNo_t pinNo);
-// Deactivates all the preriferals needed for the given pin
+
+/**
+* @brief  Deactivates all the preriferals needed for the given pin
+*/
 void pinDeInit(pinNo_t pinNo);
-// Resets pin to default
+
+/**
+* @brief  Resets pin to default
+*/
 void pinReset(pinNo_t pinNo);
 
-// Dependeing on the platform an the form of information printing.
+/**
-// Will pirnt tthe rurrent devices pin status and their configrarion.
+* @brief  Will pirnt tthe rurrent devices pin status and their configrarion.
+* Dependeing on the platform an the form of information printing.
+*/
 void pinHardwareInfo(pinNo_t pinNo);
-// Dependeing on the platfonr an the form of information printing.
+
-// Handles the given error and stops all further execution.
+/**
+* @brief  Handles the given error and stops all further execution.
+* Dependeing on the platfonr an the form of information printing.
+*/
 void pinThrowError(); 	
 
 #ifdef __cplusplus
 }
 #endif
 
-#endif //  _GPIO_H_
+#endif // _GPIO_H_

bsl/csl/stm32f042/Src/pin.c

@@ -52,7 +52,7 @@ const uint32_t outputStgeList[3] =
 	OTYPER_OPEN_DRAIN
 };
 
-void pinSetMode(pinNo_t pinNo, mode mode)
+void pinSetMode(pinNo_t pinNo, mode_t mode)
 {
 	//Clear entry.
 	PIN_BASE->MODER &=~ (0x3 << ((pinNo & 0x0F) * 2));
@@ -60,25 +60,25 @@ void pinSetMode(pinNo_t pinNo, mode mode)
 	PIN_BASE->MODER |= (moderMode[mode] << ((pinNo & 0x0F) * 2));
 }
 
-void pinSetOutputStage(pinNo_t pinNo, stage stage)
+void pinSetOutputStage(pinNo_t pinNo, stage_t stage)
 {
 	PIN_BASE->OSPEEDR &= 1 << (pinNo & 0x0F);	
 	PIN_BASE->OSPEEDR |= (outputStgeList[stage] << (pinNo & 0x0F));
 }
  
-void pinSetPullUpDonw(pinNo_t pinNo, pullUpDown resistance)
+void pinSetPullUpDonw(pinNo_t pinNo, pullUpDown_t resistance)
 {
     PIN_BASE->PUPDR &= ~(0x3 << ((pinNo & 0x0F) * 2));
     PIN_BASE->PUPDR |= (pinPullUpDown[resistance] << ((pinNo & 0x0F) * 2));
 }
  
-void pinSetSpeed(pinNo_t pinNo, speed speed)
+void pinSetSpeed(pinNo_t pinNo, speed_t speed)
 {
 	PIN_BASE->OSPEEDR &= (0x3 << ((pinNo & 0x0F) * 2));	
 	PIN_BASE->OSPEEDR |= (speedList[speed] << ((pinNo & 0x0F) * 2));
 }
  
-void pinConfig(pinNo_t pinNo, mode mode, stage stage, pullUpDown resistance, speed speed)
+void pinConfig(pinNo_t pinNo, mode_t mode, stage_t stage, pullUpDown_t resistance, speed_t speed)
 {
 	pinInit(pinNo); //Very important to init first so that the corresponding bus gets his clock	
 	pinSetMode(pinNo, mode); 	

doxyfile.in.bak

@@ -0,0 +1 @@
+INPUT = @CMAKE_CURRENT_SOURCE_DIR@/bsl/csl/stm32f042/Src/ @CMAKE_CURRENT_SOURCE_DIR@/bsl/csl/interfaces/