[Concept,02/14] video: Add a little more documentation to the uclass
Commit Message
From: Simon Glass <sjg@chromium.org>
The copy buffer is a bit confusing, so add some more documentation for
it.
Signed-off-by: Simon Glass <sjg@chromium.org>
---
drivers/video/video-uclass.c | 30 ++++++++++++++++++++++++++----
1 file changed, 26 insertions(+), 4 deletions(-)
@@ -47,10 +47,32 @@
* @size and @align information and this time video_post_bind() checks that
* the drivers does not overflow the allocated memory.
*
- * The frame buffer address is actually set (to plat->base) in
- * video_post_probe(). This function also clears the frame buffer and
- * allocates a suitable text console device. This can then be used to write
- * text to the video device.
+ * The driver's probe() function is called, which should set up the hardware
+ * and fill in any required fields in struct video_uc_plat and
+ * struct video_priv.
+ *
+ * After the driver's probe() completes, video_post_probe() is called. This
+ * converts the framebuffer addresses (plat->base and plat->copy_base) to
+ * pointers (priv->fb and priv->copy_fb), clears the frame buffer, and
+ * allocates a suitable text-console device. The console can then be used to
+ * write text to the video device.
+ *
+ * Copy framebuffer (CONFIG_VIDEO_COPY):
+ *
+ * To avoid flicker, some drivers need to draw to an off-screen buffer and
+ * then copy to the visible framebuffer. Drivers can enable this in two ways:
+ *
+ * 1) If the framebuffer is in fixed memory (common on x86 hardware), in
+ * bind() leave plat->size as 0 but set up plat->copy_size. This will allocate a
+ * copy buffer. The driver must then set copy_base to the fixed-memory address
+ * and base to the allocated copy_base. See for example vesa_setup_video_priv().
+ *
+ * 2) Otherwise, since plat->size to the required value. The off-screen
+ * framebuffer will be allocated. The driver must then set up copy_base in the
+ * probe() method.
+ *
+ * In both cases, U-Boot draws to priv->fb and video_sync() copies the
+ * damaged regions from priv->fb to priv->copy_fb to make them visible.
*/
DECLARE_GLOBAL_DATA_PTR;