drivers: can: Improve rendering of API comments
- Hide internal driver API from public documentation - Use consistent upper-case naming for CAN, RTR, etc. - Fix indentation of some comments so that they are rendered with monospace font. Signed-off-by: Martin Jäger <martin@libre.solar>
This commit is contained in:
Martin Jäger
Anas Nashif
parent
d1a93c1426
commit
053ee94d49
1 changed files with 44 additions and 30 deletions
|
|
@ -84,8 +84,7 @@ extern "C" {
|
|||
K_MSGQ_DEFINE(name, sizeof(struct zcan_frame), size, 4)
|
||||
|
||||
/**
|
||||
* @brief can_ide enum
|
||||
* Define if the message has a standard (11bit) or extended (29bit)
|
||||
* @brief Define if the message has a standard (11bit) or extended (29bit)
|
||||
* identifier
|
||||
*/
|
||||
enum can_ide {
|
||||
|
|
@ -94,8 +93,7 @@ enum can_ide {
|
|||
};
|
||||
|
||||
/**
|
||||
* @brief can_rtr enum
|
||||
* Define if the message is a data or remote frame
|
||||
* @brief Defines if the message is a data or remote frame
|
||||
*/
|
||||
enum can_rtr {
|
||||
CAN_DATAFRAME,
|
||||
|
|
@ -103,8 +101,7 @@ enum can_rtr {
|
|||
};
|
||||
|
||||
/**
|
||||
* @brief can_mode enum
|
||||
* Defines the mode of the can controller
|
||||
* @brief Defines the mode of the CAN controller
|
||||
*/
|
||||
enum can_mode {
|
||||
/*Normal mode*/
|
||||
|
|
@ -118,8 +115,7 @@ enum can_mode {
|
|||
};
|
||||
|
||||
/**
|
||||
* @brief can_state enum
|
||||
* Defines the possible states of the CAN bus
|
||||
* @brief Defines the possible states of the CAN bus
|
||||
*/
|
||||
enum can_state {
|
||||
CAN_ERROR_ACTIVE,
|
||||
|
|
@ -128,15 +124,22 @@ enum can_state {
|
|||
CAN_BUS_UNKNOWN
|
||||
};
|
||||
|
||||
/*
|
||||
/**
|
||||
* Controller Area Network Identifier structure for Linux compatibility.
|
||||
*
|
||||
* The fields in this type are:
|
||||
*
|
||||
* bit 0-28 : CAN identifier (11/29 bit)
|
||||
* bit 29 : error message frame flag (0 = data frame, 1 = error message)
|
||||
* bit 30 : remote transmission request flag (1 = rtr frame)
|
||||
* bit 31 : frame format flag (0 = standard 11 bit, 1 = extended 29 bit)
|
||||
* +------+--------------------------------------------------------------+
|
||||
* | Bits | Description |
|
||||
* +======+==============================================================+
|
||||
* | 0-28 | CAN identifier (11/29 bit) |
|
||||
* +------+--------------------------------------------------------------+
|
||||
* | 29 | Error message frame flag (0 = data frame, 1 = error message) |
|
||||
* +------+--------------------------------------------------------------+
|
||||
* | 30 | Remote transmission request flag (1 = RTR frame) |
|
||||
* +------+--------------------------------------------------------------+
|
||||
* | 31 | Frame format flag (0 = standard 11 bit, 1 = extended 29 bit) |
|
||||
* +------+--------------------------------------------------------------+
|
||||
*/
|
||||
typedef uint32_t canid_t;
|
||||
|
||||
|
|
@ -180,7 +183,6 @@ struct can_filter {
|
|||
*
|
||||
* Used to pass can messages from userspace to the driver and
|
||||
* from driver to userspace
|
||||
*
|
||||
*/
|
||||
struct zcan_frame {
|
||||
/** Message identifier*/
|
||||
|
|
@ -226,7 +228,7 @@ struct zcan_frame {
|
|||
* @brief CAN filter structure
|
||||
*
|
||||
* Used to pass can identifier filter information to the driver.
|
||||
* rtr_mask and *_id_mask are used to mask bits of the rtr and id fields.
|
||||
* rtr_mask and *_id_mask are used to mask bits of the RTR and id fields.
|
||||
* If the mask bit is 0, the value of the corresponding bit in the id or rtr
|
||||
* field don't care for the filter matching.
|
||||
*
|
||||
|
|
@ -235,7 +237,7 @@ struct zcan_filter {
|
|||
/** target state of the identifier */
|
||||
uint32_t id : 29;
|
||||
uint32_t res0 : 1;
|
||||
/** target state of the rtr bit */
|
||||
/** target state of the RTR bit */
|
||||
uint32_t rtr : 1;
|
||||
/** Indicates the identifier type (standard or extended)
|
||||
* use can_ide enum for assignment
|
||||
|
|
@ -244,13 +246,13 @@ struct zcan_filter {
|
|||
/** identifier mask*/
|
||||
uint32_t id_mask : 29;
|
||||
uint32_t res1 : 1;
|
||||
/** rtr bit mask */
|
||||
/** RTR bit mask */
|
||||
uint32_t rtr_mask : 1;
|
||||
uint32_t res2 : 1;
|
||||
};
|
||||
|
||||
/**
|
||||
* @brief can bus error count structure
|
||||
* @brief CAN bus error count structure
|
||||
*
|
||||
* Used to pass the bus error counters to userspace
|
||||
*/
|
||||
|
|
@ -263,7 +265,7 @@ struct can_bus_err_cnt {
|
|||
#define CAN_SJW_NO_CHANGE 0
|
||||
|
||||
/**
|
||||
* @brief canbus timings
|
||||
* @brief CAN bus timings
|
||||
*
|
||||
* Used to pass bus timing values to the config and bitrate calculator function.
|
||||
*
|
||||
|
|
@ -272,11 +274,13 @@ struct can_bus_err_cnt {
|
|||
* prop_seg and phase_seg1 affect the sampling-point in the same way and some
|
||||
* controllers only have a register for the sum of those two. The sync segment
|
||||
* always has a length of 1 tq
|
||||
* +---------+----------+------------+------------+
|
||||
* |sync_seg | prop_seg | phase_seg1 | phase_seg2 |
|
||||
* +---------+----------+------------+------------+
|
||||
* ^
|
||||
* Sampling-Point
|
||||
*
|
||||
* +---------+----------+------------+------------+
|
||||
* |sync_seg | prop_seg | phase_seg1 | phase_seg2 |
|
||||
* +---------+----------+------------+------------+
|
||||
* ^
|
||||
* Sampling-Point
|
||||
*
|
||||
* 1 tq (time quantum) has the length of 1/(core_clock / prescaler)
|
||||
* The bitrate is defined by the core clock divided by the prescaler and the
|
||||
* sum of the segments.
|
||||
|
|
@ -298,6 +302,12 @@ struct can_timing {
|
|||
uint16_t prescaler;
|
||||
};
|
||||
|
||||
/**
|
||||
* @cond INTERNAL_HIDDEN
|
||||
*
|
||||
* For internal use only, skip these in public documentation.
|
||||
*/
|
||||
|
||||
/**
|
||||
* @typedef can_tx_callback_t
|
||||
* @brief Define the application callback handler function signature
|
||||
|
|
@ -406,6 +416,10 @@ __subsystem struct can_driver_api {
|
|||
#endif
|
||||
};
|
||||
|
||||
/**
|
||||
* @endcond
|
||||
*/
|
||||
|
||||
/**
|
||||
* @brief Convert the DLC to the number of bytes
|
||||
*
|
||||
|
|
@ -449,8 +463,8 @@ static inline uint8_t can_bytes_to_dlc(uint8_t num_bytes)
|
|||
* @brief Perform data transfer to CAN bus.
|
||||
*
|
||||
* This routine provides a generic interface to perform data transfer
|
||||
* to the can bus. Use can_write() for simple write.
|
||||
* *
|
||||
* to the CAN bus. Use can_write() for simple write.
|
||||
*
|
||||
* @param dev Pointer to the device structure for the driver instance.
|
||||
* @param msg Message to transfer.
|
||||
* @param timeout Waiting for empty tx mailbox timeout or K_FOREVER.
|
||||
|
|
@ -480,11 +494,11 @@ static inline int z_impl_can_send(const struct device *dev,
|
|||
}
|
||||
|
||||
/*
|
||||
* Derived can APIs -- all implemented in terms of can_send()
|
||||
* Derived CAN APIs -- all implemented in terms of can_send()
|
||||
*/
|
||||
|
||||
/**
|
||||
* @brief Write a set amount of data to the can bus.
|
||||
* @brief Write a set amount of data to the CAN bus.
|
||||
*
|
||||
* This routine writes a set amount of data synchronously.
|
||||
*
|
||||
|
|
@ -583,7 +597,7 @@ __syscall int can_attach_msgq(const struct device *dev, struct k_msgq *msg_q,
|
|||
* If a message passes more than one filter the priority of the match
|
||||
* is hardware dependent.
|
||||
* A callback function can be attached to more than one filter.
|
||||
* *
|
||||
*
|
||||
* @param dev Pointer to the device structure for the driver instance.
|
||||
* @param isr Callback function pointer.
|
||||
* @param callback_arg This will be passed whenever the isr is called.
|
||||
|
|
@ -609,7 +623,7 @@ static inline int can_attach_isr(const struct device *dev,
|
|||
*
|
||||
* This routine detaches an isr callback or message queue from the identifier
|
||||
* filtering.
|
||||
* *
|
||||
*
|
||||
* @param dev Pointer to the device structure for the driver instance.
|
||||
* @param filter_id filter id returned by can_attach_isr or can_attach_msgq.
|
||||
*
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue