video: Add some notes about the cursor

Provide a few notes about how the cursor works in the video console.

Signed-off-by: Simon Glass <sjg@chromium.org>

include/video_console.h

@@ -29,6 +29,26 @@ enum {
  * The cursor is set up and maintained by the vidconsole. It is a simple
  * vertical bar of width VIDCONSOLE_CURSOR_WIDTH shown in the foreground colour.
  *
+ * No cursor processing is done unless @enabled is true.
+ *
+ * To figure out where to draw the cursor, the vidconsole's get_cursor_info() is
+ * called. It fills in the @x, @y, @height and @index information below. That
+ * information remains valid while the cursor is shown, so it can be used to
+ * hide the cursor.
+ *
+ * The cursor is drawn only when idle (by vidconsole_show_cursor() called from
+ * vidconsole_idle()). It is erased as soon as any output needs to be written to
+ * the display - vidconsole_hide_cursor() is called from a few places in the
+ * vidconsole uclass.
+ *
+ * Under the hood, vidconsole_show_cursor() calls cursor_show() which saves the
+ * pixels under the cursor as it draws it. Once finished it sets @visible to
+ * true, so that we know we must erase the cursor before drawing anything else.
+ *
+ * The old pixels end up in @save_data and are used by cursor_hide() (called
+ * from vidconsole_hide_cursor()) to restore the display contents to what they
+ * were. Once that is done, @visible is set back to false.
+ *
  * @enabled:	cursor is active (e.g. during readline)
  * @visible:	cursor is currently visible
  * @indent:	indent subsequent lines to the same position as the first line