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