dsHdmiIn HAL API Documentation Improvements and Specification Clarifications - #206
Open
KarthikeyanR470 wants to merge 2 commits into
Open
dsHdmiIn HAL API Documentation Improvements and Specification Clarifications#206KarthikeyanR470 wants to merge 2 commits into
KarthikeyanR470 wants to merge 2 commits into
Conversation
Contributor
There was a problem hiding this comment.
Pull request overview
This PR aims to improve the HDMI-In HAL specification clarity by refining parameter documentation and clarifying expected API behavior to reduce integration ambiguity.
Changes:
- Updates
dsGetHDMISPDInfo()to return SPD info via a dedicated SPD infoframe structure pointer (instead of a raw byte buffer). - Clarifies
dsGetAllmStatus()documentation to describe it as reporting current ALLM state (getter semantics). - Adjusts SPD-related parameter documentation to reference
dsSpd_infoframe_st.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| * | ||
| */ | ||
| dsError_t dsGetHDMISPDInfo (dsHdmiInPort_t iHdmiPort, unsigned char *data); | ||
| dsError_t dsGetHDMISPDInfo(dsHdmiInPort_t iHdmiPort, dsSpd_infoframe_st *spdInfo); |
Comment on lines
615
to
618
| * @param[in] iHdmiPort - HDMI input port. Please refer ::dsHdmiInPort_t | ||
| * @param[out] data - HDMI SPD info data | ||
| * Should not exceed sizeof(dsSpd_infoframe_st). Please refer ::dsSpd_infoframe_st | ||
| * Please refer ::dsSpd_infoframe_st. | ||
| * |
Comment on lines
+684
to
687
| * @brief Gets the current ALLM status for the specified HDMI input port | ||
| * | ||
| * For sink devices, this function checks whether ALLM status is enabled or disabled for the specific HDMI input port. | ||
| * For sink devices, this function checks whether ALLM status is enabled or disabled for the specified HDMI input port. | ||
| * For source devices, this function returns dsERR_OPERATION_NOT_SUPPORTED always. |
|
|
||
| /** | ||
| * @brief Checks whether ALLM status is enabled or disabled for the specific HDMI input port | ||
| * @brief Gets the current ALLM status for the specified HDMI input port |
Comment on lines
155
to
159
| * @retval dsERR_NONE - Success | ||
| * @retval dsERR_NOT_INITIALIZED - Module is not initialised | ||
| * @retval dsERR_INVALID_PARAM - Parameter passed to this function is invalid | ||
| * @retval dsERR_OPERATION_NOT_SUPPORTED - The attempted operation is not supported; e.g: source devices | ||
| * @retval dsERR_OPERATION_NOT_SUPPORTED - The attempted operation is not supported | ||
| * @retval dsERR_OPERATION_FAILED - The attempted operation has failed |
Comment on lines
615
to
+617
| * @param[in] iHdmiPort - HDMI input port. Please refer ::dsHdmiInPort_t | ||
| * @param[out] data - HDMI SPD info data | ||
| * Should not exceed sizeof(dsSpd_infoframe_st). Please refer ::dsSpd_infoframe_st | ||
| * Please refer ::dsSpd_infoframe_st. |
| * | ||
| */ | ||
| dsError_t dsGetHDMISPDInfo (dsHdmiInPort_t iHdmiPort, unsigned char *data); | ||
| dsError_t dsGetHDMISPDInfo(dsHdmiInPort_t iHdmiPort, dsSpd_infoframe_st *spdInfo); |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Goal
Improve HAL API specification clarity, consistency, and usability by addressing ambiguous documentation, refining parameter descriptions, and explicitly defining expected API behavior to prevent implementation and integration inconsistencies.
API: dsHdmiInGetNumberOfInputs()
Issue Description
The current specification states that source devices without HDMI input support "return 0", which is ambiguous. It is unclear whether this means:
The API returns dsERR_NONE and sets *NoOfinputs = 0, or
The API returns dsERR_OPERATION_NOT_SUPPORTED.
The specification should explicitly define the expected return status and output parameter behavior.
API: dsGetHDMISPDInfo()
Issue Description
The API uses unsigned char *data as the output parameter, while the documentation refers to dsSpd_infoframe_st and its size. This creates ambiguity regarding expected buffer size and data format. The specification should update the API to use dsSpd_infoframe_st * as the output parameter and document that the SPD information is returned through this structure.
API: dsGetAllmStatus()
Issue Description
The current documentation describes allmStatus as a "Flag to control the ALLM status". Since this is a getter API, the parameter does not control ALLM; it reports the current ALLM state. The specification should update the parameter description to indicate that it returns the current ALLM status of the specified HDMI input port.