11 files changed, 185 insertions(+), 17 deletions(-)

M README.md
M firmware/include/clocks.h
M firmware/include/delay.h
M firmware/include/display.h
M firmware/include/exti.h
M firmware/include/fmc.h
M firmware/include/generic.h
M firmware/include/otm8009a.h
M firmware/include/usb.h
M firmware/include/usb_device_cdc.h
M firmware/src/usb_device_cdc.c

@@ 30,6 30,9 @@ would be simulated. But afterall there was no need for this, and only one test w
 a test for seeing contents of device descriptor. The test utilizes that functions for sending data are used,
 and they are replaced by code that just prints to a file instead of changing chip memory.
 
+Most of the code is documented using Doxygen comments, unless
+the function's behavior seems obvious.
+
 ## USB device
 
 The usb device support is split across multiple files. `usb.h` contains

@@ 30,18 30,72 @@ typedef enum {
   CLOCK_HSI48,
 } clock_t;
 
+/**
+ * @brief Make sure the given clock is enabled
+ * @param[in] clock The clock type to enable
+ */
 void clocks_enable(clock_t clock);
+
+/**
+ * @brief Check if clock is ready (running)
+ * @param[in] clock The clock to check
+ * @return True if the clock is ready.
+ */
 bool clocks_ready(clock_t clock);
+
+/**
+ * @brief Wait until the clock is ready.
+ * @details Useful after enabling the clock.
+ * @param[in] clock The clock to wait for.
+ */
 void clocks_wait_ready(clock_t clock);
 
+/**
+ * @brief Configures parameters of a pll.
+ * @details Fractional scaling is currently not supported. The clock frequency will be input_freq / divm * divn / divX, where X is p, q, r for each output respectively.
+ * @param[in] pll The pll number.
+ * @param[in] vcosel What vco to select. See reference manual for details.
+ * @param[in] divm Divide initial clock frequency by this
+ * @param[in] source Where the source clock to pll is coming from.
+ * @param[in] divn Multiply the frequency of in / divm by this number
+ * @param[in] divp Divisor on the output P. If zero, the output is disabled.
+ * @param[in] divq Divisor on the output Q. If zero, the output is disabled.
+ * @param[in] divr Divisor on the output R. If zero, the output is disabled.
+ */
 void clocks_pll_configure(clock_pll_t pll, uint8_t vcosel,
                           uint8_t divm, pll_source_t source,
                           uint16_t divn, uint8_t divp, uint8_t divq,
                           uint8_t divr);
+
+/**
+ * @brief Enable the given pll, after configuring.
+ * @param[in] pll The pll to enable.
+ */
 void clocks_pll_enable(clock_pll_t pll);
+
+/**
+ * @brief Disable the given pll.
+ * @details This should be done only if the pll is not being used at the moment.
+ * @param[in] pll Description
+ */
 void clocks_pll_disable(clock_pll_t pll);
+
+/**
+ * @brief Wait until the pll is ready.
+ * @param[in] pll The pll to wait for.
+ * @param[in] timeout_us Timeout, with maximum wait for the pll.
+ */
 void clocks_pll_wait_ready(clock_pll_t pll, uint16_t timeout_us);
 
+/**
+ * @brief Change system clock to the specified clock.
+ * @details The flash read time might have to be adjusted. Also don't forget about rising the voltage if frequency is too high.
+ * @param[in] source Where to obtain system clock from.
+ * @param[in] d1cpre Divisor for 1cpre
+ * @param[in] d1ppre Divisor for 1ppre
+ * @param[in] hpre Description Divisor for hpre
+ * @param[in] timeout_us Description The maximum wait time.
+ */
 void clocks_system_clock_source(sysclock_source_t source, uint8_t d1cpre,
                                 uint8_t d1ppre, uint8_t hpre,
                                 uint16_t timeout_us);

@@ 15,6 15,10 @@
 
 #define HCLK_FREQ_HZ    ((uint32_t)SYSTEM_CLOCK / AHB_DIVIDER / HCLK_DIVIDER)
 
+/**
+ * @brief Wait for given amount of micro seconds.
+ * @param[in] us The time in micro seconds to wait for
+ */
 inline void __attribute__((always_inline)) delay_us(uint32_t us) {
   uint64_t max_load = 0xFFFFFF;
   uint64_t total_load = us * (SYSTICK_HZ / 1000000);


@@ 37,6 41,10 @@ inline void __attribute__((always_inline)) delay_us(uint32_t us) {
 }
 
 
+/**
+ * @brief Wait for given amount of milli seconds.
+ * @param[in] us The time in milli seconds to wait for
+ */
 inline void __attribute__((always_inline)) delay_ms(uint32_t ms) {
   for (uint32_t i = 0; i < ms; i++) {
     delay_us(1000);

@@ 108,27 108,72 @@ typedef struct {
   display_config_t config;
 } display_t;
 
+/**
+ * @brief Initialize the display struct.
+ * @param[in,out] display The display struct
+ * @param[out] dsi The dsi peripheral
+ * @param[out] ltdc The ltdc peripheral
+ * @param[out] layer The layer to draw to.
+ * @param[in] display_config The config parameters
+ */
 void display_init(display_t *display, DSI_TypeDef *dsi, LTDC_TypeDef* ltdc, LTDC_Layer_TypeDef* layer, display_config_t display_config);
+
+/**
+ * @brief Start the dsi peripheral
+ * @param[in,out] display The display.
+ */
 void display_start(display_t* display);
 
+/**
+ * @brief Set up the display with parameters.
+ * @param[in,out] display The display
+ * @param[in] dsi_khz Frequency of dsi physical clock.
+ * @param[in] ltdc_khz Frequency of ltdc clock.
+ * @param[in] mode The mode to use.
+ * @param[in] pll The pll configuration.
+ * @param[in] phy The phy configuration.
+ * @param[in] flow The flow configuratioon
+ * @param[in] dsi_config The dsi configuration.
+ */
 void display_setup(display_t *display, uint32_t dsi_khz, uint32_t ltdc_khz,
                    dsi_mode_t mode,
                    dsi_pll_config_t pll, dsi_phy_config_t phy,
                    dsi_flow_config_t flow, dsi_config_t dsi_config);
 
-void display_command_mode(display_t* display);
-void display_video_mode(display_t* display);
-
 void display_dsi_short_write(display_t* display, uint8_t lsb, uint8_t msb, uint8_t discriminant);
 void display_dsi_long_write(display_t* display, uint8_t cmd, uint8_t* data, uint16_t len, uint8_t discriminant);
 void display_dsi_read(display_t* display, uint8_t* buffer);
 
+/**
+ * @brief For setting the dsi transmission to low power.
+ * @param[in,out] display The display
+ * @param[in] low_power The power of low
+ */
 void display_set_command_mode_transmission_kind(display_t* display, bool low_power);
 
 // Layer calls
+
+/**
+ * @brief Set up layer configuration.
+ * @param[in,out] display The display.
+ * @param[out] buffer Pointer to buffer to draw
+ * @param[in] pixel_format The format of pixel
+ */
 void display_layer_setup(display_t *display, void* buffer, ltdc_layer_pixel_format_t pixel_format);
+
+/**
+ * @brief Replace framebuffer of dsi.
+ * @param[in,out] display The display.
+ * @param[out] buffer Pointer to buffer to set to.
+ */
 void display_set_framebuffer(display_t* display, void* buffer);
+
+/**
+ * @brief Refresh the display - send the framebuffer to the display.
+ * @param[in,out] display Description
+ */
 void display_refresh(display_t* display);
+
 void display_reload(display_t *display);
 
 #endif // DISPLAY_H

@@ 22,6 22,7 @@ void exti_init(exti_t* exti, uint8_t line, EXTI_TypeDef* exti_periph, SYSCFG_Typ
 void exti_external_interrupt(exti_t* exti, uint8_t gpio);
 
 // Only 21 positions are now supported. This is too hard for other ones.
+
 void exti_rising_interrupt(exti_t* exti);
 void exti_falling_interrupt(exti_t* exti);
 void exti_disable_interrupt(exti_t* exti);

@@ 64,7 64,23 @@ void fmc_sdram_configure(fmc_t *fmc, sdram_bank_t target_bank,
                          fmc_sdram_configuration_t config,
                          fmc_sdram_timing_t timing,
                          uint16_t mode_register);
+
+/**
+ * @brief Send command to the sdram.
+ * @param[in,out] fmc The fmc peripheral.
+ * @param[in] bank The bank the sdram is connected to.
+ * @param[in] cmd The command to send.
+ * @param[in] argument Argument of the command, if appropriate.
+ */
 void fmc_sdram_send_command(fmc_t* fmc, uint16_t bank, fmc_sdram_cmd_type_t cmd, uint16_t argument);
+
+/**
+ * @brief Allocate space in the sdram memory. This memory cannot be freed.
+ * @param[in,out] fmc The fmc with sdram.
+ * @param[in] bank The bank to use.
+ * @param[in] size The size to allocate.
+ * @return Pointer to the newly allocated space.
+ */
 void* fmc_sdram_allocate(fmc_t* fmc, sdram_bank_t bank, uint32_t size);
 
 #endif // FMC_H

@@ 1,10 1,14 @@
 #ifndef GENERIC_H
 #define GENERIC_H
 
+/**
+ * @enum task_result_t
+ * Result of a non-blocking task.
+ */
 typedef enum {
-  RES_OK,
-  RES_ERROR,
-  RES_WOULD_BLOCK
+  RES_OK,         /**< The task succeeded */
+  RES_ERROR,      /**< The task failed. */
+  RES_WOULD_BLOCK /**< The task would block, so it was aborted. */
 } task_result_t;
 
 #endif // GENERIC_H

@@ 82,6 82,15 @@ typedef enum {
   OTM8009A_MODE_LANDSCAPE,
 } otm8009a_mode_t;
 
+/**
+ * @brief Send
+ * @param[in,out] display The display
+ * @param[in] mode The mode to use
+ * @param[in] frame_rate The rate of frame
+ * @param[in] colormap The colormap to use
+ * @param[in] width The width of the display
+ * @param[in] height The height of the display
+ */
 void otm8009_init(display_t *display, otm8009a_mode_t mode,
                   otm8009a_frame_rates_t frame_rate,
                   otm8009a_colormap_t colormap,

@@ 420,12 420,6 @@ task_result_t usb_send_unicode_string_descriptor(
     uint16_t max_size,
     volatile uint32_t *fifo_tx_target);
 
-task_result_t usb_send_unicode_string_descriptor(
-    USB_OTG_INEndpointTypeDef *endpoint,
-    usb_unicode_string_descriptor_t *string_descriptor,
-    uint16_t max_size,
-    volatile uint32_t *fifo_tx_target);
-
 void usb_flush_tx_fifo(USB_OTG_GlobalTypeDef* core, uint16_t fifo_num);
 void usb_flush_rx_fifo(USB_OTG_GlobalTypeDef* core);
 

@@ 142,17 142,51 @@ typedef struct {
  */
 void cdc_acm_configure(usb_device_t *device, uint16_t rx_queue_size);
 
+/**
+ * @brief Sets a callback that will be called when data are received, with the data.
+ * @details The callback bypasses the need for a queue. Instead of putting the data to queue, the callback is first called with the data. The callback will return number of bytes it could read. The rest will be put to the queue.
+ * @param[in,out] device The device.
+ * @param[in] callback The new callback.
+ */
 void cdc_data_set_receive_callback(usb_device_t *device,
                                    cdc_receive_callback_t callback);
 
+/**
+ * @brief Sets a callback that will be called when data are received, to allow forwarding the data to custom buffer.
+ * @details The callback bypasses the need for queue or putting the data to temporary buffer by putting the data where application wants them right away.
+ * @param[in,out] device The device.
+ * @param[in] callback The new callback.
+ */
 void cdc_data_set_receive_location_callback(usb_device_t *device,
                                             cdc_receive_location_callback_t callback);
 
+/**
+ * @brief Sends data, waiting for all of them to be sent.
+ * @param[in,out] device The usb device, using cdc class.
+ * @param[out] data The data to send to the host.
+ * @param[in] size The size of the data.
+ * @return The number of bytes sent. -1 on error.
+ */
 int32_t cdc_data_send_blocking(usb_device_t *device, uint8_t *data, uint16_t size);
+
+/**
+ * @brief Sends data, not waiting for them to be sent.
+ * @param[in,out] device The usb device, using cdc class.
+ * @param[out] data The data to send to the host.
+ * @param[in] size The size of the data.
+ * @return The number of bytes sent. -1 on error.
+ */
 int32_t cdc_data_send(usb_device_t* device, uint8_t* data, uint16_t size);
 
+/**
+ * @brief Reads data from the receive queue.
+ * @param[in,out] device The device
+ * @param[out] buffer Pointer to buffer to save data to.
+ * @param[in] max_size The size of the buffer
+ * @return Description
+ */
 uint16_t cdc_data_receive(usb_device_t* device, uint8_t* buffer, uint16_t max_size);
 
-bool cdc_got_params(usb_device_t* device);
+/* bool cdc_got_params(usb_device_t* device); */
 
 #endif // USB_DEVICE_CDC_H

@@ 705,7 705,7 @@ uint16_t cdc_data_receive(usb_device_t *device, uint8_t* buffer,
   return size;
 }
 
-bool cdc_got_params(usb_device_t *device) {
-  usb_device_cdc_t* cdc = (usb_device_cdc_t*)device->class;
-  return cdc->got_setup != 0;
-}
+/* bool cdc_got_params(usb_device_t *device) { */
+/*   usb_device_cdc_t* cdc = (usb_device_cdc_t*)device->class; */
+/*   return cdc->got_setup != 0; */
+/* } */