1Copyright 2017 IBM 2 3Licensed under the Apache License, Version 2.0 (the "License"); 4you may not use this file except in compliance with the License. 5You may obtain a copy of the License at 6 7 http://www.apache.org/licenses/LICENSE-2.0 8 9Unless required by applicable law or agreed to in writing, software 10distributed under the License is distributed on an "AS IS" BASIS, 11WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12See the License for the specific language governing permissions and 13limitations under the License. 14 15MBOX 16==== 17 18This repo contains the protocol definition for the host to BMC mailbox 19communication specification which can be found in 20Documentation/mbox_procotol.md. 21 22There is also a reference implementation of a BMC mailbox daemon, the details 23of which can be found in Documentation/mboxd.md. 24 25Finally there is also an implementation of a mailbox daemon control program, the 26details of which can be found in Documentation/mboxctl.md. 27 28Building 29======== 30 31The build system is a standard autotools setup. `bootstrap.sh` runs all the 32jobs necessary to initialise autotools. 33 34By default mboxd is configured and built _without_ the 'virtual PNOR' feature 35discussed below. The virtual PNOR functionality is written in C++, and due to 36some autotools clunkiness even if it is disabled mboxd will still be linked 37with `CXX`. Point `CXX` to `cc` at configure time if you do not have a C++ 38compiler for your target (`./configure CXX=cc`). 39 40If you are hacking on the reference implementation it's recommended to run 41`bootstrap.sh` with the `dev` argument: 42 43``` 44$ ./bootstrap.sh dev 45$ ./configure 46$ make 47$ make check 48``` 49 50This will turn on several of the compiler's sanitizers to help find bad memory 51management and undefined behaviour in the code via the test suites. 52 53Otherwise, build with: 54 55``` 56$ ./bootstrap.sh 57$ ./configure 58$ make 59$ make check 60``` 61 62In addition to its role as a flash abstraction `mboxd` can also serve as a 63partition/filesystem abstraction. This feature is known as 'virtual PNOR' and 64it can be enabled at `configure` time (note that this requires a C++ compiler 65for your target): 66 67``` 68$ ./bootstrap.sh 69$ ./configure --enable-virtual-pnor 70$ make 71$ make check 72``` 73 74Style Guide 75=========== 76 77Preamble 78-------- 79 80This codebase is a mix of C (due to its heritage) and C++. This is an ugly 81split: message logging and error handling can be vastly different inside the 82same codebase. The aim is to remove the split one way or the other over time 83and have consistent approaches to solving problems. 84 85phosphor-mboxd is developed as part of the OpenBMC project, which also leads to 86integration of frameworks such as 87[phosphor-logging](https://github.com/openbmc/phosphor-logging). Specifically 88on phosphor-logging, it's noted that without care we can achieve absurd 89duplication or irritating splits in where errors are reported, as the C code is 90not capable of making use of the interfaces provided. 91 92Rules 93----- 94 951. Message logging MUST be done to stdout or stderr, and MUST NOT be done 96 directly via journal APIs or wrappers of the journal APIs. 97 98 Rationale: 99 100 We have two scenarios where we care about output, with the important 101 restriction that the method must be consistent between C and C++: 102 103 1. Running in-context on an OpenBMC-based system 104 2. Running the test suite 105 106 In the first case it is desirable that the messages appear in the system 107 journal. To this end, systemd will by default capture stdout and stderr of 108 the launched binary and redirect it to the journal. 109 110 In the second case it is *desirable* that messages be captured by the test 111 runner (`make check`) for test failure analysis, and it is *undesirable* for 112 messages to appear in the system journal (as these are tests, not issues 113 affecting the health of the system they are being executed on). 114 115 Therefore direct calls to the journal MUST be avoided for the purpose of 116 message logging. 117 118 Note: This section specifically targets the use of phosphor-logging's 119 `log<T>()`. It does not prevent the use of `elog<T>()`. 120