vcons(9) - NetBSD Manual Pages

VCONS(9)               NetBSD Kernel Developer's Manual               VCONS(9)


NAME

     vcons -- generic virtual console framework


SYNOPSIS

     #include <wscons/wsdisplay_vconsvar.h>

     int
     vcons_init(struct vcons_data *vd, void *cookie,
         struct wsscreen_descr *desc, struct wsdisplay_accessops *accops);

     int
     vcons_init_screen(struct vcons_data *vd, struct vcons_screen *scr,
         int exists, long *defattr);

     void
     vcons_redraw_screen(struct vcons_screen *scr);


DESCRIPTION

     These functions are used to setup and control the generic virtual console
     framework.

     The vcons_init() function initializes the framework, it needs to be
     called for each driver that's going to use vcons.

     vcons_init_screen() adds a virtual screen to a display.

     vcons_redraw_screen() redraws a screen.  A driver should call it when
     returning to terminal emulation mode, for instance when X exits.

     struct vcons_data contains all information needed to manage virtual con-
     soles on a display, usually it will be a member of the driver's softc.

     struct vcons_screen describes a virtual screen.


USAGE

     To use vcons with a driver it needs to be initialized by calling
     vcons_init(), usually in the driver's attach function.

     vd        should be a pointer to the driver's struct vcons_data.

     cookie    should be a pointer to the driver's softc.

     desc      should point to a struct wsscreen_descr describing the default
               screen type for this display.

     accops    points to the driver's struct wsdisplay_accessops so
               vcons_init() can fill it in with its own implementations of
               alloc_screen(), free_screen(), and show_screen().

     A driver should however provide its own ioctl() and mmap() implementa-
     tions.  Both will receive a pointer to the driver's struct vcons_data as
     first parameter.

     After initialization the driver needs to provide a callback function that
     will be called whenever a screen is added.  Its purpose is to set up the
     struct rasops_info describing the screen.  After that the drawing methods
     in struct rasops_info will be replaced with wrappers which call the orig-
     inal drawing functions (which may or may not be provided by the driver)
     only when the respective screen is visible.  To add a virtual screen the
     driver one should call vcons_init_screen() which will call the callback
     function described above, allocate storage for characters and attributes
     based on whatever the callback set up in struct rasops_info, and add the
     screen to a list kept in struct vcons_data.

     The callback needs to have this form:

     void init_screen(void *cookie, struct vcons_screen *scr, int existing,
     long *defattr)

     and should be stored in the init_screen member found in struct
     vcons_data.  The arguments are:

     cookie    is the cookie passed to vcons_init()

     scr       points to the struct vcons_screen being added, its scr_ri mem-
               ber, a struct rasops_info, needs to be filled in.

     existing  is non-zero if the screen already exists and is only added to
               the list.

     defattr   points to the screen's default text attribute.  It's filled in
               by vcons_init_screen() by calling the alloc_attr() method found
               in struct rasops_info.

     When attaching a wsdisplay(9) the accesscookie member of the struct
     wsemuldisplaydev_attach_args passed to config_found() needs to be a
     pointer to the driver's struct vcons_data.

     The following members of struct vcons_screen may be of interest to driv-
     ers:

     scr_ri        contains the struct rasops_info describing the screen's
                   geometry, access methods and so on.

     scr_cookie    the value passed as cookie to vcons_init().  Usually the
                   driver's softc.

     scr_vd        the driver's struct vcons_data.

     scr_flags     can be zero or any combination of:
                   VCONS_NO_REDRAW         don't call vcons_redraw_screen()
                                           when this screen becomes visible.
                   VCONS_SCREEN_IS_STATIC  don't free(9) this screen's struct
                                           vcons_screen in free_screen() -
                                           useful if the screen has been stat-
                                           ically allocated.

     scr_status    currently contains only one flag, VCONS_IS_VISIBLE, which
                   is set when the screen is visible.


SEE ALSO

     wscons(4), wsdisplay(4)

NetBSD 10.99                   February 12, 2006                  NetBSD 10.99