From fc6bf8cf80377d26f4ab4d09e11f8581d778a9d5 Mon Sep 17 00:00:00 2001 From: Mark Ryan Date: Fri, 26 Aug 2016 16:27:50 +0100 Subject: [PATCH] qemu: Add package documentation This commit adds some package documentation to the qemu package, including an overview of the package and an example of its use. Signed-off-by: Mark Ryan --- examples_test.go | 84 ++++++++++++++++++++++++++++++++++++++++++++++++ qemu.go | 8 +++++ 2 files changed, 92 insertions(+) create mode 100644 examples_test.go diff --git a/examples_test.go b/examples_test.go new file mode 100644 index 0000000000..1fc9dcf3a3 --- /dev/null +++ b/examples_test.go @@ -0,0 +1,84 @@ +/* +// Copyright (c) 2016 Intel Corporation +// +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. +*/ + +package qemu_test + +import ( + "time" + + "github.com/01org/ciao/qemu" + "golang.org/x/net/context" +) + +func Example() { + params := make([]string, 0, 32) + + // Rootfs + params = append(params, "-drive", "file=/tmp/image.qcow2,if=virtio,aio=threads,format=qcow2") + // Network + params = append(params, "-net", "nic,model=virtio", "-net", "user") + // kvm + params = append(params, "-enable-kvm", "-cpu", "host") + // qmp socket + params = append(params, "-daemonize", "-qmp", "unix:/tmp/qmp-socket,server,nowait") + // resources + params = append(params, "-m", "370", "-smp", "cpus=2") + + // LaunchQemu should return as soon as the instance has launched as we + // are using the --daemonize flag. It will set up a unix domain socket + // called /tmp/qmp-socket that we can use to manage the instance. + _, err := qemu.LaunchQemu(context.Background(), params, nil, nil) + if err != nil { + panic(err) + } + + // This channel will be closed when the instance dies. + disconnectedCh := make(chan struct{}) + + // Set up our options. We don't want any logging or to receive any events. + cfg := qemu.QMPConfig{} + + // Start monitoring the qemu instance. This functon will block until we have + // connect to the QMP socket and received the welcome message. + q, _, err := qemu.QMPStart(context.Background(), "/tmp/qmp-socket", cfg, disconnectedCh) + if err != nil { + panic(err) + } + + // This has to be the first command executed in a QMP session. + err = q.ExecuteQMPCapabilities(context.Background()) + if err != nil { + panic(err) + } + + // Let's try to shutdown the VM. If it hasn't shutdown in 10 seconds we'll + // send a quit message. + ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second) + err = q.ExecuteSystemPowerdown(ctx) + cancel() + if err != nil { + err = q.ExecuteQuit(context.Background()) + if err != nil { + panic(err) + } + } + + q.Shutdown() + + // disconnectedCh is closed when the VM exits. This line blocks until this + // event occurs. + <-disconnectedCh +} diff --git a/qemu.go b/qemu.go index a98928cd39..4984ec63d6 100644 --- a/qemu.go +++ b/qemu.go @@ -14,6 +14,14 @@ // limitations under the License. */ +// Package qemu provides methods and types for launching and managing QEMU +// instances. Instances can be launched with the LaunchQemu function and +// managed thereafter via QMPStart and the QMP object that this function +// returns. To manage a qemu instance after it has been launched you need +// to pass the -qmp option during launch requesting the qemu instance to create +// a QMP unix domain manageent socket, e.g., +// -qmp unix:/tmp/qmp-socket,server,nowait. For more information see the +// example below. package qemu import (