[Qemu-devel] [PATCH v2 0/6] QMP: re-organize documentation

[Qemu-devel] [PATCH v2 0/6] QMP: re-organize documentation

[Luiz Capitulino]

The QMP dir is storing QMP docs and scripts. This series moves the scripts to
scripts/qmp/ and the docs to docs/qmp/. Also, the docs are updated.

v2

 - Set git diff.renames to true
 - Fix trailing whitespaces
 - Other minor fixes

Luiz Capitulino (6):
  QMP: add scripts/qmp
  QMP: fix qmp-commands.txt generation path
  QMP: QMP/ -> docs/qmp/
  QMP: Update README file
  QMP: Update qmp-spec.txt
  QMP: qmp-events.txt: alphabetical order fix and other minor changes

 Makefile                            |  6 +--
 QMP/README                          | 88 -------------------------------------
 docs/qmp/README                     | 87 ++++++++++++++++++++++++++++++++++++
 {QMP => docs/qmp}/qmp-events.txt    | 34 +++++++-------
 {QMP => docs/qmp}/qmp-spec.txt      | 65 ++++++++++++---------------
 {QMP => scripts/qmp}/qemu-ga-client |  0
 {QMP => scripts/qmp}/qmp            |  0
 {QMP => scripts/qmp}/qmp-shell      |  2 +-
 {QMP => scripts/qmp}/qmp.py         |  2 +-
 {QMP => scripts/qmp}/qom-fuse       |  0
 {QMP => scripts/qmp}/qom-get        |  0
 {QMP => scripts/qmp}/qom-list       |  0
 {QMP => scripts/qmp}/qom-set        |  0
 13 files changed, 137 insertions(+), 147 deletions(-)
 delete mode 100644 QMP/README
 create mode 100644 docs/qmp/README
 rename {QMP => docs/qmp}/qmp-events.txt (99%)
 rename {QMP => docs/qmp}/qmp-spec.txt (82%)
 rename {QMP => scripts/qmp}/qemu-ga-client (100%)
 rename {QMP => scripts/qmp}/qmp (100%)
 rename {QMP => scripts/qmp}/qmp-shell (99%)
 rename {QMP => scripts/qmp}/qmp.py (99%)
 rename {QMP => scripts/qmp}/qom-fuse (100%)
 rename {QMP => scripts/qmp}/qom-get (100%)
 rename {QMP => scripts/qmp}/qom-list (100%)
 rename {QMP => scripts/qmp}/qom-set (100%)

-- 
1.8.1.4

[Qemu-devel] [PATCH 1/6] QMP: add scripts/qmp

[Luiz Capitulino]

Populate it with all scripts stored in QMP/. Also fixes trailing
whitespaces in qmp-shell and qmp.py.

Signed-off-by: Luiz Capitulino <lcapitulino@redhat.com>
---
 {QMP => scripts/qmp}/qemu-ga-client | 0
 {QMP => scripts/qmp}/qmp            | 0
 {QMP => scripts/qmp}/qmp-shell      | 2 +-
 {QMP => scripts/qmp}/qmp.py         | 2 +-
 {QMP => scripts/qmp}/qom-fuse       | 0
 {QMP => scripts/qmp}/qom-get        | 0
 {QMP => scripts/qmp}/qom-list       | 0
 {QMP => scripts/qmp}/qom-set        | 0
 8 files changed, 2 insertions(+), 2 deletions(-)
 rename {QMP => scripts/qmp}/qemu-ga-client (100%)
 rename {QMP => scripts/qmp}/qmp (100%)
 rename {QMP => scripts/qmp}/qmp-shell (99%)
 rename {QMP => scripts/qmp}/qmp.py (99%)
 rename {QMP => scripts/qmp}/qom-fuse (100%)
 rename {QMP => scripts/qmp}/qom-get (100%)
 rename {QMP => scripts/qmp}/qom-list (100%)
 rename {QMP => scripts/qmp}/qom-set (100%)

diff --git a/QMP/qemu-ga-client b/scripts/qmp/qemu-ga-client
similarity index 100%
rename from QMP/qemu-ga-client
rename to scripts/qmp/qemu-ga-client
diff --git a/QMP/qmp b/scripts/qmp/qmp
similarity index 100%
rename from QMP/qmp
rename to scripts/qmp/qmp
diff --git a/QMP/qmp-shell b/scripts/qmp/qmp-shell
similarity index 99%
rename from QMP/qmp-shell
rename to scripts/qmp/qmp-shell
index 73cb3b6..d6b420f 100755
--- a/QMP/qmp-shell
+++ b/scripts/qmp/qmp-shell
@@ -91,7 +91,7 @@ class QMPShell(qmp.QEMUMonitorProtocol):
         """
         Build a QMP input object from a user provided command-line in the
         following format:
-    
+
             < command-name > [ arg-name1=arg1 ] ... [ arg-nameN=argN ]
         """
         cmdargs = cmdline.split()
diff --git a/QMP/qmp.py b/scripts/qmp/qmp.py
similarity index 99%
rename from QMP/qmp.py
rename to scripts/qmp/qmp.py
index c551df1..21804f4 100644
--- a/QMP/qmp.py
+++ b/scripts/qmp/qmp.py
@@ -1,5 +1,5 @@
 # QEMU Monitor Protocol Python class
-# 
+#
 # Copyright (C) 2009, 2010 Red Hat Inc.
 #
 # Authors:
diff --git a/QMP/qom-fuse b/scripts/qmp/qom-fuse
similarity index 100%
rename from QMP/qom-fuse
rename to scripts/qmp/qom-fuse
diff --git a/QMP/qom-get b/scripts/qmp/qom-get
similarity index 100%
rename from QMP/qom-get
rename to scripts/qmp/qom-get
diff --git a/QMP/qom-list b/scripts/qmp/qom-list
similarity index 100%
rename from QMP/qom-list
rename to scripts/qmp/qom-list
diff --git a/QMP/qom-set b/scripts/qmp/qom-set
similarity index 100%
rename from QMP/qom-set
rename to scripts/qmp/qom-set
-- 
1.8.1.4

[Qemu-devel] [PATCH 2/6] QMP: fix qmp-commands.txt generation path

[Luiz Capitulino]

This file should be generated in the BUILD_DIR, as all other docs.

Signed-off-by: Luiz Capitulino <lcapitulino@redhat.com>
Reviewed-by: Eric Blake <eblake@redhat.com>
---
 Makefile | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/Makefile b/Makefile
index 362fe3e..aca548d 100644
--- a/Makefile
+++ b/Makefile
@@ -65,7 +65,7 @@ LIBS+=-lz $(LIBS_TOOLS)
 HELPERS-$(CONFIG_LINUX) = qemu-bridge-helper$(EXESUF)
 
 ifdef BUILD_DOCS
-DOCS=qemu-doc.html qemu-tech.html qemu.1 qemu-img.1 qemu-nbd.8 QMP/qmp-commands.txt
+DOCS=qemu-doc.html qemu-tech.html qemu.1 qemu-img.1 qemu-nbd.8 qmp-commands.txt
 ifdef CONFIG_VIRTFS
 DOCS+=fsdev/virtfs-proxy-helper.1
 endif
@@ -304,7 +304,7 @@ endif
 install-doc: $(DOCS)
 	$(INSTALL_DIR) "$(DESTDIR)$(qemu_docdir)"
 	$(INSTALL_DATA) qemu-doc.html  qemu-tech.html "$(DESTDIR)$(qemu_docdir)"
-	$(INSTALL_DATA) QMP/qmp-commands.txt "$(DESTDIR)$(qemu_docdir)"
+	$(INSTALL_DATA) qmp-commands.txt "$(DESTDIR)$(qemu_docdir)"
 ifdef CONFIG_POSIX
 	$(INSTALL_DIR) "$(DESTDIR)$(mandir)/man1"
 	$(INSTALL_DATA) qemu.1 "$(DESTDIR)$(mandir)/man1"
@@ -398,7 +398,7 @@ qemu-options.texi: $(SRC_PATH)/qemu-options.hx
 qemu-monitor.texi: $(SRC_PATH)/hmp-commands.hx
 	$(call quiet-command,sh $(SRC_PATH)/scripts/hxtool -t < $< > $@,"  GEN   $@")
 
-QMP/qmp-commands.txt: $(SRC_PATH)/qmp-commands.hx
+qmp-commands.txt: $(SRC_PATH)/qmp-commands.hx
 	$(call quiet-command,sh $(SRC_PATH)/scripts/hxtool -q < $< > $@,"  GEN   $@")
 
 qemu-img-cmds.texi: $(SRC_PATH)/qemu-img-cmds.hx
-- 
1.8.1.4

[Qemu-devel] [PATCH 3/6] QMP: QMP/ -> docs/qmp/

[Luiz Capitulino]

Signed-off-by: Luiz Capitulino <lcapitulino@redhat.com>
---
 {QMP => docs/qmp}/README         | 0
 {QMP => docs/qmp}/qmp-events.txt | 0
 {QMP => docs/qmp}/qmp-spec.txt   | 0
 3 files changed, 0 insertions(+), 0 deletions(-)
 rename {QMP => docs/qmp}/README (100%)
 rename {QMP => docs/qmp}/qmp-events.txt (100%)
 rename {QMP => docs/qmp}/qmp-spec.txt (100%)

diff --git a/QMP/README b/docs/qmp/README
similarity index 100%
rename from QMP/README
rename to docs/qmp/README
diff --git a/QMP/qmp-events.txt b/docs/qmp/qmp-events.txt
similarity index 100%
rename from QMP/qmp-events.txt
rename to docs/qmp/qmp-events.txt
diff --git a/QMP/qmp-spec.txt b/docs/qmp/qmp-spec.txt
similarity index 100%
rename from QMP/qmp-spec.txt
rename to docs/qmp/qmp-spec.txt
-- 
1.8.1.4

[Qemu-devel] [PATCH 4/6] QMP: Update README file

[Luiz Capitulino]

Drop unneeded info, fix some of the examples and rename QEMU Monitor
Protocol to QEMU Machine Protocol.

Signed-off-by: Luiz Capitulino <lcapitulino@redhat.com>
Reviewed-by: Eric Blake <eblake@redhat.com>
---
 docs/qmp/README | 99 ++++++++++++++++++++++++++++-----------------------------
 1 file changed, 49 insertions(+), 50 deletions(-)

diff --git a/docs/qmp/README b/docs/qmp/README
index c95a08c..85c4bc1 100644
--- a/docs/qmp/README
+++ b/docs/qmp/README
@@ -1,13 +1,13 @@
-                          QEMU Monitor Protocol
+                          QEMU Machine Protocol
                           =====================
 
 Introduction
--------------
+------------
 
-The QEMU Monitor Protocol (QMP) allows applications to communicate with
-QEMU's Monitor.
+The QEMU Machine Protocol (QMP) allows applications to operate a
+QEMU instance.
 
-QMP is JSON[1] based and currently has the following features:
+QMP is JSON[1] based and features the following:
 
 - Lightweight, text-based, easy to parse data format
 - Asynchronous messages support (ie. events)
@@ -15,37 +15,28 @@ QMP is JSON[1] based and currently has the following features:
 
 For detailed information on QMP's usage, please, refer to the following files:
 
-o qmp-spec.txt      QEMU Monitor Protocol current specification
+o qmp-spec.txt      QEMU Machine Protocol current specification
 o qmp-commands.txt  QMP supported commands (auto-generated at build-time)
 o qmp-events.txt    List of available asynchronous events
 
-There is also a simple Python script called 'qmp-shell' available.
-
-IMPORTANT: It's strongly recommended to read the 'Stability Considerations'
-section in the qmp-commands.txt file before making any serious use of QMP.
-
-
 [1] http://www.json.org
 
 Usage
 -----
 
-To enable QMP, you need a QEMU monitor instance in "control mode". There are
-two ways of doing this.
+You can use the -qmp option to enable QMP. For example, the following
+makes QMP available on localhost port 4444:
 
-The simplest one is using the '-qmp' command-line option. The following
-example makes QMP available on localhost port 4444:
+$ qemu [...] -qmp tcp:localhost:4444,server,nowait
 
-  $ qemu [...] -qmp tcp:localhost:4444,server
+However, for more flexibility and to make use of more options, the -mon
+command-line option should be used. For instance, the following example
+creates one HMP instance (human monitor) on stdio and one QMP instance
+on localhost port 4444:
 
-However, in order to have more complex combinations, like multiple monitors,
-the '-mon' command-line option should be used along with the '-chardev' one.
-For instance, the following example creates one user monitor on stdio and one
-QMP monitor on localhost port 4444.
-
-   $ qemu [...] -chardev stdio,id=mon0 -mon chardev=mon0,mode=readline \
-                -chardev socket,id=mon1,host=localhost,port=4444,server \
-                -mon chardev=mon1,mode=control
+$ qemu [...] -chardev stdio,id=mon0 -mon chardev=mon0,mode=readline \
+             -chardev socket,id=mon1,host=localhost,port=4444,server,nowait \
+             -mon chardev=mon1,mode=control,pretty=on
 
 Please, refer to QEMU's manpage for more information.
 
@@ -58,31 +49,39 @@ $ telnet localhost 4444
 Trying 127.0.0.1...
 Connected to localhost.
 Escape character is '^]'.
-{"QMP": {"version": {"qemu": {"micro": 50, "minor": 13, "major": 0}, "package": ""}, "capabilities": []}}
-{ "execute": "qmp_capabilities" }
-{"return": {}}
-{ "execute": "query-version" }
-{"return": {"qemu": {"micro": 50, "minor": 13, "major": 0}, "package": ""}}
-
-Development Process
--------------------
+{
+    "QMP": {
+        "version": {
+            "qemu": {
+                "micro": 50, 
+                "minor": 6, 
+                "major": 1
+            }, 
+            "package": ""
+        }, 
+        "capabilities": [
+        ]
+    }
+}
 
-When changing QMP's interface (by adding new commands, events or modifying
-existing ones) it's mandatory to update the relevant documentation, which is
-one (or more) of the files listed in the 'Introduction' section*.
-
-Also, it's strongly recommended to send the documentation patch first, before
-doing any code change. This is so because:
-
-  1. Avoids the code dictating the interface
-
-  2. Review can improve your interface.  Letting that happen before
-     you implement it can save you work.
-
-* The qmp-commands.txt file is generated from the qmp-commands.hx one, which
-  is the file that should be edited.
-
-Homepage
---------
+{ "execute": "qmp_capabilities" }
+{
+    "return": {
+    }
+}
+
+{ "execute": "query-status" }
+{
+    "return": {
+        "status": "prelaunch", 
+        "singlestep": false, 
+        "running": false
+    }
+}
+
+Please, refer to the qapi-schema.json file for a complete command reference.
+
+QMP wiki page
+-------------
 
 http://wiki.qemu.org/QMP
-- 
1.8.1.4

[Qemu-devel] [PATCH 5/6] QMP: Update qmp-spec.txt

[Luiz Capitulino]

Simplify the text, fix some of the examples.

Signed-off-by: Luiz Capitulino <lcapitulino@redhat.com>
Reviewed-by: Eric Blake <eblake@redhat.com>
---
 docs/qmp/qmp-spec.txt | 65 ++++++++++++++++++++++-----------------------------
 1 file changed, 28 insertions(+), 37 deletions(-)

diff --git a/docs/qmp/qmp-spec.txt b/docs/qmp/qmp-spec.txt
index a277896..22568c6 100644
--- a/docs/qmp/qmp-spec.txt
+++ b/docs/qmp/qmp-spec.txt
@@ -1,21 +1,17 @@
-           QEMU Monitor Protocol Specification - Version 0.1
+                      QEMU Machine Protocol Specification
 
 1. Introduction
 ===============
 
-This document specifies the QEMU Monitor Protocol (QMP), a JSON-based protocol
-which is available for applications to control QEMU at the machine-level.
-
-To enable QMP support, QEMU has to be run in "control mode". This is done by
-starting QEMU with the appropriate command-line options. Please, refer to the
-QEMU manual page for more information.
+This document specifies the QEMU Machine Protocol (QMP), a JSON-based protocol
+which is available for applications to operate QEMU at the machine-level.
 
 2. Protocol Specification
 =========================
 
 This section details the protocol format. For the purpose of this document
-"Client" is any application which is communicating with QEMU in control mode,
-and "Server" is QEMU itself.
+"Client" is any application which is using QMP to communicate with QEMU and
+"Server" is QEMU itself.
 
 JSON data structures, when mentioned in this document, are always in the
 following format:
@@ -47,14 +43,14 @@ that the connection has been successfully established and that the Server is
 ready for capabilities negotiation (for more information refer to section
 '4. Capabilities Negotiation').
 
-The format is:
+The greeting message format is:
 
 { "QMP": { "version": json-object, "capabilities": json-array } }
 
  Where,
 
 - The "version" member contains the Server's version information (the format
-  is the same of the 'query-version' command)
+  is the same of the query-version command)
 - The "capabilities" member specify the availability of features beyond the
   baseline specification
 
@@ -83,10 +79,7 @@ of a command execution: success or error.
 2.4.1 success
 -------------
 
-The success response is issued when the command execution has finished
-without errors.
-
-The format is:
+The format of a success response is:
 
 { "return": json-object, "id": json-value }
 
@@ -96,15 +89,12 @@ The format is:
   in a per-command basis or an empty json-object if the command does not
   return data
 - The "id" member contains the transaction identification associated
-  with the command execution (if issued by the Client)
+  with the command execution if issued by the Client
 
 2.4.2 error
 -----------
 
-The error response is issued when the command execution could not be
-completed because of an error condition.
-
-The format is:
+The format of an error response is:
 
 { "error": { "class": json-string, "desc": json-string }, "id": json-value }
 
@@ -114,7 +104,7 @@ The format is:
 - The "desc" member is a human-readable error message. Clients should
   not attempt to parse this message.
 - The "id" member contains the transaction identification associated with
-  the command execution (if issued by the Client)
+  the command execution if issued by the Client
 
 NOTE: Some errors can occur before the Server is able to read the "id" member,
 in these cases the "id" member will not be part of the error response, even
@@ -124,9 +114,9 @@ if provided by the client.
 -----------------------
 
 As a result of state changes, the Server may send messages unilaterally
-to the Client at any time. They are called 'asynchronous events'.
+to the Client at any time. They are called "asynchronous events".
 
-The format is:
+The format of asynchronous events is:
 
 { "event": json-string, "data": json-object,
   "timestamp": { "seconds": json-number, "microseconds": json-number } }
@@ -147,36 +137,37 @@ qmp-events.txt file.
 ===============
 
 This section provides some examples of real QMP usage, in all of them
-'C' stands for 'Client' and 'S' stands for 'Server'.
+"C" stands for "Client" and "S" stands for "Server".
 
 3.1 Server greeting
 -------------------
 
-S: {"QMP": {"version": {"qemu": "0.12.50", "package": ""}, "capabilities": []}}
+S: { "QMP": { "version": { "qemu": { "micro": 50, "minor": 6, "major": 1 },
+     "package": ""}, "capabilities": []}}
 
 3.2 Simple 'stop' execution
 ---------------------------
 
 C: { "execute": "stop" }
-S: {"return": {}}
+S: { "return": {} }
 
 3.3 KVM information
 -------------------
 
 C: { "execute": "query-kvm", "id": "example" }
-S: {"return": {"enabled": true, "present": true}, "id": "example"}
+S: { "return": { "enabled": true, "present": true }, "id": "example"}
 
 3.4 Parsing error
 ------------------
 
 C: { "execute": }
-S: {"error": {"class": "GenericError", "desc": "Invalid JSON syntax" } }
+S: { "error": { "class": "GenericError", "desc": "Invalid JSON syntax" } }
 
 3.5 Powerdown event
 -------------------
 
-S: {"timestamp": {"seconds": 1258551470, "microseconds": 802384}, "event":
-"POWERDOWN"}
+S: { "timestamp": { "seconds": 1258551470, "microseconds": 802384 },
+    "event": "POWERDOWN" }
 
 4. Capabilities Negotiation
 ----------------------------
@@ -184,17 +175,17 @@ S: {"timestamp": {"seconds": 1258551470, "microseconds": 802384}, "event":
 When a Client successfully establishes a connection, the Server is in
 Capabilities Negotiation mode.
 
-In this mode only the 'qmp_capabilities' command is allowed to run, all
-other commands will return the CommandNotFound error. Asynchronous messages
-are not delivered either.
+In this mode only the qmp_capabilities command is allowed to run, all
+other commands will return the CommandNotFound error. Asynchronous
+messages are not delivered either.
 
-Clients should use the 'qmp_capabilities' command to enable capabilities
+Clients should use the qmp_capabilities command to enable capabilities
 advertised in the Server's greeting (section '2.2 Server Greeting') they
 support.
 
-When the 'qmp_capabilities' command is issued, and if it does not return an
+When the qmp_capabilities command is issued, and if it does not return an
 error, the Server enters in Command mode where capabilities changes take
-effect, all commands (except 'qmp_capabilities') are allowed and asynchronous
+effect, all commands (except qmp_capabilities) are allowed and asynchronous
 messages are delivered.
 
 5 Compatibility Considerations
@@ -245,7 +236,7 @@ arguments, errors, asynchronous events, and so forth.
 
 Any new names downstream wishes to add must begin with '__'.  To
 ensure compatibility with other downstreams, it is strongly
-recommended that you prefix your downstram names with '__RFQDN_' where
+recommended that you prefix your downstream names with '__RFQDN_' where
 RFQDN is a valid, reverse fully qualified domain name which you
 control.  For example, a qemu-kvm specific monitor command would be:
 
-- 
1.8.1.4

[Qemu-devel] [PATCH 6/6] QMP: qmp-events.txt: alphabetical order fix and other minor changes

[Luiz Capitulino]

Signed-off-by: Luiz Capitulino <lcapitulino@redhat.com>
---
 docs/qmp/qmp-events.txt | 34 +++++++++++++++++-----------------
 1 file changed, 17 insertions(+), 17 deletions(-)

diff --git a/docs/qmp/qmp-events.txt b/docs/qmp/qmp-events.txt
index 4b24ec9..6b87e97 100644
--- a/docs/qmp/qmp-events.txt
+++ b/docs/qmp/qmp-events.txt
@@ -1,4 +1,4 @@
-                   QEMU Monitor Protocol Events
+                   QEMU Machine Protocol Events
                    ============================
 
 BALLOON_CHANGE
@@ -159,7 +159,7 @@ Note: The "ready to complete" status is always reset by a BLOCK_JOB_ERROR
 event.
 
 DEVICE_DELETED
------------------
+--------------
 
 Emitted whenever the device removal completion is acknowledged
 by the guest.
@@ -194,8 +194,22 @@ Data:
   },
   "timestamp": { "seconds": 1265044230, "microseconds": 450486 } }
 
+GUEST_PANICKED
+--------------
+
+Emitted when guest OS panic is detected.
+
+Data:
+
+- "action": Action that has been taken (json-string, currently always "pause").
+
+Example:
+
+{ "event": "GUEST_PANICKED",
+     "data": { "action": "pause" } }
+
 NIC_RX_FILTER_CHANGED
------------------
+---------------------
 
 The event is emitted once until the query command is executed,
 the first event will always be emitted.
@@ -486,17 +500,3 @@ Example:
 
 Note: If action is "reset", "shutdown", or "pause" the WATCHDOG event is
 followed respectively by the RESET, SHUTDOWN, or STOP events.
-
-GUEST_PANICKED
---------------
-
-Emitted when guest OS panic is detected.
-
-Data:
-
-- "action": Action that has been taken (json-string, currently always "pause").
-
-Example:
-
-{ "event": "GUEST_PANICKED",
-     "data": { "action": "pause" } }
-- 
1.8.1.4

Re: [Qemu-devel] [PATCH v2 0/6] QMP: re-organize documentation

[Eric Blake]

[-- Attachment #1: Type: text/plain, Size: 731 bytes --]

On 09/13/2013 12:11 PM, Luiz Capitulino wrote:
> The QMP dir is storing QMP docs and scripts. This series moves the scripts to
> scripts/qmp/ and the docs to docs/qmp/. Also, the docs are updated.
> 
> v2
> 
>  - Set git diff.renames to true
>  - Fix trailing whitespaces
>  - Other minor fixes
> 
> Luiz Capitulino (6):
>   QMP: add scripts/qmp
>   QMP: fix qmp-commands.txt generation path
>   QMP: QMP/ -> docs/qmp/
>   QMP: Update README file
>   QMP: Update qmp-spec.txt
>   QMP: qmp-events.txt: alphabetical order fix and other minor changes

Series: Reviewed-by: Eric Blake <eblake@redhat.com>

-- 
Eric Blake   eblake redhat com    +1-919-301-3266
Libvirt virtualization library http://libvirt.org


[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 621 bytes --]