From patchwork Fri May 31 06:12:50 2019 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Stewart Smith X-Patchwork-Id: 1108084 Return-Path: X-Original-To: incoming@patchwork.ozlabs.org Delivered-To: patchwork-incoming@bilbo.ozlabs.org Received: from lists.ozlabs.org (lists.ozlabs.org [IPv6:2401:3900:2:1::3]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (4096 bits)) (No client certificate requested) by ozlabs.org (Postfix) with ESMTPS id 45FZCJ2srmz9sDX for ; Fri, 31 May 2019 16:23:40 +1000 (AEST) Authentication-Results: ozlabs.org; dmarc=none (p=none dis=none) header.from=linux.ibm.com Received: from lists.ozlabs.org (lists.ozlabs.org [IPv6:2401:3900:2:1::3]) by lists.ozlabs.org (Postfix) with ESMTP id 45FZCJ1sn7zDqWj for ; Fri, 31 May 2019 16:23:40 +1000 (AEST) X-Original-To: skiboot@lists.ozlabs.org Delivered-To: skiboot@lists.ozlabs.org Authentication-Results: lists.ozlabs.org; spf=pass (mailfrom) smtp.mailfrom=linux.ibm.com (client-ip=148.163.156.1; helo=mx0a-001b2d01.pphosted.com; envelope-from=stewart@linux.ibm.com; receiver=) Authentication-Results: lists.ozlabs.org; dmarc=none (p=none dis=none) header.from=linux.ibm.com Received: from mx0a-001b2d01.pphosted.com (mx0a-001b2d01.pphosted.com [148.163.156.1]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by lists.ozlabs.org (Postfix) with ESMTPS id 45FZ0K65ZjzDqYL for ; Fri, 31 May 2019 16:14:09 +1000 (AEST) Received: from pps.filterd (m0098409.ppops.net [127.0.0.1]) by mx0a-001b2d01.pphosted.com (8.16.0.27/8.16.0.27) with SMTP id x4V643du060041 for ; Fri, 31 May 2019 02:14:07 -0400 Received: from e32.co.us.ibm.com (e32.co.us.ibm.com [32.97.110.150]) by mx0a-001b2d01.pphosted.com with ESMTP id 2stx4v99xk-1 (version=TLSv1.2 cipher=AES256-GCM-SHA384 bits=256 verify=NOT) for ; Fri, 31 May 2019 02:14:07 -0400 Received: from localhost by e32.co.us.ibm.com with IBM ESMTP SMTP Gateway: Authorized Use Only! Violators will be prosecuted for from ; Fri, 31 May 2019 07:14:06 +0100 Received: from b03cxnp08028.gho.boulder.ibm.com (9.17.130.20) by e32.co.us.ibm.com (192.168.1.132) with IBM ESMTP SMTP Gateway: Authorized Use Only! Violators will be prosecuted; (version=TLSv1/SSLv3 cipher=AES256-GCM-SHA384 bits=256/256) Fri, 31 May 2019 07:14:04 +0100 Received: from b03ledav001.gho.boulder.ibm.com (b03ledav001.gho.boulder.ibm.com [9.17.130.232]) by b03cxnp08028.gho.boulder.ibm.com (8.14.9/8.14.9/NCO v10.0) with ESMTP id x4V6E39l30474746 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-GCM-SHA384 bits=256 verify=OK) for ; Fri, 31 May 2019 06:14:03 GMT Received: from b03ledav001.gho.boulder.ibm.com (unknown [127.0.0.1]) by IMSVA (Postfix) with ESMTP id CAC776E050 for ; Fri, 31 May 2019 06:14:03 +0000 (GMT) Received: from b03ledav001.gho.boulder.ibm.com (unknown [127.0.0.1]) by IMSVA (Postfix) with ESMTP id 93BA96E04C for ; Fri, 31 May 2019 06:14:03 +0000 (GMT) Received: from birb.localdomain (unknown [9.185.142.91]) by b03ledav001.gho.boulder.ibm.com (Postfix) with ESMTP for ; Fri, 31 May 2019 06:14:03 +0000 (GMT) Received: by birb.localdomain (Postfix, from userid 1000) id 48329503F92; Fri, 31 May 2019 16:13:57 +1000 (AEST) From: Stewart Smith To: skiboot@lists.ozlabs.org Date: Fri, 31 May 2019 16:12:50 +1000 X-Mailer: git-send-email 2.21.0 In-Reply-To: <20190531061351.22973-1-stewart@linux.ibm.com> References: <20190531061351.22973-1-stewart@linux.ibm.com> MIME-Version: 1.0 X-TM-AS-GCONF: 00 x-cbid: 19053106-0004-0000-0000-0000151674F9 X-IBM-SpamModules-Scores: X-IBM-SpamModules-Versions: BY=3.00011189; HX=3.00000242; KW=3.00000007; PH=3.00000004; SC=3.00000286; SDB=6.01211088; UDB=6.00636341; IPR=6.00992124; MB=3.00027126; MTD=3.00000008; XFM=3.00000015; UTC=2019-05-31 06:14:05 X-IBM-AV-DETECTION: SAVI=unused REMOTE=unused XFE=unused x-cbparentid: 19053106-0005-0000-0000-00008BDE97A1 Message-Id: <20190531061351.22973-50-stewart@linux.ibm.com> X-Proofpoint-Virus-Version: vendor=fsecure engine=2.50.10434:, , definitions=2019-05-31_03:, , signatures=0 X-Proofpoint-Spam-Details: rule=outbound_notspam policy=outbound score=0 priorityscore=1501 malwarescore=0 suspectscore=1 phishscore=0 bulkscore=0 spamscore=0 clxscore=1015 lowpriorityscore=0 mlxscore=0 impostorscore=0 mlxlogscore=999 adultscore=0 classifier=spam adjust=0 reason=mlx scancount=1 engine=8.0.1-1810050000 definitions=main-1905310040 Subject: [Skiboot] [PATCH 049/110] doc: prettify and flesh out OPAL_FLASH_* call documentation X-BeenThere: skiboot@lists.ozlabs.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: Mailing list for skiboot development List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: skiboot-bounces+incoming=patchwork.ozlabs.org@lists.ozlabs.org Sender: "Skiboot" Signed-off-by: Stewart Smith --- doc/opal-api/opal-flash-110-111-112.rst | 65 ++++++++++++++----------- 1 file changed, 37 insertions(+), 28 deletions(-) diff --git a/doc/opal-api/opal-flash-110-111-112.rst b/doc/opal-api/opal-flash-110-111-112.rst index e05bd2db504b..cee9bcc7dcea 100644 --- a/doc/opal-api/opal-flash-110-111-112.rst +++ b/doc/opal-api/opal-flash-110-111-112.rst @@ -1,7 +1,9 @@ OPAL Flash calls ================ -There are three OPAL calls for interacting with flash devices: :: +There are three OPAL calls for interacting with flash devices: + +.. code-block:: c #define OPAL_FLASH_READ 110 #define OPAL_FLASH_WRITE 111 @@ -16,64 +18,71 @@ All operations on the flash device must be aligned to the block size of the flash. This applies to both offset and size arguments. This interface is asynchronous; all calls require a 'token' argument. On -success, the calls will return ``OPAL_ASYNC_COMPLETION``, and an +success, the calls will return :ref:`OPAL_ASYNC_COMPLETION`, and an opal_async_completion message will be sent (with the appropriate token argument) when the operation completes. +.. note:: These calls can have higher than normal latency, spending many + **milliseconds** inside OPAL. This is due to the OPAL_FLASH_* calls + typically being backed by flash on the other side of the LPC bus, + which has a maximum transfer rate of 5MB/sec, or to/from flash attached + to the ast2400/ast2500 (the typical setup for OpenPOWER systems) of + only 1.75MB/sec. + All calls share the same return values: -``OPAL_ASYNC_COMPLETION`` +:ref:`OPAL_ASYNC_COMPLETION` operation started, an async completion will be triggered with the ``token`` argument - -``OPAL_PARAMETER`` +:ref:`OPAL_PARAMETER` invalid flash id - -``OPAL_PARAMETER`` +:ref:`OPAL_PARAMETER` invalid size or offset (alignment, or access beyond end of device) - -``OPAL_BUSY`` +:ref:`OPAL_BUSY` flash in use - -``OPAL_HARDWARE`` +:ref:`OPAL_HARDWARE` error accessing flash device +.. _OPAL_FLASH_READ: + OPAL_FLASH_READ --------------- -Parameters: :: +.. code-block:: c + + #define OPAL_FLASH_READ 110 - uint64_t id - uint64_t offset - uint64_t buffer - uint64_t size - uint64_t token + int64_t opal_flash_read(uint64_t id, uint64_t offset, uint64_t buf, + uint64_t size, uint64_t token); Reads from the specified flash id, at the specified offset, into the buffer. Will trigger an async completion with token when completed. +.. _OPAL_FLASH_ERASE: + OPAL_FLASH_ERASE ---------------- -Parameters: :: +.. code-block:: c - uint64_t id - uint64_t offset - uint64_t size - uint64_t token + #define OPAL_FLASH_ERASE 112 + + int64_t opal_flash_erase(uint64_t id, uint64_t offset, uint64_t size, + uint64_t token); Erases the specified flash id, at the specified offset and size. Will trigger an async completion with token when completed. +.. _OPAL_FLASH_WRITE: + OPAL_FLASH_WRITE ---------------- -Parameters: :: +.. code-block:: c + + #define OPAL_FLASH_WRITE 111 - uint64_t id - uint64_t offset - uint64_t buffer - uint64_t size - uint64_t token + int64_t opal_flash_write(uint64_t id, uint64_t offset, uint64_t buf, + uint64_t size, uint64_t token); Writes buffer to the specified flash id, at the specified offset and size. The flash must be erased before being written. Will trigger an async completion with