diff options
author | Maarten Lankhorst <maarten.lankhorst@linux.intel.com> | 2016-07-27 15:33:12 +0200 |
---|---|---|
committer | Maarten Lankhorst <maarten.lankhorst@linux.intel.com> | 2016-07-27 15:33:12 +0200 |
commit | 2d672a107e8e37e3d9968daec5e4abddd1b66abc (patch) | |
tree | 20c3be66471ee719d3e7123fb063e6ee3e7fc8df /lib | |
parent | c4cbc4dbf371ac29f0a0588883094a1a70aa7274 (diff) |
lib/igt_kms: Add some more documentation to some common kms functions.
Signed-off-by: Maarten Lankhorst <maarten.lankhorst@linux.intel.com>
Diffstat (limited to 'lib')
-rw-r--r-- | lib/igt_kms.c | 40 | ||||
-rw-r--r-- | lib/igt_kms.h | 68 |
2 files changed, 100 insertions, 8 deletions
diff --git a/lib/igt_kms.c b/lib/igt_kms.c index 8b507b21..7d7a53c9 100644 --- a/lib/igt_kms.c +++ b/lib/igt_kms.c @@ -468,6 +468,8 @@ uint32_t kmstest_find_crtc_for_connector(int fd, drmModeRes *res, * @width: width of the buffer in pixels * @height: height of the buffer in pixels * @bpp: bytes per pixel of the buffer + * @stride: Pointer which receives the dumb bo's stride, can be NULL. + * @size: Pointer which receives the dumb bo's size, can be NULL. * * This wraps the CREATE_DUMB ioctl, which allocates a new dumb buffer object * for the specified dimensions. @@ -2269,6 +2271,25 @@ static int do_display_commit(igt_display_t *display, return 0; } +/** + * igt_display_try_commit_atomic: + * @display: #igt_display_t to commit. + * @flags: Flags passed to drmModeAtomicCommit. + * @user_data: User defined pointer passed to drmModeAtomicCommit. + * + * This function is similar to #igt_display_try_commit2, but is + * used when you want to pass different flags to the actual commit. + * + * Useful flags can be DRM_MODE_ATOMIC_ALLOW_MODESET, + * DRM_MODE_ATOMIC_NONBLOCK, DRM_MODE_PAGE_FLIP_EVENT, + * or DRM_MODE_ATOMIC_TEST_ONLY. + * + * @user_data is returned in the event if you pass + * DRM_MODE_PAGE_FLIP_EVENT to @flags. + * + * This function will return an error if commit fails, instead of + * aborting the test. + */ int igt_display_try_commit_atomic(igt_display_t *display, uint32_t flags, void *user_data) { int ret; @@ -2291,6 +2312,24 @@ int igt_display_try_commit_atomic(igt_display_t *display, uint32_t flags, void * return 0; } +/** + * igt_display_commit_atomic: + * @display: #igt_display_t to commit. + * @flags: Flags passed to drmModeAtomicCommit. + * @user_data: User defined pointer passed to drmModeAtomicCommit. + * + * This function is similar to #igt_display_commit2, but is + * used when you want to pass different flags to the actual commit. + * + * Useful flags can be DRM_MODE_ATOMIC_ALLOW_MODESET, + * DRM_MODE_ATOMIC_NONBLOCK, DRM_MODE_PAGE_FLIP_EVENT, + * or DRM_MODE_ATOMIC_TEST_ONLY. + * + * @user_data is returned in the event if you pass + * DRM_MODE_PAGE_FLIP_EVENT to @flags. + * + * This function will abort the test if commit fails. + */ void igt_display_commit_atomic(igt_display_t *display, uint32_t flags, void *user_data) { int ret = igt_display_try_commit_atomic(display, flags, user_data); @@ -2715,6 +2754,7 @@ void igt_reset_connectors(void) /** * kmstest_get_vbl_flag: + * @pipe_id: Pipe to convert to flag representation. * * Convert a pipe id into the flag representation * expected in DRM while processing DRM_IOCTL_WAIT_VBLANK. diff --git a/lib/igt_kms.h b/lib/igt_kms.h index bc7825a3..005d7e8c 100644 --- a/lib/igt_kms.h +++ b/lib/igt_kms.h @@ -39,6 +39,15 @@ /* Low-level helpers with kmstest_ prefix */ +/** + * pipe: + * @PIPE_NONE: Invalid pipe, used for disconnecting a output from a pipe. + * @PIPE_ANY: Deprecated alias for @PIPE_NONE. + * @PIPE_A: First crtc. + * @PIPE_B: Second crtc. + * @PIPE_C: Third crtc. + * @I915_MAX_PIPES: Max number of pipes allowed. + */ enum pipe { PIPE_NONE = -1, PIPE_ANY = PIPE_NONE, @@ -174,6 +183,13 @@ void *kmstest_dumb_map_buffer(int fd, uint32_t handle, uint64_t size, */ /* High-level kms api with igt_ prefix */ + +/** + * igt_commit_style: + * @COMMIT_LEGACY: Changes will be committed using the legacy API. + * @COMMIT_UNIVERSAL: Changes will be committed with the universal plane API, no modesets are allowed. + * @COMMIT_ATOMIC: Changes will be committed using the atomic API. + */ enum igt_commit_style { COMMIT_LEGACY = 0, COMMIT_UNIVERSAL, @@ -351,24 +367,50 @@ static inline bool igt_output_is_connected(igt_output_t *output) return false; } -static inline bool igt_pipe_connector_valid(enum pipe pipe, - igt_output_t *output) -{ - return igt_output_is_connected(output) && - (output->config.valid_crtc_idx_mask & (1 << pipe)); -} +/** + * igt_pipe_connector_valid: + * @pipe: pipe to check. + * @output: #igt_output_t to check. + * + * Checks whether the given pipe and output can be used together. + */ +#define igt_pipe_connector_valid(pipe, output) \ + (igt_output_is_connected((output)) && \ + (output->config.valid_crtc_idx_mask & (1 << (pipe)))) #define for_each_if(condition) if (!(condition)) {} else +/** + * for_each_connected_output: + * @display: a pointer to an #igt_display_t structure + * @output: The output to iterate. + * + * This for loop iterates over all outputs. + */ #define for_each_connected_output(display, output) \ for (int i__ = 0; i__ < (display)->n_outputs; i__++) \ for_each_if (((output = &(display)->outputs[i__]), \ igt_output_is_connected(output))) +/** + * for_each_pipe: + * @display: a pointer to an #igt_display_t structure + * @pipe: The pipe to iterate. + * + * This for loop iterates over all pipes. + */ #define for_each_pipe(display, pipe) \ - for (pipe = 0; pipe < igt_display_get_n_pipes(display); pipe++) \ + for (pipe = 0; pipe < igt_display_get_n_pipes(display); pipe++) -/* Big complex macro to make 'break' work as expected. */ +/** + * for_each_pipe_with_valid_output: + * @display: a pointer to an #igt_display_t structure + * @pipe: The pipe for which this @pipe / @output combination is valid. + * @output: The output for which this @pipe / @output combination is valid. + * + * This for loop is called over all connected outputs. This function + * will try every combination of @pipe and @output. + */ #define for_each_pipe_with_valid_output(display, pipe, output) \ for (int con__ = pipe = 0; \ pipe < igt_display_get_n_pipes((display)) && con__ < (display)->n_outputs; \ @@ -376,6 +418,16 @@ static inline bool igt_pipe_connector_valid(enum pipe pipe, for_each_if (((output = &(display)->outputs[con__]), \ igt_pipe_connector_valid(pipe, output))) +/** + * for_each_valid_output_on_pipe: + * @display: a pointer to an #igt_display_t structure + * @pipe: Pipe to enumerate valid outputs over + * @output: The enumerated output. + * + * This for loop is called over all connected @output that can be used + * on this @pipe . If there are no valid outputs for this pipe, nothing + * happens. + */ #define for_each_valid_output_on_pipe(display, pipe, output) \ for_each_connected_output(display, output) \ for_each_if (igt_pipe_connector_valid(pipe, output)) |