Skip to content

drivers: can: clarify the meaning of minimum/maximum supported bitrates #80127

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Oct 23, 2024
Merged

drivers: can: clarify the meaning of minimum/maximum supported bitrates #80127

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
37 changes: 35 additions & 2 deletions include/zephyr/drivers/can.h
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -835,8 +835,16 @@ static inline int z_impl_can_get_core_clock(const struct device *dev, uint32_t *
*
* Get the minimum supported bitrate for the CAN controller/transceiver combination.
*
* @note The minimum bitrate represents limitations of the CAN controller/transceiver
* combination. Whether the CAN controller can achieve this bitrate depends on the CAN core clock
* rate and the minimum CAN timing limits.
*
* @see can_get_core_clock()
* @see can_get_timing_min()
* @see can_get_timing_data_min()
*
* @param dev Pointer to the device structure for the driver instance.
* @return Minimum supported bitrate in bits/s
* @return Minimum supported bitrate in bits/s. A value of 0 means the lower limit is unspecified.
*/
__syscall uint32_t can_get_bitrate_min(const struct device *dev);

Expand All @@ -854,8 +862,17 @@ static inline uint32_t z_impl_can_get_bitrate_min(const struct device *dev)
*
* @deprecated Use @a can_get_bitrate_min() instead.
*
* @note The minimum bitrate represents limitations of the CAN controller/transceiver
Copy link
Contributor

@kartben kartben Oct 23, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It's laudable to update the docs for the deprecated function -- it really is! -- but in this instance I wonder if it's not counter productive. Keeping the docs of the deprecated method as lean as possible helps make the @deprecated mention less buried in surrounding text.
I think it's acceptable to let the docs of a deprecated method go stale since, after all, any new user is encouraged to look for the replacement. And to some extent I think it's ok that any existing user in need to look back at the docs to understand/clarify the behavior would basically see the docs as they were when it was decided to deprecate the method.

Copy link
Member Author

@henrikbrixandersen henrikbrixandersen Oct 23, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thank you for reviewing. I opted to keep the documentation in sync between the deprecated functions and their replacement to convey that there are no functional changes between the two.

* combination. Whether the CAN controller can achieve this bitrate depends on the CAN core clock
* rate and the minimum CAN timing limits.
*
* @see can_get_core_clock()
* @see can_get_timing_min()
* @see can_get_timing_data_min()
*
* @param dev Pointer to the device structure for the driver instance.
* @param[out] min_bitrate Minimum supported bitrate in bits/s
* @param[out] min_bitrate Minimum supported bitrate in bits/s. A value of 0 means the lower limit
* is unspecified.
*
* @retval -EIO General input/output error.
* @retval -ENOSYS If this function is not implemented by the driver.
Expand All @@ -872,6 +889,14 @@ __deprecated static inline int can_get_min_bitrate(const struct device *dev, uin
*
* Get the maximum supported bitrate for the CAN controller/transceiver combination.
*
* @note The maximum bitrate represents limitations of the CAN controller/transceiver
* combination. Whether the CAN controller can achieve this bitrate depends on the CAN core clock
* rate and the maximum CAN timing limits.
*
* @see can_get_core_clock()
* @see can_get_timing_max()
* @see can_get_timing_data_max()
*
* @param dev Pointer to the device structure for the driver instance.
* @return Maximum supported bitrate in bits/s
*/
Expand All @@ -891,6 +916,14 @@ static inline uint32_t z_impl_can_get_bitrate_max(const struct device *dev)
*
* @deprecated Use @a can_get_bitrate_max() instead.
*
* @note The maximum bitrate represents limitations of the CAN controller/transceiver
* combination. Whether the CAN controller can achieve this bitrate depends on the CAN core clock
* rate and the maximum CAN timing limits.
*
* @see can_get_core_clock()
* @see can_get_timing_max()
* @see can_get_timing_data_max()
*
* @param dev Pointer to the device structure for the driver instance.
* @param[out] max_bitrate Maximum supported bitrate in bits/s
*
Expand Down
Loading