From patchwork Tue Jan 28 18:01:41 2020 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Cornelia Huck X-Patchwork-Id: 1230634 Return-Path: X-Original-To: incoming@patchwork.ozlabs.org Delivered-To: patchwork-incoming@bilbo.ozlabs.org Authentication-Results: ozlabs.org; spf=pass (sender SPF authorized) smtp.mailfrom=nongnu.org (client-ip=209.51.188.17; helo=lists.gnu.org; envelope-from=qemu-devel-bounces+incoming=patchwork.ozlabs.org@nongnu.org; receiver=) Authentication-Results: ozlabs.org; dmarc=fail (p=none dis=none) header.from=redhat.com Authentication-Results: ozlabs.org; dkim=fail reason="signature verification failed" (1024-bit key; unprotected) header.d=redhat.com header.i=@redhat.com header.a=rsa-sha256 header.s=mimecast20190719 header.b=X0os4M8U; dkim-atps=neutral Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by ozlabs.org (Postfix) with ESMTPS id 486cLD51vHz9s1x for ; Wed, 29 Jan 2020 06:36:20 +1100 (AEDT) Received: from localhost ([::1]:36410 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1iwWeo-0002op-OC for incoming@patchwork.ozlabs.org; Tue, 28 Jan 2020 14:36:18 -0500 Received: from eggs.gnu.org ([2001:470:142:3::10]:43201) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1iwVBj-0000IZ-RE for qemu-devel@nongnu.org; Tue, 28 Jan 2020 13:02:13 -0500 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1iwVBh-0008Qe-KB for qemu-devel@nongnu.org; Tue, 28 Jan 2020 13:02:11 -0500 Received: from us-smtp-delivery-1.mimecast.com ([207.211.31.120]:31035 helo=us-smtp-1.mimecast.com) by eggs.gnu.org with esmtps (TLS1.0:DHE_RSA_AES_256_CBC_SHA1:32) (Exim 4.71) (envelope-from ) id 1iwVBh-0008Q9-GB for qemu-devel@nongnu.org; Tue, 28 Jan 2020 13:02:09 -0500 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1580234529; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:cc:mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references; bh=NEMzZc5GftA9BHigBeIaqxAyx6X1L5qJQi+2/xu9yqA=; b=X0os4M8UZSifSyB5XFpsov3agdT4P+t/7v9avCVJOXRTorUHCszGSpVG1CfWfJnYlnvvHw ig6krkvs7id8j/kVLm2a9f/qrWFWf2wO00joq+o7MTzSQo3a6Ze2Zcs4j10lpTSKSmKLZE fDcKZwWV8Vr09rRyYIsGeIdb31zLQdg= Received: from mimecast-mx01.redhat.com (mimecast-mx01.redhat.com [209.132.183.4]) (Using TLS) by relay.mimecast.com with ESMTP id us-mta-299-nR1Kxz0iN6ah6prDv0NwNA-1; Tue, 28 Jan 2020 13:01:50 -0500 Received: from smtp.corp.redhat.com (int-mx01.intmail.prod.int.phx2.redhat.com [10.5.11.11]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mimecast-mx01.redhat.com (Postfix) with ESMTPS id C3C791800D41; Tue, 28 Jan 2020 18:01:48 +0000 (UTC) Received: from localhost (ovpn-116-186.ams2.redhat.com [10.36.116.186]) by smtp.corp.redhat.com (Postfix) with ESMTPS id 38FD319E9C; Tue, 28 Jan 2020 18:01:48 +0000 (UTC) From: Cornelia Huck To: Tony Krowiak , "Jason J . Herne" Subject: [PATCH RFC 1/2] docs: rstfy s390 dasd ipl documentation Date: Tue, 28 Jan 2020 19:01:41 +0100 Message-Id: <20200128180142.15132-2-cohuck@redhat.com> In-Reply-To: <20200128180142.15132-1-cohuck@redhat.com> References: <20200128180142.15132-1-cohuck@redhat.com> MIME-Version: 1.0 X-Scanned-By: MIMEDefang 2.79 on 10.5.11.11 X-MC-Unique: nR1Kxz0iN6ah6prDv0NwNA-1 X-Mimecast-Spam-Score: 0 X-Mimecast-Originator: redhat.com X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.2.x-3.x [generic] X-Received-From: 207.211.31.120 X-BeenThere: qemu-devel@nongnu.org X-Mailman-Version: 2.1.23 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Cc: Thomas Huth , Pierre Morel , Cornelia Huck , qemu-devel@nongnu.org, Halil Pasic , Christian Borntraeger , qemu-s390x@nongnu.org Errors-To: qemu-devel-bounces+incoming=patchwork.ozlabs.org@nongnu.org Sender: "Qemu-devel" While at it, also fix the numbering in 'What QEMU does'. Signed-off-by: Cornelia Huck Reviewed-by: Thomas Huth --- MAINTAINERS | 2 +- docs/devel/index.rst | 1 + .../{s390-dasd-ipl.txt => s390-dasd-ipl.rst} | 65 ++++++++++--------- 3 files changed, 37 insertions(+), 31 deletions(-) rename docs/devel/{s390-dasd-ipl.txt => s390-dasd-ipl.rst} (77%) diff --git a/MAINTAINERS b/MAINTAINERS index f6511d5120ce..628bf7454088 100644 --- a/MAINTAINERS +++ b/MAINTAINERS @@ -1235,7 +1235,7 @@ S: Supported F: hw/s390x/ipl.* F: pc-bios/s390-ccw/ F: pc-bios/s390-ccw.img -F: docs/devel/s390-dasd-ipl.txt +F: docs/devel/s390-dasd-ipl.rst T: git https://github.com/borntraeger/qemu.git s390-next L: qemu-s390x@nongnu.org diff --git a/docs/devel/index.rst b/docs/devel/index.rst index ac862152dcb3..b084def854b8 100644 --- a/docs/devel/index.rst +++ b/docs/devel/index.rst @@ -24,3 +24,4 @@ Contents: tcg tcg-plugins bitops + s390-dasd-ipl diff --git a/docs/devel/s390-dasd-ipl.txt b/docs/devel/s390-dasd-ipl.rst similarity index 77% rename from docs/devel/s390-dasd-ipl.txt rename to docs/devel/s390-dasd-ipl.rst index 9107e048e4e6..1f6a7ea01ce6 100644 --- a/docs/devel/s390-dasd-ipl.txt +++ b/docs/devel/s390-dasd-ipl.rst @@ -1,25 +1,28 @@ -***************************** -***** s390 hardware IPL ***** -***************************** +Booting from real channel-attached devices on s390x +=================================================== + +s390 hardware IPL +----------------- The s390 hardware IPL process consists of the following steps. -1. A READ IPL ccw is constructed in memory location 0x0. +1. A READ IPL ccw is constructed in memory location ``0x0``. This ccw, by definition, reads the IPL1 record which is located on the disk at cylinder 0 track 0 record 1. Note that the chain flag is on in this ccw so when it is complete another ccw will be fetched and executed from memory - location 0x08. + location ``0x08``. -2. Execute the Read IPL ccw at 0x00, thereby reading IPL1 data into 0x00. +2. Execute the Read IPL ccw at ``0x00``, thereby reading IPL1 data into ``0x00``. IPL1 data is 24 bytes in length and consists of the following pieces of - information: [psw][read ccw][tic ccw]. When the machine executes the Read + information: ``[psw][read ccw][tic ccw]``. When the machine executes the Read IPL ccw it read the 24-bytes of IPL1 to be read into memory starting at - location 0x0. Then the ccw program at 0x08 which consists of a read + location ``0x0``. Then the ccw program at ``0x08`` which consists of a read ccw and a tic ccw is automatically executed because of the chain flag from the original READ IPL ccw. The read ccw will read the IPL2 data into memory and the TIC (Transfer In Channel) will transfer control to the channel program contained in the IPL2 data. The TIC channel command is the equivalent of a branch/jump/goto instruction for channel programs. + NOTE: The ccws in IPL1 are defined by the architecture to be format 0. 3. Execute IPL2. @@ -31,15 +34,18 @@ The s390 hardware IPL process consists of the following steps. the real operating system is loaded into memory and we are ready to hand control over to the guest operating system. At this point the guest operating system is entirely responsible for loading any more data it might - need to function. NOTE: The IPL2 channel program might read data into memory - location 0 thereby overwriting the IPL1 psw and channel program. This is ok - as long as the data placed in location 0 contains a psw whose instruction + need to function. + + NOTE: The IPL2 channel program might read data into memory + location ``0x0`` thereby overwriting the IPL1 psw and channel program. This is ok + as long as the data placed in location ``0x0`` contains a psw whose instruction address points to the guest operating system code to execute at the end of the IPL/boot process. + NOTE: The ccws in IPL2 are defined by the architecture to be format 0. 4. Start executing the guest operating system. - The psw that was loaded into memory location 0 as part of the ipl process + The psw that was loaded into memory location ``0x0`` as part of the ipl process should contain the needed flags for the operating system we have loaded. The psw's instruction address will point to the location in memory where we want to start executing the operating system. This psw is loaded (via LPSW @@ -54,18 +60,17 @@ written immediately after the special "Read IPL" ccw, the IPL1 channel program will be executed immediately (the special read ccw has the chaining bit turned on). The TIC at the end of the IPL1 channel program will cause the IPL2 channel program to be executed automatically. After this sequence completes the "Load" -procedure then loads the psw from 0x0. +procedure then loads the psw from ``0x0``. -********************************************************** -***** How this all pertains to QEMU (and the kernel) ***** -********************************************************** +How this all pertains to QEMU (and the kernel) +---------------------------------------------- In theory we should merely have to do the following to IPL/boot a guest operating system from a DASD device: -1. Place a "Read IPL" ccw into memory location 0x0 with chaining bit on. -2. Execute channel program at 0x0. -3. LPSW 0x0. +1. Place a "Read IPL" ccw into memory location ``0x0`` with chaining bit on. +2. Execute channel program at ``0x0``. +3. LPSW ``0x0``. However, our emulation of the machine's channel program logic within the kernel is missing one key feature that is required for this process to work: @@ -89,32 +94,31 @@ Lastly, in some cases (the zipl bootloader for example) the IPL2 program also transfers control to another channel program segment immediately after reading it from the disk. So we need to be able to handle this case. -************************** -***** What QEMU does ***** -************************** +What QEMU does +-------------- Since we are forced to live with prefetch we cannot use the very simple IPL procedure we defined in the preceding section. So we compensate by doing the following. -1. Place "Read IPL" ccw into memory location 0x0, but turn off chaining bit. -2. Execute "Read IPL" at 0x0. +1. Place "Read IPL" ccw into memory location ``0x0``, but turn off chaining bit. +2. Execute "Read IPL" at ``0x0``. - So now IPL1's psw is at 0x0 and IPL1's channel program is at 0x08. + So now IPL1's psw is at ``0x0`` and IPL1's channel program is at ``0x08``. -4. Write a custom channel program that will seek to the IPL2 record and then +3. Write a custom channel program that will seek to the IPL2 record and then execute the READ and TIC ccws from IPL1. Normally the seek is not required because after reading the IPL1 record the disk is automatically positioned to read the very next record which will be IPL2. But since we are not reading both IPL1 and IPL2 as part of the same channel program we must manually set the position. -5. Grab the target address of the TIC instruction from the IPL1 channel program. +4. Grab the target address of the TIC instruction from the IPL1 channel program. This address is where the IPL2 channel program starts. Now IPL2 is loaded into memory somewhere, and we know the address. -6. Execute the IPL2 channel program at the address obtained in step #5. +5. Execute the IPL2 channel program at the address obtained in step #4. Because this channel program can be dynamic, we must use a special algorithm that detects a READ immediately followed by a TIC and breaks the ccw chain @@ -126,8 +130,9 @@ following. channel program from executing properly. Now the operating system code is loaded somewhere in guest memory and the psw - in memory location 0x0 will point to entry code for the guest operating + in memory location ``0x0`` will point to entry code for the guest operating system. -7. LPSW 0x0. +6. LPSW ``0x0`` + LPSW transfers control to the guest operating system and we're done.