Name Date Size #Lines LOC

..--

Documentation/H--1,6321,222

file/H--291196

m4/H--

mtd/H--396249

test/H--2,9582,036

vpnor/H--4,4543,005

.clang-format-cH A D08-Mar-2018141 76

.clang-format-c++H A D11-Oct-20182.8 KiB10098

.gitignoreH A D25-Mar-2018781 6251

.markdownlint.yamlH A D12-Jun-2025135 76

LICENSEH A D13-Oct-201611.1 KiB202169

Makefile.amH A D12-Mar-20201.2 KiB6144

OWNERSH A D21-Nov-20241.8 KiB5651

README.mdH A D25-Jun-20254 KiB11584

backend.hH A D25-Jul-20237.5 KiB286141

bootstrap.shH A D04-Dec-20222 KiB6947

common.cH A D25-Oct-20241.3 KiB7757

common.hH A D03-Aug-20181.8 KiB11077

configure.acH A D16-Jun-20223.8 KiB8574

control.cH A D25-Jul-20233.1 KiB148100

control_dbus.cH A D25-Jul-20236.2 KiB260213

control_dbus.hH A D14-Mar-2019849 2518

control_legacy.cH A D25-Jul-20237.8 KiB321208

dbus.hH A D19-Aug-20181.3 KiB4722

format-code.shH A D22-Jul-20221.4 KiB4211

lpc.cH A D14-Mar-20194.5 KiB182130

lpc.hH A D13-Mar-2019345 158

mboxctl.cH A D04-Apr-20199.1 KiB429354

mboxd.cH A D25-Jul-202310.7 KiB483404

mboxd.hH A D18-Nov-20182.6 KiB11373

mtd.cH A D26-Feb-2018773 4634

protocol.cH A D25-Jul-202320.3 KiB768537

protocol.hH A D14-Mar-20192.7 KiB134109

transport.hH A D31-Oct-2018431 1811

transport_dbus.cH A D25-Jul-202313 KiB543448

transport_dbus.hH A D31-Oct-2018350 158

transport_mbox.cH A D25-Jul-202317.8 KiB700412

transport_mbox.hH A D31-Oct-20181.4 KiB6145

windows.cH A D25-Jul-202319.1 KiB670383

windows.hH A D28-Aug-20182 KiB6043

README.md

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```shell
25./bootstrap.sh dev
26./configure
27make
28make 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```shell
37./bootstrap.sh
38./configure
39make
40make 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```shell
50./bootstrap.sh
51./configure CXX=cc --disable-virtual-pnor
52make
53make 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   1. Running in-context on an OpenBMC-based system
84   2. Running the test suite
85
86   In the first case it is desirable that the messages appear in the system
87   journal. To this end, systemd will by default capture stdout and stderr of
88   the launched binary and redirect it to the journal.
89
90   In the second case it is _desirable_ that messages be captured by the test
91   runner (`make check`) for test failure analysis, and it is _undesirable_ for
92   messages to appear in the system journal (as these are tests, not issues
93   affecting the health of the system they are being executed on).
94
95   Therefore direct calls to the journal MUST be avoided for the purpose of
96   message logging.
97
98   Note: This section specifically targets the use of phosphor-logging's
99   `log<T>()`. It does not prevent the use of `elog<T>()`.
100
101## License and Copyright
102
103Copyright 2017 IBM
104
105Licensed under the Apache License, Version 2.0 (the "License"); you may not use
106this file except in compliance with the License. You may obtain a copy of the
107License at
108
109<http://www.apache.org/licenses/LICENSE-2.0>
110
111Unless required by applicable law or agreed to in writing, software distributed
112under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR
113CONDITIONS OF ANY KIND, either express or implied. See the License for the
114specific language governing permissions and limitations under the License.
115