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 28Style Guide 29=========== 30 31Preamble 32-------- 33 34This codebase is a mix of C (due to its heritage) and C++. This is an ugly 35split: message logging and error handling can be vastly different inside the 36same codebase. The aim is to remove the split one way or the other over time 37and have consistent approaches to solving problems. 38 39phosphor-mboxd is developed as part of the OpenBMC project, which also leads to 40integration of frameworks such as 41[phosphor-logging](https://github.com/openbmc/phosphor-logging). Specifically 42on phosphor-logging, it's noted that without care we can achieve absurd 43duplication or irritating splits in where errors are reported, as the C code is 44not capable of making use of the interfaces provided. 45 46Rules 47----- 48 491. Message logging MUST be done to stdout or stderr, and MUST NOT be done 50 directly via journal APIs or wrappers of the journal APIs. 51 52 Rationale: 53 54 We have two scenarios where we care about output, with the important 55 restriction that the method must be consistent between C and C++: 56 57 1. Running in-context on an OpenBMC-based system 58 2. Running the test suite 59 60 In the first case it is desirable that the messages appear in the system 61 journal. To this end, systemd will by default capture stdout and stderr of 62 the launched binary and redirect it to the journal. 63 64 In the second case it is *desirable* that messages be captured by the test 65 runner (`make check`) for test failure analysis, and it is *undesirable* for 66 messages to appear in the system journal (as these are tests, not issues 67 affecting the health of the system they are being executed on). 68 69 Therefore direct calls to the journal MUST be avoided for the purpose of 70 message logging. 71 72 Note: This section specifically targets the use of phosphor-logging's 73 `log<T>()`. It does not prevent the use of `elog<T>()`. 74