2 * QEMU graphical console
4 * Copyright (c) 2004 Fabrice Bellard
6 * Permission is hereby granted, free of charge, to any person obtaining a copy
7 * of this software and associated documentation files (the "Software"), to deal
8 * in the Software without restriction, including without limitation the rights
9 * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
10 * copies of the Software, and to permit persons to whom the Software is
11 * furnished to do so, subject to the following conditions:
13 * The above copyright notice and this permission notice shall be included in
14 * all copies or substantial portions of the Software.
16 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
17 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
18 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
19 * THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
20 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
21 * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
25 #include "qemu/osdep.h"
26 #include "ui/console.h"
27 #include "hw/qdev-core.h"
28 #include "qapi/error.h"
29 #include "qapi/qapi-commands-ui.h"
30 #include "qapi/visitor.h"
31 #include "qemu/coroutine.h"
32 #include "qemu/error-report.h"
33 #include "qemu/main-loop.h"
34 #include "qemu/module.h"
35 #include "qemu/option.h"
36 #include "chardev/char.h"
38 #include "exec/memory.h"
39 #include "qom/object.h"
41 #include "console-priv.h"
43 OBJECT_DEFINE_ABSTRACT_TYPE(QemuConsole
, qemu_console
, QEMU_CONSOLE
, OBJECT
)
45 typedef struct QemuGraphicConsole
{
52 int cursor_x
, cursor_y
;
56 typedef QemuConsoleClass QemuGraphicConsoleClass
;
58 OBJECT_DEFINE_TYPE(QemuGraphicConsole
, qemu_graphic_console
, QEMU_GRAPHIC_CONSOLE
, QEMU_CONSOLE
)
63 uint64_t update_interval
;
66 QLIST_HEAD(, DisplayChangeListener
) listeners
;
69 static DisplayState
*display_state
;
70 static QTAILQ_HEAD(, QemuConsole
) consoles
=
71 QTAILQ_HEAD_INITIALIZER(consoles
);
73 static void dpy_refresh(DisplayState
*s
);
74 static DisplayState
*get_alloc_displaystate(void);
75 static bool displaychangelistener_has_dmabuf(DisplayChangeListener
*dcl
);
76 static bool console_compatible_with(QemuConsole
*con
,
77 DisplayChangeListener
*dcl
, Error
**errp
);
78 static QemuConsole
*qemu_graphic_console_lookup_unused(void);
79 static void dpy_set_ui_info_timer(void *opaque
);
81 static void gui_update(void *opaque
)
83 uint64_t interval
= GUI_REFRESH_INTERVAL_IDLE
;
84 uint64_t dcl_interval
;
85 DisplayState
*ds
= opaque
;
86 DisplayChangeListener
*dcl
;
88 ds
->refreshing
= true;
90 ds
->refreshing
= false;
92 QLIST_FOREACH(dcl
, &ds
->listeners
, next
) {
93 dcl_interval
= dcl
->update_interval
?
94 dcl
->update_interval
: GUI_REFRESH_INTERVAL_DEFAULT
;
95 if (interval
> dcl_interval
) {
96 interval
= dcl_interval
;
99 if (ds
->update_interval
!= interval
) {
100 ds
->update_interval
= interval
;
101 trace_console_refresh(interval
);
103 ds
->last_update
= qemu_clock_get_ms(QEMU_CLOCK_REALTIME
);
104 timer_mod(ds
->gui_timer
, ds
->last_update
+ interval
);
107 static void gui_setup_refresh(DisplayState
*ds
)
109 DisplayChangeListener
*dcl
;
110 bool need_timer
= false;
112 QLIST_FOREACH(dcl
, &ds
->listeners
, next
) {
113 if (dcl
->ops
->dpy_refresh
!= NULL
) {
118 if (need_timer
&& ds
->gui_timer
== NULL
) {
119 ds
->gui_timer
= timer_new_ms(QEMU_CLOCK_REALTIME
, gui_update
, ds
);
120 timer_mod(ds
->gui_timer
, qemu_clock_get_ms(QEMU_CLOCK_REALTIME
));
122 if (!need_timer
&& ds
->gui_timer
!= NULL
) {
123 timer_free(ds
->gui_timer
);
124 ds
->gui_timer
= NULL
;
128 void graphic_hw_update_done(QemuConsole
*con
)
131 qemu_co_enter_all(&con
->dump_queue
, NULL
);
135 void graphic_hw_update(QemuConsole
*con
)
141 if (con
->hw_ops
->gfx_update
) {
142 con
->hw_ops
->gfx_update(con
->hw
);
143 async
= con
->hw_ops
->gfx_update_async
;
146 graphic_hw_update_done(con
);
150 static void graphic_hw_update_bh(void *con
)
152 graphic_hw_update(con
);
155 void qemu_console_co_wait_update(QemuConsole
*con
)
157 if (qemu_co_queue_empty(&con
->dump_queue
)) {
158 /* Defer the update, it will restart the pending coroutines */
159 aio_bh_schedule_oneshot(qemu_get_aio_context(),
160 graphic_hw_update_bh
, con
);
162 qemu_co_queue_wait(&con
->dump_queue
, NULL
);
166 static void graphic_hw_gl_unblock_timer(void *opaque
)
168 warn_report("console: no gl-unblock within one second");
171 void graphic_hw_gl_block(QemuConsole
*con
, bool block
)
181 assert(con
->gl_block
>= 0);
182 if (!con
->hw_ops
->gl_block
) {
185 if ((block
&& con
->gl_block
!= 1) || (!block
&& con
->gl_block
!= 0)) {
188 con
->hw_ops
->gl_block(con
->hw
, block
);
191 timeout
= qemu_clock_get_ms(QEMU_CLOCK_REALTIME
);
192 timeout
+= 1000; /* one sec */
193 timer_mod(con
->gl_unblock_timer
, timeout
);
195 timer_del(con
->gl_unblock_timer
);
199 int qemu_console_get_window_id(QemuConsole
*con
)
201 return con
->window_id
;
204 void qemu_console_set_window_id(QemuConsole
*con
, int window_id
)
206 con
->window_id
= window_id
;
209 void graphic_hw_invalidate(QemuConsole
*con
)
211 if (con
&& con
->hw_ops
->invalidate
) {
212 con
->hw_ops
->invalidate(con
->hw
);
216 void graphic_hw_text_update(QemuConsole
*con
, console_ch_t
*chardata
)
218 if (con
&& con
->hw_ops
->text_update
) {
219 con
->hw_ops
->text_update(con
->hw
, chardata
);
223 static void displaychangelistener_gfx_switch(DisplayChangeListener
*dcl
,
224 struct DisplaySurface
*new_surface
,
227 if (dcl
->ops
->dpy_gfx_switch
) {
228 dcl
->ops
->dpy_gfx_switch(dcl
, new_surface
);
231 if (update
&& dcl
->ops
->dpy_gfx_update
) {
232 dcl
->ops
->dpy_gfx_update(dcl
, 0, 0,
233 surface_width(new_surface
),
234 surface_height(new_surface
));
238 static void dpy_gfx_create_texture(QemuConsole
*con
, DisplaySurface
*surface
)
240 if (con
->gl
&& con
->gl
->ops
->dpy_gl_ctx_create_texture
) {
241 con
->gl
->ops
->dpy_gl_ctx_create_texture(con
->gl
, surface
);
245 static void dpy_gfx_destroy_texture(QemuConsole
*con
, DisplaySurface
*surface
)
247 if (con
->gl
&& con
->gl
->ops
->dpy_gl_ctx_destroy_texture
) {
248 con
->gl
->ops
->dpy_gl_ctx_destroy_texture(con
->gl
, surface
);
252 static void dpy_gfx_update_texture(QemuConsole
*con
, DisplaySurface
*surface
,
253 int x
, int y
, int w
, int h
)
255 if (con
->gl
&& con
->gl
->ops
->dpy_gl_ctx_update_texture
) {
256 con
->gl
->ops
->dpy_gl_ctx_update_texture(con
->gl
, surface
, x
, y
, w
, h
);
260 static void displaychangelistener_display_console(DisplayChangeListener
*dcl
,
263 static const char nodev
[] =
264 "This VM has no graphic display device.";
265 static DisplaySurface
*dummy
;
266 QemuConsole
*con
= dcl
->con
;
268 if (!con
|| !console_compatible_with(con
, dcl
, errp
)) {
270 dummy
= qemu_create_placeholder_surface(640, 480, nodev
);
273 dpy_gfx_create_texture(con
, dummy
);
275 displaychangelistener_gfx_switch(dcl
, dummy
, TRUE
);
279 dpy_gfx_create_texture(con
, con
->surface
);
280 displaychangelistener_gfx_switch(dcl
, con
->surface
,
281 con
->scanout
.kind
== SCANOUT_SURFACE
);
283 if (con
->scanout
.kind
== SCANOUT_DMABUF
&&
284 displaychangelistener_has_dmabuf(dcl
)) {
285 dcl
->ops
->dpy_gl_scanout_dmabuf(dcl
, con
->scanout
.dmabuf
);
286 } else if (con
->scanout
.kind
== SCANOUT_TEXTURE
&&
287 dcl
->ops
->dpy_gl_scanout_texture
) {
288 dcl
->ops
->dpy_gl_scanout_texture(dcl
,
289 con
->scanout
.texture
.backing_id
,
290 con
->scanout
.texture
.backing_y_0_top
,
291 con
->scanout
.texture
.backing_width
,
292 con
->scanout
.texture
.backing_height
,
293 con
->scanout
.texture
.x
,
294 con
->scanout
.texture
.y
,
295 con
->scanout
.texture
.width
,
296 con
->scanout
.texture
.height
,
297 con
->scanout
.texture
.d3d_tex2d
);
301 void qemu_text_console_put_keysym(QemuTextConsole
*s
, int keysym
)
303 qemu_text_console_handle_keysym(s
, keysym
);
306 static const int qcode_to_keysym
[Q_KEY_CODE__MAX
] = {
307 [Q_KEY_CODE_UP
] = QEMU_KEY_UP
,
308 [Q_KEY_CODE_DOWN
] = QEMU_KEY_DOWN
,
309 [Q_KEY_CODE_RIGHT
] = QEMU_KEY_RIGHT
,
310 [Q_KEY_CODE_LEFT
] = QEMU_KEY_LEFT
,
311 [Q_KEY_CODE_HOME
] = QEMU_KEY_HOME
,
312 [Q_KEY_CODE_END
] = QEMU_KEY_END
,
313 [Q_KEY_CODE_PGUP
] = QEMU_KEY_PAGEUP
,
314 [Q_KEY_CODE_PGDN
] = QEMU_KEY_PAGEDOWN
,
315 [Q_KEY_CODE_DELETE
] = QEMU_KEY_DELETE
,
316 [Q_KEY_CODE_TAB
] = QEMU_KEY_TAB
,
317 [Q_KEY_CODE_BACKSPACE
] = QEMU_KEY_BACKSPACE
,
320 static const int ctrl_qcode_to_keysym
[Q_KEY_CODE__MAX
] = {
321 [Q_KEY_CODE_UP
] = QEMU_KEY_CTRL_UP
,
322 [Q_KEY_CODE_DOWN
] = QEMU_KEY_CTRL_DOWN
,
323 [Q_KEY_CODE_RIGHT
] = QEMU_KEY_CTRL_RIGHT
,
324 [Q_KEY_CODE_LEFT
] = QEMU_KEY_CTRL_LEFT
,
325 [Q_KEY_CODE_HOME
] = QEMU_KEY_CTRL_HOME
,
326 [Q_KEY_CODE_END
] = QEMU_KEY_CTRL_END
,
327 [Q_KEY_CODE_PGUP
] = QEMU_KEY_CTRL_PAGEUP
,
328 [Q_KEY_CODE_PGDN
] = QEMU_KEY_CTRL_PAGEDOWN
,
331 bool qemu_text_console_put_qcode(QemuTextConsole
*s
, int qcode
, bool ctrl
)
335 keysym
= ctrl
? ctrl_qcode_to_keysym
[qcode
] : qcode_to_keysym
[qcode
];
339 qemu_text_console_put_keysym(s
, keysym
);
343 void qemu_text_console_put_string(QemuTextConsole
*s
, const char *str
, int len
)
347 for (i
= 0; i
< len
&& str
[i
]; i
++) {
348 qemu_text_console_put_keysym(s
, str
[i
]);
353 qemu_console_register(QemuConsole
*c
)
357 if (QTAILQ_EMPTY(&consoles
)) {
359 QTAILQ_INSERT_TAIL(&consoles
, c
, next
);
360 } else if (!QEMU_IS_GRAPHIC_CONSOLE(c
) || phase_check(PHASE_MACHINE_READY
)) {
361 QemuConsole
*last
= QTAILQ_LAST(&consoles
);
362 c
->index
= last
->index
+ 1;
363 QTAILQ_INSERT_TAIL(&consoles
, c
, next
);
366 * HACK: Put graphical consoles before text consoles.
368 * Only do that for coldplugged devices. After initial device
369 * initialization we will not renumber the consoles any more.
371 QemuConsole
*it
= QTAILQ_FIRST(&consoles
);
373 while (QTAILQ_NEXT(it
, next
) != NULL
&& QEMU_IS_GRAPHIC_CONSOLE(it
)) {
374 it
= QTAILQ_NEXT(it
, next
);
376 if (QEMU_IS_GRAPHIC_CONSOLE(it
)) {
377 /* have no text consoles */
378 c
->index
= it
->index
+ 1;
379 QTAILQ_INSERT_AFTER(&consoles
, it
, c
, next
);
381 c
->index
= it
->index
;
382 QTAILQ_INSERT_BEFORE(it
, c
, next
);
383 /* renumber text consoles */
384 for (i
= c
->index
+ 1; it
!= NULL
; it
= QTAILQ_NEXT(it
, next
), i
++) {
392 qemu_console_finalize(Object
*obj
)
394 QemuConsole
*c
= QEMU_CONSOLE(obj
);
396 /* TODO: check this code path, and unregister from consoles */
397 g_clear_pointer(&c
->surface
, qemu_free_displaysurface
);
398 g_clear_pointer(&c
->gl_unblock_timer
, timer_free
);
399 g_clear_pointer(&c
->ui_timer
, timer_free
);
403 qemu_console_class_init(ObjectClass
*oc
, void *data
)
408 qemu_console_init(Object
*obj
)
410 QemuConsole
*c
= QEMU_CONSOLE(obj
);
411 DisplayState
*ds
= get_alloc_displaystate();
413 qemu_co_queue_init(&c
->dump_queue
);
416 c
->ui_timer
= timer_new_ms(QEMU_CLOCK_REALTIME
,
417 dpy_set_ui_info_timer
, c
);
418 qemu_console_register(c
);
422 qemu_graphic_console_finalize(Object
*obj
)
424 QemuGraphicConsole
*c
= QEMU_GRAPHIC_CONSOLE(obj
);
426 g_clear_pointer(&c
->device
, object_unref
);
430 qemu_graphic_console_prop_get_head(Object
*obj
, Visitor
*v
, const char *name
,
431 void *opaque
, Error
**errp
)
433 QemuGraphicConsole
*c
= QEMU_GRAPHIC_CONSOLE(obj
);
435 visit_type_uint32(v
, name
, &c
->head
, errp
);
439 qemu_graphic_console_class_init(ObjectClass
*oc
, void *data
)
441 object_class_property_add_link(oc
, "device", TYPE_DEVICE
,
442 offsetof(QemuGraphicConsole
, device
),
443 object_property_allow_set_link
,
444 OBJ_PROP_LINK_STRONG
);
445 object_class_property_add(oc
, "head", "uint32",
446 qemu_graphic_console_prop_get_head
,
451 qemu_graphic_console_init(Object
*obj
)
456 void qemu_displaysurface_win32_set_handle(DisplaySurface
*surface
,
457 HANDLE h
, uint32_t offset
)
459 assert(!surface
->handle
);
462 surface
->handle_offset
= offset
;
466 win32_pixman_image_destroy(pixman_image_t
*image
, void *data
)
468 DisplaySurface
*surface
= data
;
470 if (!surface
->handle
) {
474 assert(surface
->handle_offset
== 0);
477 pixman_image_get_data(surface
->image
),
484 DisplaySurface
*qemu_create_displaysurface(int width
, int height
)
486 DisplaySurface
*surface
;
489 HANDLE handle
= NULL
;
492 trace_displaysurface_create(width
, height
);
495 bits
= qemu_win32_map_alloc(width
* height
* 4, &handle
, &error_abort
);
498 surface
= qemu_create_displaysurface_from(
503 surface
->flags
= QEMU_ALLOCATED_FLAG
;
506 qemu_displaysurface_win32_set_handle(surface
, handle
, 0);
511 DisplaySurface
*qemu_create_displaysurface_from(int width
, int height
,
512 pixman_format_code_t format
,
513 int linesize
, uint8_t *data
)
515 DisplaySurface
*surface
= g_new0(DisplaySurface
, 1);
517 trace_displaysurface_create_from(surface
, width
, height
, format
);
518 surface
->image
= pixman_image_create_bits(format
,
520 (void *)data
, linesize
);
521 assert(surface
->image
!= NULL
);
523 pixman_image_set_destroy_function(surface
->image
,
524 win32_pixman_image_destroy
, surface
);
530 DisplaySurface
*qemu_create_displaysurface_pixman(pixman_image_t
*image
)
532 DisplaySurface
*surface
= g_new0(DisplaySurface
, 1);
534 trace_displaysurface_create_pixman(surface
);
535 surface
->image
= pixman_image_ref(image
);
540 DisplaySurface
*qemu_create_placeholder_surface(int w
, int h
,
543 DisplaySurface
*surface
= qemu_create_displaysurface(w
, h
);
545 pixman_color_t bg
= QEMU_PIXMAN_COLOR_BLACK
;
546 pixman_color_t fg
= QEMU_PIXMAN_COLOR_GRAY
;
547 pixman_image_t
*glyph
;
551 x
= (w
/ FONT_WIDTH
- len
) / 2;
552 y
= (h
/ FONT_HEIGHT
- 1) / 2;
553 for (i
= 0; i
< len
; i
++) {
554 glyph
= qemu_pixman_glyph_from_vgafont(FONT_HEIGHT
, vgafont16
, msg
[i
]);
555 qemu_pixman_glyph_render(glyph
, surface
->image
, &fg
, &bg
,
556 x
+i
, y
, FONT_WIDTH
, FONT_HEIGHT
);
557 qemu_pixman_image_unref(glyph
);
560 surface
->flags
|= QEMU_PLACEHOLDER_FLAG
;
564 void qemu_free_displaysurface(DisplaySurface
*surface
)
566 if (surface
== NULL
) {
569 trace_displaysurface_free(surface
);
570 qemu_pixman_image_unref(surface
->image
);
574 bool console_has_gl(QemuConsole
*con
)
576 return con
->gl
!= NULL
;
579 static bool displaychangelistener_has_dmabuf(DisplayChangeListener
*dcl
)
581 if (dcl
->ops
->dpy_has_dmabuf
) {
582 return dcl
->ops
->dpy_has_dmabuf(dcl
);
585 if (dcl
->ops
->dpy_gl_scanout_dmabuf
) {
592 static bool console_compatible_with(QemuConsole
*con
,
593 DisplayChangeListener
*dcl
, Error
**errp
)
597 flags
= con
->hw_ops
->get_flags
? con
->hw_ops
->get_flags(con
->hw
) : 0;
599 if (console_has_gl(con
) &&
600 !con
->gl
->ops
->dpy_gl_ctx_is_compatible_dcl(con
->gl
, dcl
)) {
601 error_setg(errp
, "Display %s is incompatible with the GL context",
606 if (flags
& GRAPHIC_FLAGS_GL
&&
607 !console_has_gl(con
)) {
608 error_setg(errp
, "The console requires a GL context.");
613 if (flags
& GRAPHIC_FLAGS_DMABUF
&&
614 !displaychangelistener_has_dmabuf(dcl
)) {
615 error_setg(errp
, "The console requires display DMABUF support.");
622 void console_handle_touch_event(QemuConsole
*con
,
623 struct touch_slot touch_slots
[INPUT_EVENT_SLOTS_MAX
],
625 int width
, int height
,
627 InputMultiTouchType type
,
630 struct touch_slot
*slot
;
631 bool needs_sync
= false;
635 if (num_slot
>= INPUT_EVENT_SLOTS_MAX
) {
637 "Unexpected touch slot number: % " PRId64
" >= %d",
638 num_slot
, INPUT_EVENT_SLOTS_MAX
);
642 slot
= &touch_slots
[num_slot
];
646 if (type
== INPUT_MULTI_TOUCH_TYPE_BEGIN
) {
647 slot
->tracking_id
= num_slot
;
650 for (i
= 0; i
< INPUT_EVENT_SLOTS_MAX
; ++i
) {
654 update
= INPUT_MULTI_TOUCH_TYPE_UPDATE
;
657 slot
= &touch_slots
[i
];
659 if (slot
->tracking_id
== -1) {
663 if (update
== INPUT_MULTI_TOUCH_TYPE_END
) {
664 slot
->tracking_id
= -1;
665 qemu_input_queue_mtt(con
, update
, i
, slot
->tracking_id
);
668 qemu_input_queue_mtt(con
, update
, i
, slot
->tracking_id
);
669 qemu_input_queue_btn(con
, INPUT_BUTTON_TOUCH
, true);
670 qemu_input_queue_mtt_abs(con
,
671 INPUT_AXIS_X
, (int) slot
->x
,
673 i
, slot
->tracking_id
);
674 qemu_input_queue_mtt_abs(con
,
675 INPUT_AXIS_Y
, (int) slot
->y
,
677 i
, slot
->tracking_id
);
683 qemu_input_event_sync();
687 void qemu_console_set_display_gl_ctx(QemuConsole
*con
, DisplayGLCtx
*gl
)
689 /* display has opengl support */
692 error_report("The console already has an OpenGL context.");
699 dcl_set_graphic_cursor(DisplayChangeListener
*dcl
, QemuGraphicConsole
*con
)
701 if (con
&& con
->cursor
&& dcl
->ops
->dpy_cursor_define
) {
702 dcl
->ops
->dpy_cursor_define(dcl
, con
->cursor
);
704 if (con
&& dcl
->ops
->dpy_mouse_set
) {
705 dcl
->ops
->dpy_mouse_set(dcl
, con
->cursor_x
, con
->cursor_y
, con
->cursor_on
);
709 void register_displaychangelistener(DisplayChangeListener
*dcl
)
713 trace_displaychangelistener_register(dcl
, dcl
->ops
->dpy_name
);
714 dcl
->ds
= get_alloc_displaystate();
715 QLIST_INSERT_HEAD(&dcl
->ds
->listeners
, dcl
, next
);
716 gui_setup_refresh(dcl
->ds
);
720 displaychangelistener_display_console(dcl
, &error_fatal
);
721 if (QEMU_IS_GRAPHIC_CONSOLE(dcl
->con
)) {
722 dcl_set_graphic_cursor(dcl
, QEMU_GRAPHIC_CONSOLE(dcl
->con
));
723 } else if (QEMU_IS_TEXT_CONSOLE(dcl
->con
)) {
724 qemu_text_console_update_size(QEMU_TEXT_CONSOLE(dcl
->con
));
726 qemu_text_console_update_cursor();
729 void update_displaychangelistener(DisplayChangeListener
*dcl
,
732 DisplayState
*ds
= dcl
->ds
;
734 dcl
->update_interval
= interval
;
735 if (!ds
->refreshing
&& ds
->update_interval
> interval
) {
736 timer_mod(ds
->gui_timer
, ds
->last_update
+ interval
);
740 void unregister_displaychangelistener(DisplayChangeListener
*dcl
)
742 DisplayState
*ds
= dcl
->ds
;
743 trace_displaychangelistener_unregister(dcl
, dcl
->ops
->dpy_name
);
747 QLIST_REMOVE(dcl
, next
);
749 gui_setup_refresh(ds
);
752 static void dpy_set_ui_info_timer(void *opaque
)
754 QemuConsole
*con
= opaque
;
755 uint32_t head
= qemu_console_get_head(con
);
757 con
->hw_ops
->ui_info(con
->hw
, head
, &con
->ui_info
);
760 bool dpy_ui_info_supported(const QemuConsole
*con
)
766 return con
->hw_ops
->ui_info
!= NULL
;
769 const QemuUIInfo
*dpy_get_ui_info(const QemuConsole
*con
)
771 assert(dpy_ui_info_supported(con
));
773 return &con
->ui_info
;
776 int dpy_set_ui_info(QemuConsole
*con
, QemuUIInfo
*info
, bool delay
)
778 if (!dpy_ui_info_supported(con
)) {
781 if (memcmp(&con
->ui_info
, info
, sizeof(con
->ui_info
)) == 0) {
782 /* nothing changed -- ignore */
787 * Typically we get a flood of these as the user resizes the window.
788 * Wait until the dust has settled (one second without updates), then
789 * go notify the guest.
791 con
->ui_info
= *info
;
792 timer_mod(con
->ui_timer
,
793 qemu_clock_get_ms(QEMU_CLOCK_REALTIME
) + (delay
? 1000 : 0));
797 void dpy_gfx_update(QemuConsole
*con
, int x
, int y
, int w
, int h
)
799 DisplayState
*s
= con
->ds
;
800 DisplayChangeListener
*dcl
;
801 int width
= qemu_console_get_width(con
, x
+ w
);
802 int height
= qemu_console_get_height(con
, y
+ h
);
808 w
= MIN(w
, width
- x
);
809 h
= MIN(h
, height
- y
);
811 if (!qemu_console_is_visible(con
)) {
814 dpy_gfx_update_texture(con
, con
->surface
, x
, y
, w
, h
);
815 QLIST_FOREACH(dcl
, &s
->listeners
, next
) {
816 if (con
!= dcl
->con
) {
819 if (dcl
->ops
->dpy_gfx_update
) {
820 dcl
->ops
->dpy_gfx_update(dcl
, x
, y
, w
, h
);
825 void dpy_gfx_update_full(QemuConsole
*con
)
827 int w
= qemu_console_get_width(con
, 0);
828 int h
= qemu_console_get_height(con
, 0);
830 dpy_gfx_update(con
, 0, 0, w
, h
);
833 void dpy_gfx_replace_surface(QemuConsole
*con
,
834 DisplaySurface
*surface
)
836 static const char placeholder_msg
[] = "Display output is not active.";
837 DisplayState
*s
= con
->ds
;
838 DisplaySurface
*old_surface
= con
->surface
;
839 DisplaySurface
*new_surface
= surface
;
840 DisplayChangeListener
*dcl
;
846 width
= surface_width(old_surface
);
847 height
= surface_height(old_surface
);
853 new_surface
= qemu_create_placeholder_surface(width
, height
, placeholder_msg
);
856 assert(old_surface
!= new_surface
);
858 con
->scanout
.kind
= SCANOUT_SURFACE
;
859 con
->surface
= new_surface
;
860 dpy_gfx_create_texture(con
, new_surface
);
861 QLIST_FOREACH(dcl
, &s
->listeners
, next
) {
862 if (con
!= dcl
->con
) {
865 displaychangelistener_gfx_switch(dcl
, new_surface
, surface
? FALSE
: TRUE
);
867 dpy_gfx_destroy_texture(con
, old_surface
);
868 qemu_free_displaysurface(old_surface
);
871 bool dpy_gfx_check_format(QemuConsole
*con
,
872 pixman_format_code_t format
)
874 DisplayChangeListener
*dcl
;
875 DisplayState
*s
= con
->ds
;
877 QLIST_FOREACH(dcl
, &s
->listeners
, next
) {
878 if (dcl
->con
&& dcl
->con
!= con
) {
879 /* dcl bound to another console -> skip */
882 if (dcl
->ops
->dpy_gfx_check_format
) {
883 if (!dcl
->ops
->dpy_gfx_check_format(dcl
, format
)) {
887 /* default is to allow native 32 bpp only */
888 if (format
!= qemu_default_pixman_format(32, true)) {
896 static void dpy_refresh(DisplayState
*s
)
898 DisplayChangeListener
*dcl
;
900 QLIST_FOREACH(dcl
, &s
->listeners
, next
) {
901 if (dcl
->ops
->dpy_refresh
) {
902 dcl
->ops
->dpy_refresh(dcl
);
907 void dpy_text_cursor(QemuConsole
*con
, int x
, int y
)
909 DisplayState
*s
= con
->ds
;
910 DisplayChangeListener
*dcl
;
912 if (!qemu_console_is_visible(con
)) {
915 QLIST_FOREACH(dcl
, &s
->listeners
, next
) {
916 if (con
!= dcl
->con
) {
919 if (dcl
->ops
->dpy_text_cursor
) {
920 dcl
->ops
->dpy_text_cursor(dcl
, x
, y
);
925 void dpy_text_update(QemuConsole
*con
, int x
, int y
, int w
, int h
)
927 DisplayState
*s
= con
->ds
;
928 DisplayChangeListener
*dcl
;
930 if (!qemu_console_is_visible(con
)) {
933 QLIST_FOREACH(dcl
, &s
->listeners
, next
) {
934 if (con
!= dcl
->con
) {
937 if (dcl
->ops
->dpy_text_update
) {
938 dcl
->ops
->dpy_text_update(dcl
, x
, y
, w
, h
);
943 void dpy_text_resize(QemuConsole
*con
, int w
, int h
)
945 DisplayState
*s
= con
->ds
;
946 DisplayChangeListener
*dcl
;
948 if (!qemu_console_is_visible(con
)) {
951 QLIST_FOREACH(dcl
, &s
->listeners
, next
) {
952 if (con
!= dcl
->con
) {
955 if (dcl
->ops
->dpy_text_resize
) {
956 dcl
->ops
->dpy_text_resize(dcl
, w
, h
);
961 void dpy_mouse_set(QemuConsole
*c
, int x
, int y
, bool on
)
963 QemuGraphicConsole
*con
= QEMU_GRAPHIC_CONSOLE(c
);
964 DisplayState
*s
= c
->ds
;
965 DisplayChangeListener
*dcl
;
970 if (!qemu_console_is_visible(c
)) {
973 QLIST_FOREACH(dcl
, &s
->listeners
, next
) {
977 if (dcl
->ops
->dpy_mouse_set
) {
978 dcl
->ops
->dpy_mouse_set(dcl
, x
, y
, on
);
983 void dpy_cursor_define(QemuConsole
*c
, QEMUCursor
*cursor
)
985 QemuGraphicConsole
*con
= QEMU_GRAPHIC_CONSOLE(c
);
986 DisplayState
*s
= c
->ds
;
987 DisplayChangeListener
*dcl
;
989 cursor_unref(con
->cursor
);
990 con
->cursor
= cursor_ref(cursor
);
991 if (!qemu_console_is_visible(c
)) {
994 QLIST_FOREACH(dcl
, &s
->listeners
, next
) {
998 if (dcl
->ops
->dpy_cursor_define
) {
999 dcl
->ops
->dpy_cursor_define(dcl
, cursor
);
1004 QEMUGLContext
dpy_gl_ctx_create(QemuConsole
*con
,
1005 struct QEMUGLParams
*qparams
)
1008 return con
->gl
->ops
->dpy_gl_ctx_create(con
->gl
, qparams
);
1011 void dpy_gl_ctx_destroy(QemuConsole
*con
, QEMUGLContext ctx
)
1014 con
->gl
->ops
->dpy_gl_ctx_destroy(con
->gl
, ctx
);
1017 int dpy_gl_ctx_make_current(QemuConsole
*con
, QEMUGLContext ctx
)
1020 return con
->gl
->ops
->dpy_gl_ctx_make_current(con
->gl
, ctx
);
1023 void dpy_gl_scanout_disable(QemuConsole
*con
)
1025 DisplayState
*s
= con
->ds
;
1026 DisplayChangeListener
*dcl
;
1028 if (con
->scanout
.kind
!= SCANOUT_SURFACE
) {
1029 con
->scanout
.kind
= SCANOUT_NONE
;
1031 QLIST_FOREACH(dcl
, &s
->listeners
, next
) {
1032 if (con
!= dcl
->con
) {
1035 if (dcl
->ops
->dpy_gl_scanout_disable
) {
1036 dcl
->ops
->dpy_gl_scanout_disable(dcl
);
1041 void dpy_gl_scanout_texture(QemuConsole
*con
,
1042 uint32_t backing_id
,
1043 bool backing_y_0_top
,
1044 uint32_t backing_width
,
1045 uint32_t backing_height
,
1046 uint32_t x
, uint32_t y
,
1047 uint32_t width
, uint32_t height
,
1050 DisplayState
*s
= con
->ds
;
1051 DisplayChangeListener
*dcl
;
1053 con
->scanout
.kind
= SCANOUT_TEXTURE
;
1054 con
->scanout
.texture
= (ScanoutTexture
) {
1055 backing_id
, backing_y_0_top
, backing_width
, backing_height
,
1056 x
, y
, width
, height
, d3d_tex2d
,
1058 QLIST_FOREACH(dcl
, &s
->listeners
, next
) {
1059 if (con
!= dcl
->con
) {
1062 if (dcl
->ops
->dpy_gl_scanout_texture
) {
1063 dcl
->ops
->dpy_gl_scanout_texture(dcl
, backing_id
,
1065 backing_width
, backing_height
,
1066 x
, y
, width
, height
,
1072 void dpy_gl_scanout_dmabuf(QemuConsole
*con
,
1075 DisplayState
*s
= con
->ds
;
1076 DisplayChangeListener
*dcl
;
1078 con
->scanout
.kind
= SCANOUT_DMABUF
;
1079 con
->scanout
.dmabuf
= dmabuf
;
1080 QLIST_FOREACH(dcl
, &s
->listeners
, next
) {
1081 if (con
!= dcl
->con
) {
1084 if (dcl
->ops
->dpy_gl_scanout_dmabuf
) {
1085 dcl
->ops
->dpy_gl_scanout_dmabuf(dcl
, dmabuf
);
1090 void dpy_gl_cursor_dmabuf(QemuConsole
*con
, QemuDmaBuf
*dmabuf
,
1091 bool have_hot
, uint32_t hot_x
, uint32_t hot_y
)
1093 DisplayState
*s
= con
->ds
;
1094 DisplayChangeListener
*dcl
;
1096 QLIST_FOREACH(dcl
, &s
->listeners
, next
) {
1097 if (con
!= dcl
->con
) {
1100 if (dcl
->ops
->dpy_gl_cursor_dmabuf
) {
1101 dcl
->ops
->dpy_gl_cursor_dmabuf(dcl
, dmabuf
,
1102 have_hot
, hot_x
, hot_y
);
1107 void dpy_gl_cursor_position(QemuConsole
*con
,
1108 uint32_t pos_x
, uint32_t pos_y
)
1110 DisplayState
*s
= con
->ds
;
1111 DisplayChangeListener
*dcl
;
1113 QLIST_FOREACH(dcl
, &s
->listeners
, next
) {
1114 if (con
!= dcl
->con
) {
1117 if (dcl
->ops
->dpy_gl_cursor_position
) {
1118 dcl
->ops
->dpy_gl_cursor_position(dcl
, pos_x
, pos_y
);
1123 void dpy_gl_release_dmabuf(QemuConsole
*con
,
1126 DisplayState
*s
= con
->ds
;
1127 DisplayChangeListener
*dcl
;
1129 QLIST_FOREACH(dcl
, &s
->listeners
, next
) {
1130 if (con
!= dcl
->con
) {
1133 if (dcl
->ops
->dpy_gl_release_dmabuf
) {
1134 dcl
->ops
->dpy_gl_release_dmabuf(dcl
, dmabuf
);
1139 void dpy_gl_update(QemuConsole
*con
,
1140 uint32_t x
, uint32_t y
, uint32_t w
, uint32_t h
)
1142 DisplayState
*s
= con
->ds
;
1143 DisplayChangeListener
*dcl
;
1147 graphic_hw_gl_block(con
, true);
1148 QLIST_FOREACH(dcl
, &s
->listeners
, next
) {
1149 if (con
!= dcl
->con
) {
1152 if (dcl
->ops
->dpy_gl_update
) {
1153 dcl
->ops
->dpy_gl_update(dcl
, x
, y
, w
, h
);
1156 graphic_hw_gl_block(con
, false);
1159 /***********************************************************/
1160 /* register display */
1162 /* console.c internal use only */
1163 static DisplayState
*get_alloc_displaystate(void)
1165 if (!display_state
) {
1166 display_state
= g_new0(DisplayState
, 1);
1168 return display_state
;
1172 * Called by main(), after creating QemuConsoles
1173 * and before initializing ui (sdl/vnc/...).
1175 DisplayState
*init_displaystate(void)
1180 QTAILQ_FOREACH(con
, &consoles
, next
) {
1181 /* Hook up into the qom tree here (not in object_new()), once
1182 * all QemuConsoles are created and the order / numbering
1183 * doesn't change any more */
1184 name
= g_strdup_printf("console[%d]", con
->index
);
1185 object_property_add_child(container_get(object_get_root(), "/backend"),
1190 return display_state
;
1193 void graphic_console_set_hwops(QemuConsole
*con
,
1194 const GraphicHwOps
*hw_ops
,
1197 con
->hw_ops
= hw_ops
;
1201 QemuConsole
*graphic_console_init(DeviceState
*dev
, uint32_t head
,
1202 const GraphicHwOps
*hw_ops
,
1205 static const char noinit
[] =
1206 "Guest has not initialized the display (yet).";
1210 DisplaySurface
*surface
;
1212 s
= qemu_graphic_console_lookup_unused();
1214 trace_console_gfx_reuse(s
->index
);
1215 width
= qemu_console_get_width(s
, 0);
1216 height
= qemu_console_get_height(s
, 0);
1218 trace_console_gfx_new();
1219 s
= (QemuConsole
*)object_new(TYPE_QEMU_GRAPHIC_CONSOLE
);
1221 QEMU_GRAPHIC_CONSOLE(s
)->head
= head
;
1222 graphic_console_set_hwops(s
, hw_ops
, opaque
);
1224 object_property_set_link(OBJECT(s
), "device", OBJECT(dev
),
1228 surface
= qemu_create_placeholder_surface(width
, height
, noinit
);
1229 dpy_gfx_replace_surface(s
, surface
);
1230 s
->gl_unblock_timer
= timer_new_ms(QEMU_CLOCK_REALTIME
,
1231 graphic_hw_gl_unblock_timer
, s
);
1235 static const GraphicHwOps unused_ops
= {
1239 void graphic_console_close(QemuConsole
*con
)
1241 static const char unplugged
[] =
1242 "Guest display has been unplugged";
1243 DisplaySurface
*surface
;
1244 int width
= qemu_console_get_width(con
, 640);
1245 int height
= qemu_console_get_height(con
, 480);
1247 trace_console_gfx_close(con
->index
);
1248 object_property_set_link(OBJECT(con
), "device", NULL
, &error_abort
);
1249 graphic_console_set_hwops(con
, &unused_ops
, NULL
);
1252 dpy_gl_scanout_disable(con
);
1254 surface
= qemu_create_placeholder_surface(width
, height
, unplugged
);
1255 dpy_gfx_replace_surface(con
, surface
);
1258 QemuConsole
*qemu_console_lookup_default(void)
1262 QTAILQ_FOREACH(con
, &consoles
, next
) {
1263 if (QEMU_IS_GRAPHIC_CONSOLE(con
)) {
1267 return QTAILQ_FIRST(&consoles
);
1270 QemuConsole
*qemu_console_lookup_by_index(unsigned int index
)
1274 QTAILQ_FOREACH(con
, &consoles
, next
) {
1275 if (con
->index
== index
) {
1282 QemuConsole
*qemu_console_lookup_by_device(DeviceState
*dev
, uint32_t head
)
1288 QTAILQ_FOREACH(con
, &consoles
, next
) {
1289 obj
= object_property_get_link(OBJECT(con
),
1290 "device", &error_abort
);
1291 if (DEVICE(obj
) != dev
) {
1294 h
= object_property_get_uint(OBJECT(con
),
1295 "head", &error_abort
);
1304 QemuConsole
*qemu_console_lookup_by_device_name(const char *device_id
,
1305 uint32_t head
, Error
**errp
)
1310 dev
= qdev_find_recursive(sysbus_get_default(), device_id
);
1312 error_set(errp
, ERROR_CLASS_DEVICE_NOT_FOUND
,
1313 "Device '%s' not found", device_id
);
1317 con
= qemu_console_lookup_by_device(dev
, head
);
1319 error_setg(errp
, "Device %s (head %d) is not bound to a QemuConsole",
1327 static QemuConsole
*qemu_graphic_console_lookup_unused(void)
1332 QTAILQ_FOREACH(con
, &consoles
, next
) {
1333 if (!QEMU_IS_GRAPHIC_CONSOLE(con
) || con
->hw_ops
!= &unused_ops
) {
1336 obj
= object_property_get_link(OBJECT(con
),
1337 "device", &error_abort
);
1346 QEMUCursor
*qemu_console_get_cursor(QemuConsole
*con
)
1348 return QEMU_IS_GRAPHIC_CONSOLE(con
) ? QEMU_GRAPHIC_CONSOLE(con
)->cursor
: NULL
;
1351 bool qemu_console_is_visible(QemuConsole
*con
)
1353 return con
->dcls
> 0;
1356 bool qemu_console_is_graphic(QemuConsole
*con
)
1358 return con
&& QEMU_IS_GRAPHIC_CONSOLE(con
);
1361 bool qemu_console_is_fixedsize(QemuConsole
*con
)
1363 return con
&& (QEMU_IS_GRAPHIC_CONSOLE(con
) || QEMU_IS_FIXED_TEXT_CONSOLE(con
));
1366 bool qemu_console_is_gl_blocked(QemuConsole
*con
)
1368 assert(con
!= NULL
);
1369 return con
->gl_block
;
1372 static bool qemu_graphic_console_is_multihead(QemuGraphicConsole
*c
)
1376 QTAILQ_FOREACH(con
, &consoles
, next
) {
1377 QemuGraphicConsole
*candidate
;
1379 if (!QEMU_IS_GRAPHIC_CONSOLE(con
)) {
1383 candidate
= QEMU_GRAPHIC_CONSOLE(con
);
1384 if (candidate
->device
!= c
->device
) {
1388 if (candidate
->head
!= c
->head
) {
1395 char *qemu_console_get_label(QemuConsole
*con
)
1397 if (QEMU_IS_GRAPHIC_CONSOLE(con
)) {
1398 QemuGraphicConsole
*c
= QEMU_GRAPHIC_CONSOLE(con
);
1403 dev
= DEVICE(c
->device
);
1404 multihead
= qemu_graphic_console_is_multihead(c
);
1406 return g_strdup_printf("%s.%d", dev
->id
?
1408 object_get_typename(c
->device
),
1411 return g_strdup_printf("%s", dev
->id
?
1413 object_get_typename(c
->device
));
1416 return g_strdup("VGA");
1417 } else if (QEMU_IS_TEXT_CONSOLE(con
)) {
1418 const char *label
= qemu_text_console_get_label(QEMU_TEXT_CONSOLE(con
));
1420 return g_strdup(label
);
1424 return g_strdup_printf("vc%d", con
->index
);
1427 int qemu_console_get_index(QemuConsole
*con
)
1429 return con
? con
->index
: -1;
1432 uint32_t qemu_console_get_head(QemuConsole
*con
)
1437 if (QEMU_IS_GRAPHIC_CONSOLE(con
)) {
1438 return QEMU_GRAPHIC_CONSOLE(con
)->head
;
1443 int qemu_console_get_width(QemuConsole
*con
, int fallback
)
1448 switch (con
->scanout
.kind
) {
1449 case SCANOUT_DMABUF
:
1450 return qemu_dmabuf_get_width(con
->scanout
.dmabuf
);
1451 case SCANOUT_TEXTURE
:
1452 return con
->scanout
.texture
.width
;
1453 case SCANOUT_SURFACE
:
1454 return surface_width(con
->surface
);
1460 int qemu_console_get_height(QemuConsole
*con
, int fallback
)
1465 switch (con
->scanout
.kind
) {
1466 case SCANOUT_DMABUF
:
1467 return qemu_dmabuf_get_height(con
->scanout
.dmabuf
);
1468 case SCANOUT_TEXTURE
:
1469 return con
->scanout
.texture
.height
;
1470 case SCANOUT_SURFACE
:
1471 return surface_height(con
->surface
);
1477 int qemu_invalidate_text_consoles(void)
1482 QTAILQ_FOREACH(s
, &consoles
, next
) {
1483 if (qemu_console_is_graphic(s
) ||
1484 !qemu_console_is_visible(s
)) {
1488 graphic_hw_invalidate(s
);
1494 void qemu_console_resize(QemuConsole
*s
, int width
, int height
)
1496 DisplaySurface
*surface
= qemu_console_surface(s
);
1498 assert(QEMU_IS_GRAPHIC_CONSOLE(s
));
1500 if ((s
->scanout
.kind
!= SCANOUT_SURFACE
||
1501 (surface
&& surface_is_allocated(surface
) &&
1502 !surface_is_placeholder(surface
))) &&
1503 qemu_console_get_width(s
, -1) == width
&&
1504 qemu_console_get_height(s
, -1) == height
) {
1508 surface
= qemu_create_displaysurface(width
, height
);
1509 dpy_gfx_replace_surface(s
, surface
);
1512 DisplaySurface
*qemu_console_surface(QemuConsole
*console
)
1514 switch (console
->scanout
.kind
) {
1515 case SCANOUT_SURFACE
:
1516 return console
->surface
;
1522 PixelFormat
qemu_default_pixelformat(int bpp
)
1524 pixman_format_code_t fmt
= qemu_default_pixman_format(bpp
, true);
1525 PixelFormat pf
= qemu_pixelformat_from_pixman(fmt
);
1529 static QemuDisplay
*dpys
[DISPLAY_TYPE__MAX
];
1531 void qemu_display_register(QemuDisplay
*ui
)
1533 assert(ui
->type
< DISPLAY_TYPE__MAX
);
1534 dpys
[ui
->type
] = ui
;
1537 bool qemu_display_find_default(DisplayOptions
*opts
)
1539 static DisplayType prio
[] = {
1540 #if defined(CONFIG_GTK)
1543 #if defined(CONFIG_SDL)
1546 #if defined(CONFIG_COCOA)
1552 for (i
= 0; i
< (int)ARRAY_SIZE(prio
); i
++) {
1553 if (dpys
[prio
[i
]] == NULL
) {
1554 Error
*local_err
= NULL
;
1555 int rv
= ui_module_load(DisplayType_str(prio
[i
]), &local_err
);
1557 error_report_err(local_err
);
1560 if (dpys
[prio
[i
]] == NULL
) {
1563 opts
->type
= prio
[i
];
1569 void qemu_display_early_init(DisplayOptions
*opts
)
1571 assert(opts
->type
< DISPLAY_TYPE__MAX
);
1572 if (opts
->type
== DISPLAY_TYPE_NONE
) {
1575 if (dpys
[opts
->type
] == NULL
) {
1576 Error
*local_err
= NULL
;
1577 int rv
= ui_module_load(DisplayType_str(opts
->type
), &local_err
);
1579 error_report_err(local_err
);
1582 if (dpys
[opts
->type
] == NULL
) {
1583 error_report("Display '%s' is not available.",
1584 DisplayType_str(opts
->type
));
1587 if (dpys
[opts
->type
]->early_init
) {
1588 dpys
[opts
->type
]->early_init(opts
);
1592 void qemu_display_init(DisplayState
*ds
, DisplayOptions
*opts
)
1594 assert(opts
->type
< DISPLAY_TYPE__MAX
);
1595 if (opts
->type
== DISPLAY_TYPE_NONE
) {
1598 assert(dpys
[opts
->type
] != NULL
);
1599 dpys
[opts
->type
]->init(ds
, opts
);
1602 const char *qemu_display_get_vc(DisplayOptions
*opts
)
1604 #ifdef CONFIG_PIXMAN
1605 const char *vc
= "vc:80Cx24C";
1607 const char *vc
= NULL
;
1610 assert(opts
->type
< DISPLAY_TYPE__MAX
);
1611 if (dpys
[opts
->type
] && dpys
[opts
->type
]->vc
) {
1612 vc
= dpys
[opts
->type
]->vc
;
1617 void qemu_display_help(void)
1621 printf("Available display backend types:\n");
1623 for (idx
= DISPLAY_TYPE_NONE
; idx
< DISPLAY_TYPE__MAX
; idx
++) {
1625 Error
*local_err
= NULL
;
1626 int rv
= ui_module_load(DisplayType_str(idx
), &local_err
);
1628 error_report_err(local_err
);
1632 printf("%s\n", DisplayType_str(dpys
[idx
]->type
));
1636 "Some display backends support suboptions, which can be set with\n"
1637 " -display backend,option=value,option=value...\n"
1638 "For a short list of the suboptions for each display, see the "
1639 "top-level -help output; more detail is in the documentation.\n");