{"id":810874,"url":"http://patchwork.ozlabs.org/api/1.2/patches/810874/?format=json","web_url":"http://patchwork.ozlabs.org/project/skiboot/patch/20170907071409.7163-2-sjitindarsingh@gmail.com/","project":{"id":44,"url":"http://patchwork.ozlabs.org/api/1.2/projects/44/?format=json","name":"skiboot firmware development","link_name":"skiboot","list_id":"skiboot.lists.ozlabs.org","list_email":"skiboot@lists.ozlabs.org","web_url":"http://github.com/open-power/skiboot","scm_url":"http://github.com/open-power/skiboot","webscm_url":"","list_archive_url":"","list_archive_url_format":"","commit_url_format":""},"msgid":"<20170907071409.7163-2-sjitindarsingh@gmail.com>","list_archive_url":null,"date":"2017-09-07T07:14:09","name":"[RFC] docs: Specify V3 of the mbox protocol","commit_ref":null,"pull_url":null,"state":"rfc","archived":false,"hash":"2b6cca34d6392353862e38f7f1713634b3e5de50","submitter":{"id":68427,"url":"http://patchwork.ozlabs.org/api/1.2/people/68427/?format=json","name":"Suraj Jitindar Singh","email":"sjitindarsingh@gmail.com"},"delegate":null,"mbox":"http://patchwork.ozlabs.org/project/skiboot/patch/20170907071409.7163-2-sjitindarsingh@gmail.com/mbox/","series":[{"id":1926,"url":"http://patchwork.ozlabs.org/api/1.2/series/1926/?format=json","web_url":"http://patchwork.ozlabs.org/project/skiboot/list/?series=1926","date":"2017-09-07T07:14:09","name":"[RFC] docs: Specify V3 of the mbox protocol","version":1,"mbox":"http://patchwork.ozlabs.org/series/1926/mbox/"}],"comments":"http://patchwork.ozlabs.org/api/patches/810874/comments/","check":"pending","checks":"http://patchwork.ozlabs.org/api/patches/810874/checks/","tags":{},"related":[],"headers":{"Return-Path":"","X-Original-To":["incoming@patchwork.ozlabs.org","skiboot@lists.ozlabs.org"],"Delivered-To":["patchwork-incoming@bilbo.ozlabs.org","skiboot@lists.ozlabs.org"],"Received":["from lists.ozlabs.org (lists.ozlabs.org [IPv6:2401:3900:2:1::3])\n\t(using TLSv1.2 with cipher ADH-AES256-GCM-SHA384 (256/256 bits))\n\t(No client certificate requested)\n\tby ozlabs.org (Postfix) with ESMTPS id 3xnsDl4bfzz9sCZ\n\tfor ;\n\tThu, 7 Sep 2017 17:15:51 +1000 (AEST)","from lists.ozlabs.org (lists.ozlabs.org [IPv6:2401:3900:2:1::3])\n\tby lists.ozlabs.org (Postfix) with ESMTP id 3xnsDl3RTRzDrCX\n\tfor ;\n\tThu, 7 Sep 2017 17:15:51 +1000 (AEST)","from mail-pg0-x243.google.com (mail-pg0-x243.google.com\n\t[IPv6:2607:f8b0:400e:c05::243])\n\t(using TLSv1.2 with cipher ECDHE-RSA-AES128-GCM-SHA256 (128/128\n\tbits)) (No client certificate requested)\n\tby lists.ozlabs.org (Postfix) with ESMTPS id 3xnsCD5f0VzDrWB;\n\tThu, 7 Sep 2017 17:14:31 +1000 (AEST)","by mail-pg0-x243.google.com with SMTP id v82so3965320pgb.1;\n\tThu, 07 Sep 2017 00:14:31 -0700 (PDT)","from surajjs1.ozlabs.ibm.com ([122.99.82.10])\n\tby smtp.gmail.com with ESMTPSA id\n\tz1sm2276402pge.45.2017.09.07.00.14.25\n\t(version=TLS1_2 cipher=ECDHE-RSA-AES128-GCM-SHA256 bits=128/128);\n\tThu, 07 Sep 2017 00:14:28 -0700 (PDT)"],"Authentication-Results":["ozlabs.org;\n\tdkim=fail reason=\"signature verification failed\" (2048-bit key;\n\tunprotected) header.d=gmail.com header.i=@gmail.com\n\theader.b=\"tE/2ygyO\"; dkim-atps=neutral","lists.ozlabs.org;\n\tdkim=fail reason=\"signature verification failed\" (2048-bit key;\n\tunprotected) header.d=gmail.com header.i=@gmail.com\n\theader.b=\"tE/2ygyO\"; dkim-atps=neutral","ozlabs.org;\n\tspf=pass (mailfrom) smtp.mailfrom=gmail.com\n\t(client-ip=2607:f8b0:400e:c05::243; helo=mail-pg0-x243.google.com;\n\tenvelope-from=sjitindarsingh@gmail.com; receiver=)","lists.ozlabs.org; dkim=pass (2048-bit key;\n\tunprotected) header.d=gmail.com header.i=@gmail.com\n\theader.b=\"tE/2ygyO\"; dkim-atps=neutral"],"DKIM-Signature":"v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20161025;\n\th=from:to:cc:subject:date:message-id:in-reply-to:references;\n\tbh=tuSjNjUlaA6k1S/nXTV6P7CMxW8WVhbMVDnicq9VtRI=;\n\tb=tE/2ygyOtZHe1DNQ74sO3/0Mwn5HcbOgXAksE0z7XsXCcXcUXp42OhoiAsGQc4b9aC\n\t3Kygo3MpJ+JAUIT6sXvGqGkvD1LlyyiLWOVyGNGLCPyFaNGLaEd/o58YPDPznYNXZvf4\n\tS0cC8YaXe2onh8ocpSPq1vcO6FNDOrQivNcU6qRai60ADAhXMY93R418MwvW5xBIFhvu\n\tOXhGz1GaJbU21FNqdh1d8I7eTvn6BWbtHU6F3qMXrf5yJnMkuYk7i0qQh7c4Mh4qoZUf\n\tGt53I+UyJB+M568PC9LYyy5YmWqfiaBFlM2a1kEL9RyNW3vMqiRCvp8h7gRMJ6ibwMOp\n\t6O5A==","X-Google-DKIM-Signature":"v=1; a=rsa-sha256; c=relaxed/relaxed;\n\td=1e100.net; s=20161025;\n\th=x-gm-message-state:from:to:cc:subject:date:message-id:in-reply-to\n\t:references;\n\tbh=tuSjNjUlaA6k1S/nXTV6P7CMxW8WVhbMVDnicq9VtRI=;\n\tb=D9508St/ppHqgEHDKhUMtRgVZqyThVKsXvQSKiCq42gu50LvBS/UZmqNKVaVbC7aNB\n\t9QKzuP9zWdnYqfCDRlS0YH1APEiV//nN2oYCVu0KEl+TyLwXB+68MlB5FI7kHQYwVp2V\n\tXuY8YrqWjkrv/Fj7jDoXapgmoGmnU9GvEA2aXLJQjgLo7S0ZomUhHBEPC97dnXrrWtZ4\n\t8Yr1fUs/Jld6p88aZrNLNBkfupOg4Nh1oRJ3rdRbbVr0rNurZ3b4CAekrkNLwT7dgGCB\n\tYOqvljCUe0jDj3zbmhhHdTqMYxOW2M4zuYhdMk4/esQWdbV4q4pYT2OUPMz9mAzw2xih\n\tVEgg==","X-Gm-Message-State":"AHPjjUhqH7Smad+6qn1/RwEeHBc40IPyEFqyCzp3bD8E5PzTwR9r0m4n\n\tXacCA0TMFRv5X7X+","X-Google-Smtp-Source":"ADKCNb7UkiX+k6Fv0WPE7IFWp8TcVF1EoiFf4IaSUcH4dhHnUAILuDI9x1L4WWxmpXavYijuGs/BGw==","X-Received":"by 10.99.127.68 with SMTP id p4mr1730946pgn.253.1504768469001;\n\tThu, 07 Sep 2017 00:14:29 -0700 (PDT)","From":"Suraj Jitindar Singh ","To":"skiboot@lists.ozlabs.org,\n\topenbmc@lists.ozlabs.org","Date":"Thu, 7 Sep 2017 17:14:09 +1000","Message-Id":"<20170907071409.7163-2-sjitindarsingh@gmail.com>","X-Mailer":"git-send-email 2.9.4","In-Reply-To":"<20170907071409.7163-1-sjitindarsingh@gmail.com>","References":"<20170907071409.7163-1-sjitindarsingh@gmail.com>","Subject":"[Skiboot] [RFC] docs: Specify V3 of the mbox protocol","X-BeenThere":"skiboot@lists.ozlabs.org","X-Mailman-Version":"2.1.23","Precedence":"list","List-Id":"Mailing list for skiboot development ","List-Unsubscribe":",\n\t","List-Archive":"","List-Post":"","List-Help":"","List-Subscribe":",\n\t","Cc":"andrew@aj.id.au, cyrilbur@gmail.comm","MIME-Version":"1.0","Content-Type":"text/plain; charset=\"utf-8\"","Content-Transfer-Encoding":"base64","Errors-To":"skiboot-bounces+incoming=patchwork.ozlabs.org@lists.ozlabs.org","Sender":"\"Skiboot\"\n\t"},"content":"Version 3 of the mbox protocol makes four protocol changes:\n - Add a requested block size argument to GET_MBOX_INFO\n - Add a no erase argument to MARK_DIRTY\n - Add a GET_FLASH_NAME command and support multiple flash devices\n - Add a MARK_LOCKED command\n\nRequested Block Size:\nThe requested block size argument has been added to the GET_MBOX_INFO\ncommand to allow the host to request a specified block size which might\nbe required to allow data manipulation at a finer granularity. The\ndaemon should take this into account when choosing a block size for use\nwhich it will specify in the response as before. The daemon has final\nsay and the host must use the block size the daemon chooses.\n\nNo Erase:\nThe no erase argument to the mark dirty command allows a host to specify\nthat an area of flash should not be erased before being written to, as is\nthe default behaviour. This can be used when a host has already erased a\nlarge area and then performs many small writes which would normally mean\nmany erases due to the implicit erase before write, making this slow.\n\nAdd GET_FLASH_NAME command:\nThe ability to support multiple flash devices has been added so that the\nmbox protocol can be used to arbitrate access from the host to a number\nof flash devices which the daemon has access to. To facilitate this the\nGET_FLASH_INFO, CREATE_{READ/WRITE}_WINDOW, and MARK_LOCKED commands now\ntake a flash ID, with the number of flash IDs allocated returned by the\nGET_MBOX_INFO commands. There is also a new command GET_FLASH_NAME used\nto convert a flash ID to a flash name.\n\nAdd MARK_LOCKED command:\nThe MARK_LOCKED command has been added to allow an area(s) of flash to be\nlocked, that is that area must be treated as read only and the host is\nnot allowed to dirty or erase any windows which map that area of flash.\nAdditionally another error code LOCKED_ERROR was added to be returned\nwhen the host does try to dirty or erase a locked area.\n\nThe host cannot lock a currently dirty or erased area of the current\nwrite window as it is not defined if the clean/dirty/erased value is\nwhat should actually be \"locked\".\n\nA locked area of flash remains so until the daemon receives an\nmboxctl --reset command and the locked areas are stored in a file on the\nBMC filesystem to ensure persistence across BMC reboots/daemon crashes.\n\nMultiple flash device support proposed and defined by:\nWilliam A. Kennington III \n\nSigned-off-by: Suraj Jitindar Singh \n---\n Documentation/mbox_protocol.md | 127 ++++++++++++++++++++++++++++++-----------\n 1 file changed, 93 insertions(+), 34 deletions(-)","diff":"diff --git a/Documentation/mbox_protocol.md b/Documentation/mbox_protocol.md\nindex bcd70a8..74863a7 100644\n--- a/Documentation/mbox_protocol.md\n+++ b/Documentation/mbox_protocol.md\n@@ -17,19 +17,21 @@ limitations under the License.\n This document describes a protocol for host to BMC communication via the\n mailbox registers present on the Aspeed 2400 and 2500 chips.\n This protocol is specifically designed to allow a host to request and manage\n-access to the flash with the specifics of how the host is required to control\n-this described below.\n+access to a flash device with the specifics of how the host is required to\n+control this described below.\n \n ## Version\n \n-Both version 1 and version 2 of the protocol are described below with version 2\n-specificities represented with V2 in brackets - (V2).\n+Version specific protocol functionalities are represented by the version number\n+in brackets next to the definition of the functionality. (e.g. (V2) for version\n+2 specific funtionality). All version specific functionality must also be\n+implemented by proceeding versions.\n \n ## Problem Overview\n \n \"mbox\" is the name we use to represent a protocol we have established between\n the host and the BMC via the Aspeed mailbox registers. This protocol is used\n-for the host to control the flash.\n+for the host to control access to the flash device(s).\n \n Prior to the mbox protocol, the host uses a backdoor into the BMC address space\n (the iLPC-to-AHB bridge) to directly manipulate the BMCs own flash controller.\n@@ -280,6 +282,14 @@ The host is not required to perform an erase before a write command and the\n BMC must ensure that a write performs as expected - that is if an erase is\n required before a write then the BMC must perform this itself.\n \n+The host may lock an area of flash using the MARK_LOCKED command. Any attempt\n+to mark dirty or erased this area of flash must fail with the LOCKED_ERROR\n+response code. The host may open a write window which contains a locked area\n+of flash however changes to a locked area of flash must never be written back\n+to the backing data source (i.e. that area of flash must be treated as read\n+only). An attempt to lock an area of flash which is not clean in the current\n+window must fail with PARAM_ERROR. (V3)\n+\n ### BMC Events\n \n The BMC can raise events with the host asynchronously to communicate to the\n@@ -316,6 +326,8 @@ MARK_WRITE_DIRTY 0x07\n WRITE_FLUSH 0x08\n BMC_EVENT_ACK 0x09\n MARK_WRITE_ERASED 0x0a\t(V2)\n+GET_FLASH_NAME 0x0b\t(V3)\n+MARK_LOCKED 0x0c\t(V3)\n ```\n \n ### Responses\n@@ -329,6 +341,7 @@ TIMEOUT\t\t5\n BUSY\t\t6\t(V2)\n WINDOW_ERROR\t7\t(V2)\n SEQ_ERROR\t8\t(V2)\n+LOCKED_ERROR\t9\t(V3)\n ```\n \n ### Sequence Numbers\n@@ -368,6 +381,10 @@ BUSY\t\t- Daemon in suspended state (currently unable to access flash)\n WINDOW_ERROR\t- Command not valid for active window or no active window\n \t\t- Try opening an appropriate window and retrying the command\n \n+SEQ_ERROR\t- Invalid sequence number supplied with command\n+\n+LOCKED_ERROR\t- Tried to mark dirty or erased locked area of flash\n+\n ### Information\n - All multibyte messages are LSB first (little endian)\n - All responses must have a valid return code in byte 13\n@@ -394,9 +411,7 @@ Sizes and addresses specified in blocks must be converted to bytes by\n multiplying by the block size.\n ```\n Command:\n-\tRESET_STATE\n-\tImplemented in Versions:\n-\t\tV1, V2\n+\tRESET_STATE (V1)\n \tArguments:\n \t\t-\n \tResponse:\n@@ -408,9 +423,7 @@ Command:\n \t\tpre mailbox protocol. Final behavior is still TBD.\n \n Command:\n-\tGET_MBOX_INFO\n-\tImplemented in Versions:\n-\t\tV1, V2\n+\tGET_MBOX_INFO (V1)\n \tArguments:\n \t\tV1:\n \t\tArgs 0: API version\n@@ -418,6 +431,10 @@ Command:\n \t\tV2:\n \t\tArgs 0: API version\n \n+\t\tV3:\n+\t\tArgs 0: API version\n+\t\tArgs 1: Requested block size (shift)\n+\n \tResponse:\n \t\tV1:\n \t\tArgs 0: API version\n@@ -430,6 +447,14 @@ Command:\n \t\tArgs 3-4: reserved\n \t\tArgs 5: Block size as power of two (encoded as a shift)\n \t\tArgs 6-7: Suggested Timeout (seconds)\n+\n+\t\tV3:\n+\t\tArgs 0: API version\n+\t\tArgs 1-2: reserved\n+\t\tArgs 3-4: reserved\n+\t\tArgs 5: Block size as power of two (encoded as a shift)\n+\t\tArgs 6-7: Suggested Timeout (seconds)\n+\t\tArgs 8: Num Allocated Flash IDs\n \tNotes:\n \t\tThe suggested timeout is a hint to the host as to how long\n \t\tit should wait after issuing a command to the BMC before it\n@@ -439,25 +464,32 @@ Command:\n \t\tthe BMC\tdoes not wish to provide a hint in which case the host\n \t\tmust choose some reasonable value.\n \n+\t\tThe host may require a specific block size and thus can request\n+\t\tthis by giving a hint to the daemon (may be zero). The daemon\n+\t\tmay use this to select the block size which it will use however\n+\t\tis free to ignore this. The value in the response is the block\n+\t\tsize which must be used for all further requests until a new\n+\t\tsize is\tnegotiated by another call to GET_MBOX_INFO. (V3)\n+\n Command:\n-\tGET_FLASH_INFO\n-\tImplemented in Versions:\n-\t\tV1, V2\n+\tGET_FLASH_INFO (V1)\n \tArguments:\n+\t\tV1, V2:\n \t\t-\n+\n+\t\tV3:\n+\t\tArgs 0: Flash ID\n \tResponse:\n \t\tV1:\n \t\tArgs 0-3: Flash size (bytes)\n \t\tArgs 4-7: Erase granule (bytes)\n \n-\t\tV2:\n+\t\tV2, V3:\n \t\tArgs 0-1: Flash size (blocks)\n \t\tArgs 2-3: Erase granule (blocks)\n \n Command:\n-\tCREATE_{READ/WRITE}_WINDOW\n-\tImplemented in Versions:\n-\t\tV1, V2\n+\tCREATE_{READ/WRITE}_WINDOW (V1)\n \tArguments:\n \t\tV1:\n \t\tArgs 0-1: Requested flash offset (blocks)\n@@ -466,11 +498,15 @@ Command:\n \t\tArgs 0-1: Requested flash offset (blocks)\n \t\tArgs 2-3: Requested flash size to access (blocks)\n \n+\t\tV3:\n+\t\tArgs 0-1: Requested flash offset (blocks)\n+\t\tArgs 2-3: Requested flash size to access (blocks)\n+\t\tArgs 4: Flash ID\n \tResponse:\n \t\tV1:\n \t\tArgs 0-1: LPC bus address of window (blocks)\n \n-\t\tV2:\n+\t\tV2, V3:\n \t\tArgs 0-1: LPC bus address of window (blocks)\n \t\tArgs 2-3: Window size (blocks)\n \t\tArgs 4-5: Flash offset mapped by window (blocks)\n@@ -504,9 +540,7 @@ Command:\n \t\twindow.\n \n Command:\n-\tCLOSE_WINDOW\n-\tImplemented in Versions:\n-\t\tV1, V2\n+\tCLOSE_WINDOW (V1)\n \tArguments:\n \t\tV1:\n \t\t-\n@@ -533,9 +567,7 @@ Command:\n \t\t\t\tevicted from the cache.\n \n Command:\n-\tMARK_WRITE_DIRTY\n-\tImplemented in Versions:\n-\t\tV1, V2\n+\tMARK_WRITE_DIRTY (V1)\n \tArguments:\n \t\tV1:\n \t\tArgs 0-1: Flash offset to mark from base of flash (blocks)\n@@ -544,6 +576,7 @@ Command:\n \t\tV2:\n \t\tArgs 0-1: Window offset to mark (blocks)\n \t\tArgs 2-3: Number to mark dirty at offset (blocks)\n+\t\tArgs 4 : Don't Erase Before Write (V3)\n \n \tResponse:\n \t\t-\n@@ -558,10 +591,15 @@ Command:\n \t\tblock. If the offset + number exceeds the size of the active\n \t\twindow then the command must not succeed.\n \n+\t\tThe host can give a hint to the daemon that is doesn't have to\n+\t\terase a flash area before writing to it by setting ARG[4]. This\n+\t\tmeans that the daemon will blindly perform a write to that area\n+\t\tand will not try to erase it before hand. This can be used if\n+\t\tthe host knows that a large area has already been erased for\n+\t\texample but then wants to perform many small writes.\n+\n Command\n-\tWRITE_FLUSH\n-\tImplemented in Versions:\n-\t\tV1, V2\n+\tWRITE_FLUSH (V1)\n \tArguments:\n \t\tV1:\n \t\tArgs 0-1: Flash offset to mark from base of flash (blocks)\n@@ -585,9 +623,7 @@ Command\n \n \n Command:\n-\tBMC_EVENT_ACK\n-\tImplemented in Versions:\n-\t\tV1, V2\n+\tBMC_EVENT_ACK (V1)\n \tArguments:\n \t\tArgs 0:\tBits in the BMC status byte (mailbox data\n \t\t\tregister 15) to ack\n@@ -598,9 +634,7 @@ Command:\n \t\tsupplied in mailbox register 15.\n \n Command:\n-\tMARK_WRITE_ERASED\n-\tImplemented in Versions:\n-\t\tV2\n+\tMARK_WRITE_ERASED (V2)\n \tArguments:\n \t\tV2:\n \t\tArgs 0-1: Window offset to erase (blocks)\n@@ -617,6 +651,31 @@ Command:\n \t\tnumber is the number of blocks of the active window to erase\n \t\tstarting at offset. If the offset + number exceeds the size of\n \t\tthe active window then the command must not succeed.\n+\n+Command:\n+\tGET_FLASH_NAME (V3)\n+\tArguments:\n+\t\tArgs 0: Flash ID\n+\tResponse:\n+\t\tArgs 0-10: Flash Name / UID\n+\tNotes:\n+\t\tDescribes a flash with some kind of identifier useful to the\n+\t\thost system. This is typically a null-padded string.\n+\n+Command:\n+\tMARK_LOCKED (V3)\n+\tArguments:\n+\t\tArgs 0-1: Flash offset to lock (blocks)\n+\t\tArgs 2-3: Number to lock at offset (blocks)\n+\t\tArgs 4: Flash ID\n+\tResponse:\n+\t\t-\n+\tNotes:\n+\t\tLock an area of flash so that the host can't mark it dirty or\n+\t\terased. If the requested area is within the current window and\n+\t\tthat area is currently marked dirty or erased then this command\n+\t\tmust fail.\n+\n ```\n \n ### BMC Events in Detail:\n","prefixes":["RFC"]}