docs/system/s390x/3270.rst | 43 ++++++++++++++++++++++++++++++++------ 1 file changed, 37 insertions(+), 6 deletions(-)
There is some additional information about the 3270 support in our
Wiki at https://wiki.qemu.org/Features/3270 - so let's include this
information into the main documentation now to have one single
source of information (the Wiki page could later be removed).
Signed-off-by: Thomas Huth <thuth@redhat.com>
---
docs/system/s390x/3270.rst | 43 ++++++++++++++++++++++++++++++++------
1 file changed, 37 insertions(+), 6 deletions(-)
diff --git a/docs/system/s390x/3270.rst b/docs/system/s390x/3270.rst
index 1774cdcadf..80350264d7 100644
--- a/docs/system/s390x/3270.rst
+++ b/docs/system/s390x/3270.rst
@@ -1,9 +1,15 @@
3270 devices
============
-QEMU supports connecting an external 3270 terminal emulator (such as
-``x3270``) to make a single 3270 device available to a guest. Note that this
-supports basic features only.
+The 3270 is the classic 'green-screen' console of the mainframes (see the
+`IBM 3270 Wikipedia article <https://en.wikipedia.org/wiki/IBM_3270>`__).
+
+The 3270 data stream is not implemented within QEMU; the device only provides
+TN3270 (a telnet extension; see `RFC 854 <https://tools.ietf.org/html/rfc854>`__
+and `RFC 1576 <https://tools.ietf.org/html/rfc1576>`__) and leaves the heavy
+lifting to an external 3270 terminal emulator (such as ``x3270``) to make a
+single 3270 device available to a guest. Note that this supports basic
+features only.
To provide a 3270 device to a guest, create a ``x-terminal3270`` linked to
a ``tn3270`` chardev. The guest will see a 3270 channel device. In order
@@ -12,10 +18,14 @@ to actually be able to use it, attach the ``x3270`` emulator to the chardev.
Example configuration
---------------------
+* Make sure that 3270 support is enabled in the guest's kernel. You need
+ ``CONFIG_TN3270`` and at least one of ``CONFIG_TN3270_TTY`` (for additional
+ ttys) or ``CONFIG_TN3270_CONSOLE`` (for a 3270 console).
+
* Add a ``tn3270`` chardev and a ``x-terminal3270`` to the QEMU command line::
- -chardev socket,id=char_0,host=0.0.0.0,port=2300,nowait,server,tn3270
- -device x-terminal3270,chardev=char_0,devno=fe.0.000a,id=terminal_0
+ -chardev socket,id=ch0,host=0.0.0.0,port=2300,nowait,server,tn3270
+ -device x-terminal3270,chardev=ch0,devno=fe.0.000a,id=terminal0
* Start the guest. In the guest, use ``chccwdev -e 0.0.000a`` to enable
the device.
@@ -29,4 +39,25 @@ Example configuration
systemctl start serial-getty@3270-tty1.service
-This should get you an addtional tty for logging into the guest.
+ This should get you an addtional tty for logging into the guest.
+
+* If you want to use the 3270 device as the kernel console instead of an
+ additional tty, you can also append ``conmode=3270 condev=000a`` to the
+ guest's kernel command line. The kernel then should use the 3270 as
+ console after the next boot.
+
+Restrictions
+------------
+
+3270 support is still experimental. In particular:
+
+* Only one 3270 device is supported.
+
+* It has only been tested with Linux guests and the x3270 emulator.
+
+* TLS/SSL is not yet supported.
+
+* Resizing on reattach is not yet supported.
+
+* Multiple commands in one inbound buffer (for example, when the reset key
+ is pressed while the network is slow) are not yet supported.
--
2.18.1
On Thu, 9 Jul 2020 18:04:39 +0200 Thomas Huth <thuth@redhat.com> wrote: > There is some additional information about the 3270 support in our > Wiki at https://wiki.qemu.org/Features/3270 - so let's include this > information into the main documentation now to have one single > source of information (the Wiki page could later be removed). No objection; but what should our general policy with regard to wiki pages vs. documentation be? The 3270 support is pretty much static, but e.g. for vfio-ccw, we use the wiki page as a place where we track things that should be worked on etc. (Related: What is the scope of our QEMU documentation? Is a libvirt XML snippet on topic? Kernel configuration options (as in here)?) > > Signed-off-by: Thomas Huth <thuth@redhat.com> > --- > docs/system/s390x/3270.rst | 43 ++++++++++++++++++++++++++++++++------ > 1 file changed, 37 insertions(+), 6 deletions(-) > > diff --git a/docs/system/s390x/3270.rst b/docs/system/s390x/3270.rst > index 1774cdcadf..80350264d7 100644 > --- a/docs/system/s390x/3270.rst > +++ b/docs/system/s390x/3270.rst > @@ -1,9 +1,15 @@ > 3270 devices > ============ > > -QEMU supports connecting an external 3270 terminal emulator (such as > -``x3270``) to make a single 3270 device available to a guest. Note that this > -supports basic features only. > +The 3270 is the classic 'green-screen' console of the mainframes (see the > +`IBM 3270 Wikipedia article <https://en.wikipedia.org/wiki/IBM_3270>`__). > + > +The 3270 data stream is not implemented within QEMU; the device only provides > +TN3270 (a telnet extension; see `RFC 854 <https://tools.ietf.org/html/rfc854>`__ > +and `RFC 1576 <https://tools.ietf.org/html/rfc1576>`__) and leaves the heavy > +lifting to an external 3270 terminal emulator (such as ``x3270``) to make a > +single 3270 device available to a guest. Note that this supports basic > +features only. > > To provide a 3270 device to a guest, create a ``x-terminal3270`` linked to > a ``tn3270`` chardev. The guest will see a 3270 channel device. In order > @@ -12,10 +18,14 @@ to actually be able to use it, attach the ``x3270`` emulator to the chardev. > Example configuration > --------------------- > > +* Make sure that 3270 support is enabled in the guest's kernel. You need > + ``CONFIG_TN3270`` and at least one of ``CONFIG_TN3270_TTY`` (for additional > + ttys) or ``CONFIG_TN3270_CONSOLE`` (for a 3270 console). > + > * Add a ``tn3270`` chardev and a ``x-terminal3270`` to the QEMU command line:: > > - -chardev socket,id=char_0,host=0.0.0.0,port=2300,nowait,server,tn3270 > - -device x-terminal3270,chardev=char_0,devno=fe.0.000a,id=terminal_0 > + -chardev socket,id=ch0,host=0.0.0.0,port=2300,nowait,server,tn3270 > + -device x-terminal3270,chardev=ch0,devno=fe.0.000a,id=terminal0 Any reason why you changed this? > > * Start the guest. In the guest, use ``chccwdev -e 0.0.000a`` to enable > the device. > @@ -29,4 +39,25 @@ Example configuration > > systemctl start serial-getty@3270-tty1.service > > -This should get you an addtional tty for logging into the guest. > + This should get you an addtional tty for logging into the guest. > + > +* If you want to use the 3270 device as the kernel console instead of an > + additional tty, you can also append ``conmode=3270 condev=000a`` to the > + guest's kernel command line. The kernel then should use the 3270 as > + console after the next boot. > + > +Restrictions > +------------ > + > +3270 support is still experimental. In particular: s/still experimental/very basic/ I don't think there's much progress on the horizon; let's not give people false hope :) > + > +* Only one 3270 device is supported. > + > +* It has only been tested with Linux guests and the x3270 emulator. > + > +* TLS/SSL is not yet supported. s/yet // > + > +* Resizing on reattach is not yet supported. s/yet // > + > +* Multiple commands in one inbound buffer (for example, when the reset key > + is pressed while the network is slow) are not yet supported. s/yet //
On 10/07/2020 12.55, Cornelia Huck wrote: > On Thu, 9 Jul 2020 18:04:39 +0200 > Thomas Huth <thuth@redhat.com> wrote: > >> There is some additional information about the 3270 support in our >> Wiki at https://wiki.qemu.org/Features/3270 - so let's include this >> information into the main documentation now to have one single >> source of information (the Wiki page could later be removed). > > No objection; but what should our general policy with regard to wiki > pages vs. documentation be? The 3270 support is pretty much static, but > e.g. for vfio-ccw, we use the wiki page as a place where we track > things that should be worked on etc. I think that docs which are "done" should go into the git repo. If they are rather still work-in-progress and change very often, or relate to a feature that has not been merged yet, the wiki is likely the better place. > (Related: What is the scope of our QEMU documentation? Is a libvirt XML > snippet on topic? Kernel configuration options (as in here)?) As long as the focus is still on QEMU, I think it is fine. If the information is only about libvirt or the kernel, that documentation should maybe rather be added to libvirt.org or linux-kvm.org instead. >> Signed-off-by: Thomas Huth <thuth@redhat.com> >> --- >> docs/system/s390x/3270.rst | 43 ++++++++++++++++++++++++++++++++------ >> 1 file changed, 37 insertions(+), 6 deletions(-) >> >> diff --git a/docs/system/s390x/3270.rst b/docs/system/s390x/3270.rst >> index 1774cdcadf..80350264d7 100644 >> --- a/docs/system/s390x/3270.rst >> +++ b/docs/system/s390x/3270.rst >> @@ -1,9 +1,15 @@ >> 3270 devices >> ============ >> >> -QEMU supports connecting an external 3270 terminal emulator (such as >> -``x3270``) to make a single 3270 device available to a guest. Note that this >> -supports basic features only. >> +The 3270 is the classic 'green-screen' console of the mainframes (see the >> +`IBM 3270 Wikipedia article <https://en.wikipedia.org/wiki/IBM_3270>`__). >> + >> +The 3270 data stream is not implemented within QEMU; the device only provides >> +TN3270 (a telnet extension; see `RFC 854 <https://tools.ietf.org/html/rfc854>`__ >> +and `RFC 1576 <https://tools.ietf.org/html/rfc1576>`__) and leaves the heavy >> +lifting to an external 3270 terminal emulator (such as ``x3270``) to make a >> +single 3270 device available to a guest. Note that this supports basic >> +features only. >> >> To provide a 3270 device to a guest, create a ``x-terminal3270`` linked to >> a ``tn3270`` chardev. The guest will see a 3270 channel device. In order >> @@ -12,10 +18,14 @@ to actually be able to use it, attach the ``x3270`` emulator to the chardev. >> Example configuration >> --------------------- >> >> +* Make sure that 3270 support is enabled in the guest's kernel. You need >> + ``CONFIG_TN3270`` and at least one of ``CONFIG_TN3270_TTY`` (for additional >> + ttys) or ``CONFIG_TN3270_CONSOLE`` (for a 3270 console). >> + >> * Add a ``tn3270`` chardev and a ``x-terminal3270`` to the QEMU command line:: >> >> - -chardev socket,id=char_0,host=0.0.0.0,port=2300,nowait,server,tn3270 >> - -device x-terminal3270,chardev=char_0,devno=fe.0.000a,id=terminal_0 >> + -chardev socket,id=ch0,host=0.0.0.0,port=2300,nowait,server,tn3270 >> + -device x-terminal3270,chardev=ch0,devno=fe.0.000a,id=terminal0 > > Any reason why you changed this? The lines were too long - Firefox displayed this example with a horizontal scrollbar, even if I resized the browser window large enough. With my change, it shows up nicely without scrollbar. >> >> * Start the guest. In the guest, use ``chccwdev -e 0.0.000a`` to enable >> the device. >> @@ -29,4 +39,25 @@ Example configuration >> >> systemctl start serial-getty@3270-tty1.service >> >> -This should get you an addtional tty for logging into the guest. >> + This should get you an addtional tty for logging into the guest. >> + >> +* If you want to use the 3270 device as the kernel console instead of an >> + additional tty, you can also append ``conmode=3270 condev=000a`` to the >> + guest's kernel command line. The kernel then should use the 3270 as >> + console after the next boot. >> + >> +Restrictions >> +------------ >> + >> +3270 support is still experimental. In particular: > > s/still experimental/very basic/ > > I don't think there's much progress on the horizon; let's not give > people false hope :) > >> + >> +* Only one 3270 device is supported. >> + >> +* It has only been tested with Linux guests and the x3270 emulator. >> + >> +* TLS/SSL is not yet supported. > > s/yet // > >> + >> +* Resizing on reattach is not yet supported. > > s/yet // > >> + >> +* Multiple commands in one inbound buffer (for example, when the reset key >> + is pressed while the network is slow) are not yet supported. > > s/yet // > I'll fix these in v2. Thanks for the review! Thomas
On Fri, 10 Jul 2020 at 11:56, Cornelia Huck <cohuck@redhat.com> wrote: > > On Thu, 9 Jul 2020 18:04:39 +0200 > Thomas Huth <thuth@redhat.com> wrote: > > > There is some additional information about the 3270 support in our > > Wiki at https://wiki.qemu.org/Features/3270 - so let's include this > > information into the main documentation now to have one single > > source of information (the Wiki page could later be removed). > > No objection; but what should our general policy with regard to wiki > pages vs. documentation be? The 3270 support is pretty much static, but > e.g. for vfio-ccw, we use the wiki page as a place where we track > things that should be worked on etc. I think that (apart from docs/devel) the ideal would be that a user should be able to look at the documentation to find what they need to know and not have to look in the wiki. So "feature X is unsupported" is useful to have in the documentation; developer TODO lists, design notes, suggestions for improvements, etc would be better on the wiki. > (Related: What is the scope of our QEMU documentation? Is a libvirt XML > snippet on topic? Kernel configuration options (as in here)?) If we don't think they're liable to become rapidly out of date, I guess we might as well err on the side of providing information that's helpful to users. (I think a full-on "here is a tutorial and how-to guide on setting up guest OS Foo on this model" would perhaps be a bit out of place, but there's lots of space between here and there.) thanks -- PMM
© 2016 - 2024 Red Hat, Inc.