combine canfd_init_freq(), canfd_init_freq_direct(), and canfd_frequency() with the existing functions

minor fixes on documentation

Author: wdx04

drivers/source/CAN.cpp

@@ -34,7 +34,7 @@ CAN::CAN(PinName rd, PinName td, int hz, int data_hz) : _can(), _irq()
 {
     // No lock needed in constructor
 #if DEVICE_CAN_FD
-    canfd_init_freq(&_can, rd, td, hz, data_hz);
+    can_init_freq(&_can, rd, td, hz, data_hz);
 #else
     MBED_ASSERT(data_hz == 0);
     can_init_freq(&_can, rd, td, hz);
@@ -53,7 +53,7 @@ CAN::CAN(const can_pinmap_t &pinmap, int hz, int data_hz) : _can(), _irq()
 {
     // No lock needed in constructor
 #if DEVICE_CAN_FD
-    canfd_init_freq_direct(&_can, &pinmap, hz, data_hz);
+    can_init_freq_direct(&_can, &pinmap, hz, data_hz);
 #else
     MBED_ASSERT(data_hz == 0);
     can_init_freq_direct(&_can, &pinmap, hz);
@@ -77,7 +77,7 @@ int CAN::frequency(int f, int data_f)
 {
     lock();
 #if DEVICE_CAN_FD
-    int ret = canfd_frequency(&_can, f, data_f);
+    int ret = can_frequency(&_can, f, data_f);
 #else
     MBED_ASSERT(data_f == 0);
     int ret = can_frequency(&_can, f);

hal/include/hal/can_api.h

@@ -74,70 +74,85 @@ typedef struct can_s can_t;
  * @param rd The CAN RD pin name
  * @param td The CAN TD pin name
  */
-void          can_init(can_t *obj, PinName rd, PinName td);
+void can_init(can_t *obj, PinName rd, PinName td);
 
 /** Initialize the CAN peripheral. It sets the default parameters for CAN
  *  peripheral, and configures its specifieds pins.
  *
  * @param obj The CAN object
  * @param pinmap pointer to structure which holds static pinmap
  */
-void          can_init_direct(can_t *obj, const can_pinmap_t *pinmap);
+void can_init_direct(can_t *obj, const can_pinmap_t *pinmap);
 
 /** Initialize the CAN peripheral. It sets the default parameters for CAN
  *  peripheral, and configures its specifieds pins.
  *
  * @param obj CAN object
  * @param rd The CAN RD pin name
  * @param td The CAN TD pin name
- * @param hz The bus frequency
+ * @param hz The bus frequency in classical CAN mode, or nominal phase frequency in CAN FD mode
+ * @param data_hz The data phase frequency in CAN FD mode, the CAN object is put into Classical CAN mode if this parameter is zero
  */
-void          can_init_freq(can_t *obj, PinName rd, PinName td, int hz);
+void can_init_freq(can_t *obj, PinName rd, PinName td, int hz
+#ifdef DEVICE_CAN_FD
+    , int data_hz
+#endif
+    );
 
 /** Initialize the CAN peripheral. It sets the default parameters for CAN
  *  peripheral, and configures its specifieds pins.
  *
  * @param obj CAN object
  * @param pinmap pointer to structure which holds static pinmap
- * @param hz The bus frequency
+ * @param hz The bus frequency in classical CAN mode, or nominal phase frequency in CAN FD mode
+ * @param data_hz The data phase frequency in CAN FD mode, the CAN object is put into Classical CAN mode if this parameter is zero
  */
-void          can_init_freq_direct(can_t *obj, const can_pinmap_t *pinmap, int hz);
+void can_init_freq_direct(can_t *obj, const can_pinmap_t *pinmap, int hz
+#ifdef DEVICE_CAN_FD
+    , int data_hz
+#endif
+    );
 
 /** Release the CAN peripheral, not currently invoked. It requires further
  *  resource management.
  *
  * @param obj The CAN object
  */
-void          can_free(can_t *obj);
+void can_free(can_t *obj);
 
 /** Configure the CAN bus frequency
  *
  * @param obj The CAN object
- * @param hz The bus frequency
+ * @param hz The bus frequency in classical CAN mode, or nominal phase frequency in CAN FD mode
+ * @param data_hz The data phase frequency in CAN FD mode, the CAN object is put into Classical CAN mode if this parameter is zero
  */
-int           can_frequency(can_t *obj, int hz);
+int can_frequency(can_t *obj, int hz
+#ifdef DEVICE_CAN_FD
+    , int data_hz
+#endif
+    );
 
 /** Initialize the CAN IRQ handler
  *
  * @param obj     The CAN object
  * @param handler The handler to be attached to CAN IRQ
  * @param context The context to be passed back to the handler (context != 0, 0 is reserved)
  */
-void          can_irq_init(can_t *obj, can_irq_handler handler, uintptr_t context);
+void can_irq_init(can_t *obj, can_irq_handler handler, uintptr_t context);
 
-/** Release the CAN object
+/** Remove the CAN IRQ handler
  *
  * @param obj The CAN object
  */
-void          can_irq_free(can_t *obj);
+void can_irq_free(can_t *obj);
 
 /** Enable/disable the CAN IRQ event
  *
  * @param obj    The CAN object
  * @param irq    The CAN IRQ event
  * @param enable The enable flag
  */
-void          can_irq_set(can_t *obj, CanIrqType irq, uint32_t enable);
+void can_irq_set(can_t *obj, CanIrqType irq, uint32_t enable);
 
 /** Write a CAN message to the bus.
  *
@@ -147,7 +162,7 @@ void          can_irq_set(can_t *obj, CanIrqType irq, uint32_t enable);
  * @return 0 if write failed,
  *    1 if write was successful
  */
-int           can_write(can_t *obj, CAN_Message msg);
+int can_write(can_t *obj, CAN_Message msg);
 
 /** Read a CAN message from the bus.
  *
@@ -158,7 +173,7 @@ int           can_write(can_t *obj, CAN_Message msg);
  * @return 0 if no message arrived,
  *         1 if message arrived
  */
-int           can_read(can_t *obj, CAN_Message *msg, int handle);
+int can_read(can_t *obj, CAN_Message *msg, int handle);
 
 /** Change CAN operation to the specified mode.
  *
@@ -168,7 +183,7 @@ int           can_read(can_t *obj, CAN_Message *msg, int handle);
  * @return 0 if mode change failed or unsupported,
  *   1 if mode change was successful
  */
-int           can_mode(can_t *obj, CanMode mode);
+int can_mode(can_t *obj, CanMode mode);
 
 /** Filter out incomming messages.
  *
@@ -181,15 +196,15 @@ int           can_mode(can_t *obj, CanMode mode);
  * @return 0 if filter change failed or unsupported,
  *    new filter handle if successful
  */
-int           can_filter(can_t *obj, uint32_t id, uint32_t mask, CANFormat format, int32_t handle);
+int can_filter(can_t *obj, uint32_t id, uint32_t mask, CANFormat format, int32_t handle);
 
 /** Reset CAN interface.
  *
  * @param obj    CAN object
  *
  * To use after error overflow.
  */
-void          can_reset(can_t *obj);
+void can_reset(can_t *obj);
 
 /**  Detects read errors - Used to detect read overflow errors.
  *
@@ -210,38 +225,9 @@ unsigned char can_tderror(can_t *obj);
  * @param obj CAN object
  * @param silent boolean indicating whether to go into silent mode or not.
  */
-void          can_monitor(can_t *obj, int silent);
+void can_monitor(can_t *obj, int silent);
 
 #if DEVICE_CAN_FD
-/** Initialize the CAN FD peripheral. It sets the default parameters for CAN FD
- *  peripheral, and configures its specifieds pins.
- *
- * @param obj CAN object
- * @param rd The CAN RD pin name
- * @param td The CAN TD pin name
- * @param hz The bus frequency of nominal phase
- * @param data_hz The bus frequency of data phase, the CAN object is put into Classical CAN mode if this parameter is zero
- */
-void          canfd_init_freq(can_t *obj, PinName rd, PinName td, int hz, int data_hz);
-
-/** Initialize the CAN FD peripheral. It sets the default parameters for CAN FD
- *  peripheral, and configures its specifieds pins.
- *
- * @param obj CAN object
- * @param pinmap pointer to structure which holds static pinmap
- * @param hz The bus frequency of nominal phase
- * @param data_hz The bus frequency of data phase, the CAN object is put into Classical CAN mode if this parameter is zero
- */
-void          canfd_init_freq_direct(can_t *obj, const can_pinmap_t *pinmap, int hz, int data_hz);
-
-/** Configure the CAN FD bus frequency
- *
- * @param obj The CAN object
- * @param hz The bus frequency of nominal phase
- * @param data_hz The bus frequency of data phase, the CAN object is put into Classical CAN mode if this parameter is zero
- */
-int           canfd_frequency(can_t *obj, int hz, int data_hz);
-
 /** Write a CAN FD Message to the bus.
  *
  * @param obj    The CAN object
@@ -250,7 +236,7 @@ int           canfd_frequency(can_t *obj, int hz, int data_hz);
  * @return 0 if write failed,
  *    1 if write was successful
  */
-int           canfd_write(can_t *obj, CANFD_Message msg);
+int canfd_write(can_t *obj, CANFD_Message msg);
 
 /** Read a Classical CAN or CAN FD Message from the bus.
  *
@@ -261,7 +247,7 @@ int           canfd_write(can_t *obj, CANFD_Message msg);
  * @return 0 if no message arrived,
  *         1 if message arrived
  */
-int           canfd_read(can_t *obj, CANFD_Message *msg, int handle);
+int canfd_read(can_t *obj, CANFD_Message *msg, int handle);
 #endif
 
 /** Get the pins that support CAN RD

hal/include/hal/can_helper.h

@@ -59,11 +59,11 @@ typedef enum CANType CANType;
  *
 **/
 struct CAN_Message {
-    unsigned int   id;                 // 29 bit identifier
-    unsigned char  data[8];            // Data field
-    unsigned char  len;                // Length of data field in bytes
-    CANFormat      format;             // Format ::CANFormat
-    CANType        type;               // Type ::CANType
+    unsigned int   id;                 ///< 29 bit identifier
+    unsigned char  data[8];            ///< Data field
+    unsigned char  len;                ///< Length of data field in bytes
+    CANFormat      format;             ///< Format ::CANFormat
+    CANType        type;               ///< Type ::CANType
 };
 typedef struct CAN_Message CAN_Message;
 
@@ -77,11 +77,11 @@ typedef struct CAN_Message CAN_Message;
  *
 **/
 struct CANFD_Message {
-    unsigned int   id;                 // 29 bit identifier
-    unsigned char  data[64];            // Data field
-    unsigned char  len;                // Length of data field in bytes
-    CANFormat      format;             // Format ::CANFormat
-    CANType        type;               // Type ::CANType
+    unsigned int   id;                 ///< 29 bit identifier
+    unsigned char  data[64];           ///< Data field
+    unsigned char  len;                ///< Length of data field in bytes
+    CANFormat      format;             ///< Format ::CANFormat
+    CANType        type;               ///< Type ::CANType
 };
 typedef struct CANFD_Message CANFD_Message;
 

hal/source/static_pinmap.cpp

@@ -74,6 +74,17 @@ MBED_WEAK void serial_set_flow_control_direct(serial_t *obj, FlowControl type, c
 #endif
 
 #if DEVICE_CAN
+#if DEVICE_CAN_FD
+MBED_WEAK void can_init_freq_direct(can_t *obj, const can_pinmap_t *pinmap, int hz, int data_hz)
+{
+    can_init_freq(obj, pinmap->rd_pin, pinmap->td_pin, hz, data_hz);
+}
+
+MBED_WEAK void can_init_direct(can_t *obj, const can_pinmap_t *pinmap)
+{
+    can_init(obj, pinmap->rd_pin, pinmap->td_pin);
+}
+#else
 MBED_WEAK void can_init_freq_direct(can_t *obj, const can_pinmap_t *pinmap, int hz)
 {
     can_init_freq(obj, pinmap->rd_pin, pinmap->td_pin, hz);
@@ -83,7 +94,7 @@ MBED_WEAK void can_init_direct(can_t *obj, const can_pinmap_t *pinmap)
 {
     can_init(obj, pinmap->rd_pin, pinmap->td_pin);
 }
-
+#endif
 #endif
 
 #if DEVICE_QSPI

targets/TARGET_STM/can_api.c

@@ -115,11 +115,11 @@ static uint32_t get_canfd_data_prescaler(uint32_t input_f, int data_f, uint32_t
 }
 
 #if STATIC_PINMAP_READY
-#define CANFD_INIT_FREQ_DIRECT canfd_init_freq_direct
-void canfd_init_freq_direct(can_t *obj, const can_pinmap_t *pinmap, int hz)
+#define CAN_INIT_FREQ_DIRECT can_init_freq_direct
+void can_init_freq_direct(can_t *obj, const can_pinmap_t *pinmap, int hz, int data_hz)
 #else
-#define CANFD_INIT_FREQ_DIRECT _canfd_init_freq_direct
-static void _canfd_init_freq_direct(can_t *obj, const can_pinmap_t *pinmap, int hz, int data_hz)
+#define CAN_INIT_FREQ_DIRECT _can_init_freq_direct
+static void _can_init_freq_direct(can_t *obj, const can_pinmap_t *pinmap, int hz, int data_hz)
 #endif
 {
     MBED_ASSERT((int)pinmap->peripheral != NC);
@@ -301,24 +301,13 @@ static void _canfd_init_freq_direct(can_t *obj, const can_pinmap_t *pinmap, int
     can_internal_init(obj);
 }
 
-#if STATIC_PINMAP_READY
-#define CAN_INIT_FREQ_DIRECT can_init_freq_direct
-void can_init_freq_direct(can_t *obj, const can_pinmap_t *pinmap, int hz)
-#else
-#define CAN_INIT_FREQ_DIRECT _can_init_freq_direct
-static void _can_init_freq_direct(can_t *obj, const can_pinmap_t *pinmap, int hz)
-#endif
-{
-    CANFD_INIT_FREQ_DIRECT(obj, pinmap, hz, 0);
-}
-
 void can_init_direct(can_t *obj, const can_pinmap_t *pinmap)
 {
     /* default frequency is 100 kHz */
-    CAN_INIT_FREQ_DIRECT(obj, pinmap, 100000);
+    can_init_freq_direct(obj, pinmap, 100000, 0);
 }
 
-void canfd_init_freq(can_t *obj, PinName rd, PinName td, int hz, int data_hz)
+void can_init_freq(can_t *obj, PinName rd, PinName td, int hz, int data_hz)
 {
     CANName can_rd = (CANName)pinmap_peripheral(rd, PinMap_CAN_RD);
     CANName can_td = (CANName)pinmap_peripheral(td, PinMap_CAN_TD);
@@ -329,17 +318,12 @@ void canfd_init_freq(can_t *obj, PinName rd, PinName td, int hz, int data_hz)
 
     const can_pinmap_t static_pinmap = {peripheral, rd, function_rd, td, function_td};
 
-    CANFD_INIT_FREQ_DIRECT(obj, &static_pinmap, hz, data_hz);
-}
-
-void can_init_freq(can_t *obj, PinName rd, PinName td, int hz)
-{
-    canfd_init_freq(obj, rd, td, hz, 0);
+    CAN_INIT_FREQ_DIRECT(obj, &static_pinmap, hz, data_hz);
 }
 
 void can_init(can_t *obj, PinName rd, PinName td)
 {
-    can_init_freq(obj, rd, td, 100000);
+    can_init_freq(obj, rd, td, 100000, 0);
 }
 
 void can_irq_init(can_t *obj, can_irq_handler handler, uintptr_t context)
@@ -427,7 +411,7 @@ void can_reset(can_t *obj)
     HAL_FDCAN_ResetTimestampCounter(&obj->CanHandle);
 }
 
-int canfd_frequency(can_t *obj, int f, int data_f)
+int can_frequency(can_t *obj, int f, int data_f)
 {
     if (HAL_FDCAN_Stop(&obj->CanHandle) != HAL_OK) {
         error("HAL_FDCAN_Stop error\n");
@@ -488,11 +472,6 @@ int canfd_frequency(can_t *obj, int f, int data_f)
     return can_internal_init(obj);
 }
 
-int can_frequency(can_t *obj, int f)
-{
-    return canfd_frequency(obj, f, 0);
-}
-
 /** Filter out incoming messages
  *
  *  @param obj CAN object

targets/targets.json5

@@ -4923,7 +4923,7 @@ mode is recommended for target MCUs with small amounts of flash and RAM.",
                 "macro_name": "CLOCK_SOURCE"
             },
             "hse_value": {
-                "help": "HSE default value is 16MHz in stm32u5xx_hal_conf.h, The valid value range is between 4MHz and 50MHz",
+                "help": "HSE default value is 16MHz in stm32u5xx_hal_conf.h, The effective value is within the range of 4MHz to 50MHz and can be divided by 4MHz or 5MHz.",
                 "value": "16000000",
                 "macro_name": "HSE_VALUE"
             },