[drivers] add commnet for better dev exp

cmake/board/longanpi-3h.cmake

@@ -24,10 +24,10 @@ set(CROSS_COMPILE ${CROSS_COMPILE} CACHE STRING "CROSS_COMPILE Toolchain")
 set(CMAKE_C_COMPILER "${CROSS_COMPILE}gcc")
 set(CMAKE_CXX_COMPILER "${CROSS_COMPILE}g++")
 
-set(CMAKE_COMMON_FLAGS "-nostdlib -Os -mcpu=cortex-a53")
+set(CMAKE_COMMON_FLAGS "-nostdlib -Os -Wall -mcpu=cortex-a53")
 
 # Disable specific warning flags for C and C++ compilers
-set(CMAKE_C_DISABLE_WARN_FLAGS "-Wno-int-to-pointer-cast -Wno-implicit-function-declaration -Wno-discarded-qualifiers")
+set(CMAKE_C_DISABLE_WARN_FLAGS "-Wno-int-to-pointer-cast")
 set(CMAKE_CXX_DISABLE_WARN_FLAGS "-Wno-int-to-pointer-cast")
 
 set(ARCH_BIN_START_ADDRESS "0x00020000")

include/ctype.h

@@ -3,36 +3,133 @@
 #ifndef __CTYPE_H__
 #define __CTYPE_H__
 
+/**
+ * Check if the given character is alphanumeric.
+ *
+ * @param c The character to check.
+ * @return Non-zero value if the character is alphanumeric, zero otherwise.
+ */
 int isalnum(int c);
 
+/**
+ * Check if the given character is alphabetic.
+ *
+ * @param c The character to check.
+ * @return Non-zero value if the character is alphabetic, zero otherwise.
+ */
 int isalpha(int c);
 
+/**
+ * Check if the given character is a valid ASCII character.
+ *
+ * @param c The character to check.
+ * @return Non-zero value if the character is a valid ASCII character, zero otherwise.
+ */
 int isascii(int c);
 
+/**
+ * Check if the given character is a blank space.
+ *
+ * @param c The character to check.
+ * @return Non-zero value if the character is a blank space, zero otherwise.
+ */
 int isblank(int c);
 
+/**
+ * Check if the given character is a control character.
+ *
+ * @param c The character to check.
+ * @return Non-zero value if the character is a control character, zero otherwise.
+ */
 int iscntrl(int c);
 
+/**
+ * Check if the given character is a digit.
+ *
+ * @param c The character to check.
+ * @return Non-zero value if the character is a digit, zero otherwise.
+ */
 int isdigit(int c);
 
+/**
+ * Check if the given character is printable and not a space.
+ *
+ * @param c The character to check.
+ * @return Non-zero value if the character is printable and not a space, zero otherwise.
+ */
 int isgraph(int c);
 
+/**
+ * Check if the given character is a lowercase alphabetic character.
+ *
+ * @param c The character to check.
+ * @return Non-zero value if the character is a lowercase alphabetic character, zero otherwise.
+ */
 int islower(int c);
 
+/**
+ * Check if the given character is a printable character (including spaces).
+ *
+ * @param c The character to check.
+ * @return Non-zero value if the character is a printable character, zero otherwise.
+ */
 int isprint(int c);
 
+/**
+ * Check if the given character is a punctuation character.
+ *
+ * @param c The character to check.
+ * @return Non-zero value if the character is a punctuation character, zero otherwise.
+ */
 int ispunct(int c);
 
+/**
+ * Check if the given character is a whitespace character.
+ *
+ * @param c The character to check.
+ * @return Non-zero value if the character is a whitespace character, zero otherwise.
+ */
 int isspace(int c);
 
+/**
+ * Check if the given character is an uppercase alphabetic character.
+ *
+ * @param c The character to check.
+ * @return Non-zero value if the character is an uppercase alphabetic character, zero otherwise.
+ */
 int isupper(int c);
 
+/**
+ * Check if the given character is a hexadecimal digit.
+ *
+ * @param c The character to check.
+ * @return Non-zero value if the character is a hexadecimal digit, zero otherwise.
+ */
 int isxdigit(int c);
 
+/**
+ * Convert the given character to its ASCII equivalent.
+ *
+ * @param c The character to convert.
+ * @return The ASCII value of the character.
+ */
 int toascii(int c);
 
+/**
+ * Convert the given character to lowercase.
+ *
+ * @param c The character to convert.
+ * @return The lowercase equivalent of the character.
+ */
 int tolower(int c);
 
+/**
+ * Convert the given character to uppercase.
+ *
+ * @param c The character to convert.
+ * @return The uppercase equivalent of the character.
+ */
 int toupper(int c);
 
+
 #endif /* __CTYPE_H__ */

include/drivers/pmu/axp.h

@@ -12,25 +12,32 @@
 
 #include "reg-axp.h"
 
+/**
+ * Structure describing a voltage step of the power domain.
+ */
 typedef struct _axp_step_info {
-    uint32_t step_min_vol;
-    uint32_t step_max_vol;
-    uint32_t step_val;
-    uint32_t regation;
+    uint32_t step_min_vol;  // Minimum voltage level for the step.
+    uint32_t step_max_vol;  // Maximum voltage level for the step.
+    uint32_t step_val;      // Voltage increment value for the step.
+    uint32_t regation;      // Regulator register address.
 } axp_step_info_t;
 
+/**
+ * Structure describing the control information of a power domain.
+ */
 typedef struct _axp_contrl_info {
-    char name[16];
-    uint32_t min_vol;
-    uint32_t max_vol;
-    uint32_t cfg_reg_addr;
-    uint32_t cfg_reg_mask;
-    uint32_t ctrl_reg_addr;
-    uint32_t ctrl_bit_ofs;
-    uint32_t reg_addr_offest;
-    axp_step_info_t axp_step_tbl[4];
+    char name[16];              // Name of the power domain.
+    uint32_t min_vol;           // Minimum voltage level for the domain.
+    uint32_t max_vol;           // Maximum voltage level for the domain.
+    uint32_t cfg_reg_addr;      // Configuration register address.
+    uint32_t cfg_reg_mask;      // Configuration register mask.
+    uint32_t ctrl_reg_addr;     // Control register address.
+    uint32_t ctrl_bit_ofs;      // Bit offset in the control register.
+    uint32_t reg_addr_offset;   // Offset of the register address.
+    axp_step_info_t axp_step_tbl[4]; // Voltage step table for the domain.
 } axp_contrl_info;
 
+
 /* AXP1530 */
 
 /**

include/drivers/sys-dma.h

@@ -95,24 +95,84 @@ typedef struct {
 #define DMA_RST_OFS 16
 #define DMA_GATING_OFS 0
 
+/**
+ * Initialize the DMA subsystem.
+ */
 void dma_init(void);
 
+/**
+ * Clean up and exit the DMA subsystem.
+ */
 void dma_exit(void);
 
+/**
+ * Request a DMA channel of the specified type.
+ *
+ * @param dmatype The type of DMA channel to request.
+ * @return The DMA channel number if successful, or an error code if failed.
+ */
 uint32_t dma_request(uint32_t dmatype);
 
+/**
+ * Request a DMA channel from the last allocated channel of the specified type.
+ *
+ * @param dmatype The type of DMA channel to request.
+ * @return The DMA channel number if successful, or an error code if failed.
+ */
 uint32_t dma_request_from_last(uint32_t dmatype);
 
+/**
+ * Release a previously requested DMA channel.
+ *
+ * @param hdma The DMA channel number to release.
+ * @return 0 if successful, or an error code if failed.
+ */
 int dma_release(uint32_t hdma);
 
+/**
+ * Configure the settings of a DMA channel.
+ *
+ * @param hdma The DMA channel number to configure.
+ * @param cfg Pointer to the DMA configuration structure.
+ * @return 0 if successful, or an error code if failed.
+ */
 int dma_setting(uint32_t hdma, dma_set_t *cfg);
 
+/**
+ * Start a DMA transfer.
+ *
+ * @param hdma The DMA channel number to start the transfer on.
+ * @param saddr Source address of the data to transfer.
+ * @param daddr Destination address to transfer the data to.
+ * @param bytes Number of bytes to transfer.
+ * @return 0 if successful, or an error code if failed.
+ */
 int dma_start(uint32_t hdma, uint32_t saddr, uint32_t daddr, uint32_t bytes);
 
+/**
+ * Stop a currently running DMA transfer.
+ *
+ * @param hdma The DMA channel number to stop the transfer on.
+ * @return 0 if successful, or an error code if failed.
+ */
 int dma_stop(uint32_t hdma);
 
+/**
+ * Query the status of a DMA transfer.
+ *
+ * @param hdma The DMA channel number to query status for.
+ * @return The status of the DMA transfer.
+ */
 int dma_querystatus(uint32_t hdma);
 
+/**
+ * Perform a test DMA transfer between the specified source and destination addresses.
+ *
+ * @param src_addr Pointer to the source address.
+ * @param dst_addr Pointer to the destination address.
+ * @return 0 if successful, or an error code if failed.
+ */
 int dma_test(uint32_t *src_addr, uint32_t *dst_addr);
 
+
 #endif /* _SUNXI_DMA_H */

include/drivers/sys-gpio.h

@@ -60,12 +60,37 @@ typedef struct {
     uint8_t mux;
 } gpio_mux_t;
 
-extern void sunxi_gpio_init(gpio_t pin, int cfg);
+/**
+ * Initialize the specified GPIO pin with the given configuration.
+ *
+ * @param pin The GPIO pin to initialize.
+ * @param cfg The configuration value for the GPIO pin.
+ */
+void sunxi_gpio_init(gpio_t pin, int cfg);
 
-extern void sunxi_gpio_set_value(gpio_t pin, int value);
+/**
+ * Set the value of the specified GPIO pin.
+ *
+ * @param pin The GPIO pin to set the value for.
+ * @param value The value to be set (0 or 1) for the GPIO pin.
+ */
+void sunxi_gpio_set_value(gpio_t pin, int value);
 
-extern int sunxi_gpio_read(gpio_t pin);
+/**
+ * Read the value of the specified GPIO pin.
+ *
+ * @param pin The GPIO pin to read the value from.
+ * @return The value (0 or 1) read from the GPIO pin.
+ */
+int sunxi_gpio_read(gpio_t pin);
 
-extern void sunxi_gpio_set_pull(gpio_t pin, enum gpio_pull_t pull);
+/**
+ * Set the pull configuration for the specified GPIO pin.
+ *
+ * @param pin The GPIO pin to set the pull configuration for.
+ * @param pull The pull configuration to be set for the GPIO pin.
+ */
+void sunxi_gpio_set_pull(gpio_t pin, enum gpio_pull_t pull);
 
-#endif // __SYS_GPIO_H__
+
+#endif// __SYS_GPIO_H__

include/drivers/sys-rtc.h

@@ -16,28 +16,61 @@
 #define RTC_FEL_INDEX 2
 #define RTC_BOOT_INDEX 6
 
-/* Write data to the RTC register at the specified index */
+/**
+ * Write data to the RTC register at the specified index.
+ *
+ * @param index The index of the RTC register to write data to.
+ * @param val The value to write to the RTC register.
+ */
 void rtc_write_data(int index, uint32_t val);
 
-/* Read data from the RTC register at the specified index */
+/**
+ * Read data from the RTC register at the specified index.
+ *
+ * @param index The index of the RTC register to read data from.
+ * @return The value read from the RTC register.
+ */
 uint32_t rtc_read_data(int index);
 
-/* Set the FEL flag in the RTC register */
+/**
+ * Set the FEL (Fastboot External Loader) flag in the RTC register.
+ * This flag indicates that the system should enter Fastboot mode.
+ */
 void rtc_set_fel_flag(void);
 
-/* Set the start time in milliseconds in the RTC register */
+/**
+ * Set the start time in milliseconds in the RTC register.
+ * This function sets the start time for a specific operation.
+ */
 void rtc_set_start_time_ms(void);
 
-/* Probe the FEL flag in the RTC register */
+/**
+ * Probe the FEL (Fastboot External Loader) flag in the RTC register.
+ *
+ * @return The value of the FEL flag (0 or 1).
+ */
 uint32_t rtc_probe_fel_flag(void);
 
-/* Clear the FEL flag in the RTC register */
+/**
+ * Clear the FEL (Fastboot External Loader) flag in the RTC register.
+ * This function clears the FEL flag after it has been processed.
+ */
 void rtc_clear_fel_flag(void);
 
-/* Set the bootmode flag in the RTC register */
+/**
+ * Set the bootmode flag in the RTC register.
+ *
+ * @param flag The bootmode flag value to set.
+ * @return 0 if successful, or an error code if failed.
+ */
 int rtc_set_bootmode_flag(uint8_t flag);
 
-/* Get the bootmode flag from the RTC register */
+/**
+ * Get the bootmode flag from the RTC register.
+ *
+ * @return The value of the bootmode flag.
+ */
 int rtc_get_bootmode_flag(void);
 
+
 #endif// __SYS_RTC_H__