├── release └── metrics │ ├── 2022-07 │ ├── 2019-11 │ ├── 2020-03 │ └── 2020-01 ├── style ├── json │ └── .eslintrc.json ├── javascript │ └── .clang-format ├── cpp │ ├── .clang-tidy │ ├── tidy-desired.md │ └── .clang-format └── c │ └── .clang-format ├── .markdownlint.yaml ├── .prettierrc.yaml ├── designs ├── entity-manager.md ├── README.md ├── unique-hostname.md ├── oem │ ├── ibm │ │ ├── OWNERS │ │ └── system-power-mode.md │ └── google │ │ └── root_of_trust.md ├── redfish-pcie.md ├── phosphor-hwmon-refactoring.md ├── platform-init.md ├── management-console │ ├── service-discovery.md │ └── Authorities_List_Management.md ├── thermal-control-modes.md ├── nmi-dbus-interface.md ├── ci-authorization.md ├── firmware-update-via-usb.md ├── virtual-sensors.md ├── certificate-revocation-list.md ├── sol-sysrq.md ├── cper-records.md ├── bmc-reboot-cause-update.md ├── cable-monitor.md ├── bmc-boot-ready.md ├── design-template.md ├── ecc-dbus-sel.md └── ncsi-coredump.md ├── subtree.md ├── Makefile ├── openbmc-conversion.md ├── userguide └── userguide.tex ├── development ├── README.md ├── gerrit-setup.md └── web-ui.md ├── console.md ├── discord-rules.md ├── glossary.md ├── security ├── obmc-github-security-advisory-template.md ├── obmc-security-response-team.md └── how-to-report-a-security-vulnerability.md ├── README.md ├── maintainer-workflow.md ├── OWNERS ├── SECURITY.md ├── architecture ├── code-update │ ├── code-update-diagrams.md │ └── host-code-update.md ├── optionality.md └── redfish-logging-in-bmcweb.md ├── logo ├── OpenBMC-Logo.svg └── OpenBMC-Logo2.svg ├── features.md ├── testing ├── run-test-docker.md └── local-ci-build.md ├── yocto-development.md ├── kernel-development.md └── tof └── contract.md /release/metrics/2022-07: -------------------------------------------------------------------------------- 1 | -------------------------------------------------------------------------------- /style/json/.eslintrc.json: -------------------------------------------------------------------------------- 1 | { 2 | "extends": ["plugin:json/recommended-with-comments"] 3 | } 4 | -------------------------------------------------------------------------------- /style/javascript/.clang-format: -------------------------------------------------------------------------------- 1 | --- 2 | Language: JavaScript 3 | BasedOnStyle: Google 4 | ColumnLimit: 80 5 | ... 6 | -------------------------------------------------------------------------------- /.markdownlint.yaml: -------------------------------------------------------------------------------- 1 | default: true 2 | MD013: false 3 | MD024: 4 | siblings_only: true 5 | MD033: 6 | allowed_elements: ["br", "sub", "sup"] 7 | -------------------------------------------------------------------------------- /.prettierrc.yaml: -------------------------------------------------------------------------------- 1 | tabWidth: 4 2 | printWidth: 80 3 | proseWrap: "always" 4 | overrides: 5 | - files: "*.md" 6 | options: 7 | tabWidth: 2 8 | -------------------------------------------------------------------------------- /designs/entity-manager.md: -------------------------------------------------------------------------------- 1 | # Entity Manager 2 | 3 | Design is described in the 4 | [README.md](https://github.com/openbmc/entity-manager/blob/master/README.md) of 5 | the repo. 6 | -------------------------------------------------------------------------------- /designs/README.md: -------------------------------------------------------------------------------- 1 | # Overview 2 | 3 | This is a directory of design documents. 4 | 5 | Newly authored design documents are encouraged to follow the 6 | [design document template](design-template.md). 7 | -------------------------------------------------------------------------------- /style/cpp/.clang-tidy: -------------------------------------------------------------------------------- 1 | Checks: '-*, 2 | bugprone-unchecked-optional-access, 3 | modernize-use-nullptr, 4 | ' 5 | 6 | HeaderFilterRegex: '(?!^subprojects).*' 7 | 8 | WarningsAsErrors: '*' 9 | 10 | -------------------------------------------------------------------------------- /subtree.md: -------------------------------------------------------------------------------- 1 | # Subtree Architecture 2 | 3 | In the past, meta-layer repositories were added to the repo as subtrees. This is 4 | no longer the case. Although the individual meta-\* trees still exist in gerrit 5 | and github for the sake of keeping a complete history, they should not be used, 6 | and new meta layers will simply be checked in within the openbmc/openbmc code 7 | tree. 8 | -------------------------------------------------------------------------------- /Makefile: -------------------------------------------------------------------------------- 1 | # To build: 2 | # $ apt install fonts-linuxlibertine texlive-xetex pandoc 3 | # $ make 4 | 5 | # we need xelatex for utf-8 support 6 | tex = xelatex 7 | tflags = -interaction=nonstopmode -halt-on-error 8 | 9 | all: userguide.pdf 10 | 11 | .PHONY: all clean 12 | 13 | userguide.pdf: userguide/userguide.tex 14 | $(tex) $(tflags) $^ 15 | $(tex) $(tflags) $^ 16 | 17 | userguide/userguide.tex: rest-api.tex host-management.tex console.tex architecture/code-update/code-update.tex 18 | 19 | %.tex: %.md 20 | pandoc -o $@ $^ 21 | 22 | clean: 23 | rm -f *.tex userguide.* 24 | -------------------------------------------------------------------------------- /openbmc-conversion.md: -------------------------------------------------------------------------------- 1 | # Converting to OpenBMC from AMI firmware 2 | 3 | Often a number of steps are required to convert from the AMI firmware to 4 | OpenBMC. These steps are documented for various machines below. 5 | 6 | ## Palmetto 7 | 8 | 1. Upgrade the firmware flash chip to 256Mb (32MB) part (MX25L25635E or 9 | equivalent) 10 | 2. [Build](cheatsheet.md#building-for-palmetto) and flash the `image-bmc` output 11 | to the 256Mb flash chip 12 | 3. Replace existing flash chip on the motherboard (cradle closest to the 13 | battery) 14 | 4. Manufacture a cable to connect to the COM2 header for the BMC console. COM2 15 | is wired for a DB-9-style pin-out. 16 | 5. Reconfigure both `BMC_DEBUG1` (TX) and `BMC_DEBUG2` (RX) jumpers to short 17 | pins 2-3. 18 | 6. Boot OpenBMC on your Palmetto. The console runs at 115200baud. 19 | -------------------------------------------------------------------------------- /userguide/userguide.tex: -------------------------------------------------------------------------------- 1 | \documentclass[]{article} 2 | 3 | % fonts: libertine for roman text, inconsolata for monospace 4 | \usepackage{fontspec} 5 | \setmainfont{Linux Libertine O} 6 | \setmonofont{Inconsolata} 7 | 8 | % page layout: full page, no paragraph indent 9 | \usepackage{fullpage} 10 | \usepackage{parskip} 11 | 12 | % document metadata 13 | \usepackage{hyperref} 14 | \hypersetup{ 15 | pdftitle={OpenBMC User’s Guide}, 16 | colorlinks=true, 17 | urlcolor=blue 18 | } 19 | 20 | % workaround for pandoc / xetex version differences 21 | \providecommand{\tightlist}{% 22 | \setlength{\itemsep}{0pt}\setlength{\parskip}{0pt}} 23 | 24 | \begin{document} 25 | 26 | \title{OpenBMC User's Guide} 27 | \maketitle 28 | 29 | \input{rest-api} 30 | \input{host-management} 31 | \input{console} 32 | \input{architecture/code-update/code-update} 33 | 34 | \end{document} 35 | -------------------------------------------------------------------------------- /development/README.md: -------------------------------------------------------------------------------- 1 | # OpenBMC Developer Documentation 2 | 3 | This directory is focused on providing OpenBMC developers with the instructions 4 | they need to get up and going with OpenBMC development. This can be reviewed in 5 | any order you like, but the recommended flow can be found below. 6 | 7 | 1. [Development Environment Setup](dev-environment.md) 8 | 9 | Start here. This shows how to setup an OpenBMC development environment using 10 | its bitbake build process and how to start the software emulator, QEMU. 11 | 12 | 2. [Hello World](devtool-hello-world.md) 13 | 14 | This shows how to use the yocto tool, devtool, to extract an OpenBMC source 15 | repository, build, and test your changes within QEMU. 16 | 17 | 3. [Web UI Development](web-ui.md) 18 | 19 | This shows how to modify the phosphor-webui web application and test your 20 | changes within QEMU. 21 | 22 | 4. [Code Reviews Using Gerrit](gerrit-setup.md) 23 | 24 | This shows how to setup your environment to utilize Gerrit for submitting 25 | your changes for code review. 26 | -------------------------------------------------------------------------------- /designs/unique-hostname.md: -------------------------------------------------------------------------------- 1 | # Setting a unique hostname to the BMC machine on first boot 2 | 3 | Author: Asmitha KR 4 | 5 | Other contributors: None 6 | 7 | Created: 2019-05-07 8 | 9 | ## Problem Description 10 | 11 | In OpenBMC, the hostname discovery is done by the avahi Dbus service at the 12 | startup. In a network where there are multiple OpenBMC machines, avahi keeps 13 | getting the hostname conflict and the service name conflict. Hence, the problem 14 | is to find a solution that resolves these conflicts. 15 | 16 | ## Background and References 17 | 18 | The detailed issue regarding the hostname and service name conflicts is 19 | described in the following links. 20 | 21 | - 22 | - 23 | - 24 | 25 | ## Requirements 26 | 27 | None. 28 | 29 | ## Proposed Design 30 | 31 | To solve this, we are proposing a service which assigns a unique hostname to the 32 | BMC and runs on the very first boot. one of the ways to generate the unique 33 | hostname is to append the Serial Number retrieved from Inventory Manager to the 34 | existing default hostname. 35 | 36 | ## Alternatives Considered 37 | 38 | None. 39 | 40 | ## Impacts 41 | 42 | None. 43 | 44 | ## Testing 45 | 46 | None. 47 | -------------------------------------------------------------------------------- /style/cpp/tidy-desired.md: -------------------------------------------------------------------------------- 1 | # Desired clang-tidy checks 2 | 3 | The following file contains checks and settings that the project would like to 4 | enable, but has had trouble either in engineering or has other higher priority 5 | rework. There is general agreement that the below checks _should_ be useful, but 6 | have not concretely enabled them across the project. 7 | 8 | ```yaml 9 | Checks: "-*, readability-function-size, 10 | readability-function-cognitive-complexity 11 | " 12 | 13 | CheckOptions: 14 | - key: readability-function-size.LineThreshold 15 | value: 60 # [1] 16 | - key: readability-function-size.ParameterThreshold 17 | value: 6 # [2] 18 | - key: readability-function-cognitive-complexity.Threshold 19 | value: 25 # [3] 20 | 21 | 22 | # [1] https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#f3-keep-functions-short-and-simple 23 | # [2] https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#f2-a-function-should-perform-a-single-logical-operation 24 | # [3] https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#f3-keep-functions-short-and-simple 25 | # However cognitive complexity != cyclomatic complexity. Therefore using the clang-tidy default value, 26 | # as cyclomatic complexity seems to not be implemented in clang-tidy. 27 | 28 | # [1],[2],[3] do not have to be enforced or applied project-wide yet. 29 | ``` 30 | -------------------------------------------------------------------------------- /console.md: -------------------------------------------------------------------------------- 1 | # OpenBMC host console support 2 | 3 | This document describes how to connect to the host UART console from an OpenBMC 4 | management system. 5 | 6 | The console infrastructure allows multiple shared connections to a single host 7 | UART. UART data from the host is output to all connections, and input from any 8 | connection is sent to the host. 9 | 10 | ## Remote console connections 11 | 12 | To connect to an OpenBMC console session remotely, just ssh to your BMC on 13 | port 2200. Use the same login credentials you would for a normal ssh session: 14 | 15 | ```bash 16 | ssh -p 2200 [user]@[bmc-hostname] 17 | ``` 18 | 19 | ## Local console connections 20 | 21 | If you're already logged into an OpenBMC machine, you can start a console 22 | session directly, using: 23 | 24 | ```bash 25 | obmc-console-client 26 | ``` 27 | 28 | To exit from a console, type: 29 | 30 | ```text 31 | return ~ . 32 | ``` 33 | 34 | Note that if you're on an ssh connection, you'll need to 'escape' the ~ 35 | character, by entering it twice: 36 | 37 | ```text 38 | return ~ ~ . 39 | ``` 40 | 41 | This is because obmc-console-client is an ssh session, and a double `~` is 42 | required to escape the "inner" (obmc-console-client) ssh session. 43 | 44 | ## Logging 45 | 46 | Console logs are kept in: `/var/log/obmc-console.log` 47 | 48 | This log is limited in size, and will wrap after hitting that limit (currently 49 | set at 16kB). 50 | -------------------------------------------------------------------------------- /discord-rules.md: -------------------------------------------------------------------------------- 1 | # Discord Rules 2 | 3 | 1. This community works together to build an Open Source BMC firmware. It's a 4 | community expectation that you will provide access to your code in the course 5 | of discussions. We are unable to build together if you are unable to share 6 | your code. The community is not a substitute for a support contract. 7 | 8 | 2. OpenBMC community members are volunteering their time to answer your 9 | questions. Please keep this in mind if you are waiting for a response. 10 | 11 | 3. All support questions must be asked in public channels. Do not send uninvited 12 | private messages to other community members. Private requests for help place 13 | an unfair burden of expectation on people volunteering their time. Further, 14 | others in the community cannot help if they cannot see the question. 15 | 16 | 4. Don't post the same question in multiple channels. Doing so fragments the 17 | conversation. If you're unsure of which channel to use, ask your question in 18 | `#general` and we may redirect you elsewhere. 19 | 20 | 5. Reflect on whether your standing in the community is appropriate for the help 21 | you are requesting. If you are new to the community, you will likely have the 22 | most success by asking detailed, specific questions about detailed, specific 23 | problems. Vague questions by unfamiliar people often go unanswered 24 | 25 | 6. Do not discuss undisclosed bugs that may have a security impact in Discord. 26 | Instead, email `openbmc-security@lists.ozlabs.org` and follow the [documented 27 | directions][1] 28 | 29 | [1]: 30 | https://github.com/openbmc/docs/blob/master/security/how-to-report-a-security-vulnerability.md 31 | -------------------------------------------------------------------------------- /glossary.md: -------------------------------------------------------------------------------- 1 | # Glossary 2 | 3 | Guidelines: 4 | 5 | - Include terms specific to the OpenBMC project, OpenBMC reference platforms 6 | (like OpenPower or ASpeed), BMCs, or platform management. 7 | - Include terms needed to disambiguate. For example, "image" may refer to a 8 | visual (e.g., JPEG) image or a firmware (e.g. UBIFS) image. 9 | - Treat acronyms the same as terms. 10 | 11 | BMC - Baseboard management controller. A device designed to enable remote out of 12 | band management access to a host, generally a computer system. 13 | 14 | D-Bus - Provides the primary mechanisms for inter-process communication with an 15 | OpenBMC system. OpenBMC D-Bus APIs are documented in 16 | `https://github.com/openbmc/phosphor-dbus-interfaces`. For example, see the tree 17 | under `/xyz/openbmc_project/Led`. 18 | 19 | IPMI - Intelligent Platform Management Interface. OpenBMC implements a subset of 20 | the IPMI spec. 21 | 22 | ODM - Original design manufacturer. In OpenBMC, ODM generally refers to the 23 | manufacturer of the host system. 24 | 25 | OEM - Original equipment manufacturer. In OpenBMC, OEM generally refers to the 26 | manufacturer of the host system. 27 | 28 | Phosphor - Informally designates OpenBMC software or APIs designed for use 29 | across many systems, as distinct from platform or vendor-specific elements. 30 | 31 | Redfish - The Distributed Management Task Force (DTMF) Redfish specification. 32 | OpenBMC provides Redfish REST APIs for platform management. 33 | 34 | REST - Representational State Transfer. OpenBMC provides REST APIs. 35 | 36 | SDR - IPMI Sensor Data Record. 37 | 38 | SEL - IMPI System Event Log. The BMC stores SEL events. 39 | 40 | Server - A computing device, generally the one served by the BMC. 41 | -------------------------------------------------------------------------------- /designs/oem/ibm/OWNERS: -------------------------------------------------------------------------------- 1 | # OWNERS 2 | # ------ 3 | # 4 | # The OWNERS file maintains the list of individuals responsible for various 5 | # parts of this repository, including code review and approval. We use the 6 | # Gerrit 'owners' plugin, which consumes this file, along with some extra 7 | # keywords for our own purposes and tooling. 8 | # 9 | # For details on the configuration used by 'owners' see: 10 | # https://gerrit.googlesource.com/plugins/owners/+/refs/heads/master/owners/src/main/resources/Documentation/config.md 11 | # 12 | # An OWNERS file must be in the root of a repository but may also be present 13 | # in any subdirectory. The contents of the subdirectory OWNERS file are 14 | # combined with parent directories unless 'inherit: false' is set. 15 | # 16 | # The owners file is YAML and has [up to] 4 top-level keywords. 17 | # * owners: A list of individuals who have approval authority on the 18 | # repository. 19 | # 20 | # * reviewers: A list of individuals who have requested review notification 21 | # on the repository. 22 | # 23 | # * matchers: A list of specific file/path matchers for granular 'owners' and 24 | # 'reviewers'. See 'owners' plugin documentation. 25 | # 26 | # * openbmc: A list of openbmc-specific meta-data about owners and reviewers. 27 | # - name: preferred name of the individual. 28 | # - email: preferred email address of the individual. 29 | # - discord: Discord nickname of the individual. 30 | # 31 | # It is expected that these 4 sections will be listed in the order above and 32 | # data within them will be kept sorted. 33 | 34 | owners: 35 | - geissonator@yahoo.com 36 | - gunnar@gmills.xyz 37 | 38 | reviewers: 39 | 40 | matchers: 41 | 42 | openbmc: 43 | - name: Andrew Geissler 44 | email: geissonator@yahoo.com 45 | discord: geissonator 46 | - name: Gunnar Mills 47 | email: gunnar@gmills.xyz 48 | discord: GunnarM 49 | -------------------------------------------------------------------------------- /security/obmc-github-security-advisory-template.md: -------------------------------------------------------------------------------- 1 | # OpenBMC Security Advisory Template 2 | 3 | This has guidelines for OpenBMC repository maintainers to follow when creating 4 | new draft GitHub security advisories as part of the [Security response team 5 | guidelines][]. 6 | 7 | Note that the sections under the "Description" section are intended for the 8 | security advisory "Description" field 9 | 10 | [security response team guidelines]: ./obmc-security-response-team-guidelines.md 11 | 12 | ## Affected Product 13 | 14 | - Ecosystem: Other 15 | - OpenBMC Package name: `TBD` 16 | - Affected versions: 2.9 17 | - Patched versions: `TBD` 18 | 19 | ## Severity 20 | 21 | Assess the severity using CVSS. 22 | 23 | ## CWE 24 | 25 | `TBD` 26 | 27 | ## CVE identifier 28 | 29 | Please coordinate with the security response team 30 | 31 | ## Credits 32 | 33 | Attribution to those that discovered and mitigated the vulnerability. 34 | 35 | ### Title 36 | 37 | Title goes here... 38 | 39 | ### Description 40 | 41 | The description will be used by vulnerability analysts and should include the 42 | area or the function affected, and a description of the issue. There should be 43 | enough details to differentiate this from similar problems, but not enough 44 | detail to help an attacker exploit the problem. 45 | 46 | ### Proof Of Concept 47 | 48 | If provided, insert proof of concept here. 49 | 50 | ### Vulnerability Description 51 | 52 | ...can cause denial of service. 53 | 54 | ### Affected Release 55 | 56 | OpenBMC 2.9 57 | 58 | ### Fixed in Release 59 | 60 | Please include the commit-id in the affected repo, the commit id for the 61 | metadata, or the version number. 62 | 63 | ### Mitigation 64 | 65 | If available, describe or provide a link to the mitigation needed until the fix 66 | can be applied. 67 | 68 | ### For more information 69 | 70 | If you have any questions or comments about this advisory: 71 | 72 | - Email openbmc-security at lists.ozlabs.org 73 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # OpenBMC documentation 2 | 3 | The [OpenBMC project](https://www.openbmc.org/) is a Linux Foundation project 4 | whose goal is to produce a customizable, open-source firmware stack for 5 | Baseboard Management Controllers (BMCs). This repository contains documentation 6 | for OpenBMC as a whole. There may be component-specific documentation in the 7 | repository for each component. 8 | 9 | The [features](features.md) document lists the project's major features with 10 | links to more information. 11 | 12 | ## Contact 13 | 14 | - Mail: `openbmc@lists.ozlabs.org` 15 | - List Archive: 16 | - Discord: 17 | 18 | ## OpenBMC Development 19 | 20 | These documents contain details on developing OpenBMC code itself 21 | 22 | - [cheatsheet.md](cheatsheet.md): Quick reference for some common development 23 | tasks 24 | 25 | - [CONTRIBUTING.md](CONTRIBUTING.md): Guidelines for contributing to OpenBMC 26 | 27 | - [development tutorials](development/README.md): Tutorials for getting up to 28 | speed on OpenBMC development 29 | 30 | - [kernel-development.md](kernel-development.md): Reference for common kernel 31 | development tasks 32 | 33 | ## OpenBMC Usage 34 | 35 | These documents describe how to use OpenBMC, including using the programmatic 36 | interfaces to an OpenBMC system. 37 | 38 | - [code-update](architecture/code-update): Updating OpenBMC and host platform 39 | firmware 40 | 41 | - [console.md](console.md): Using the host console 42 | 43 | - [host-management.md](host-management.md): Performing host management tasks 44 | with OpenBMC 45 | 46 | - [rest-api.md](rest-api.md): Introduction to using the OpenBMC REST API 47 | 48 | - [REDFISH-cheatsheet.md](REDFISH-cheatsheet.md): Quick reference for some 49 | common OpenBMC Redfish commands 50 | 51 | - [REST-cheatsheet.md](REST-cheatsheet.md): Quick reference for some common 52 | OpenBMC REST API commands 53 | -------------------------------------------------------------------------------- /security/obmc-security-response-team.md: -------------------------------------------------------------------------------- 1 | # The OpenBMC security vulnerability reporting process 2 | 3 | This describes the OpenBMC security vulnerability reporting process which is 4 | intended to give the project time to address security problems before public 5 | disclosure. 6 | 7 | The main pieces are: 8 | 9 | - a procedure to privately report security vulnerabilities 10 | - a security response team to address reported vulnerabilities 11 | - the openbmc-security email address for the response team 12 | - guidelines for security response team members 13 | 14 | The basic workflow is: 15 | 16 | 1. A community member reports a problem privately to the security response team 17 | (and to the repository maintainers if known). 18 | 2. The responders (including the security response team, the repository 19 | maintainers, and the problem submitter) work to understand the problem. 20 | 3. The repository maintainer creates an OpenBMC security advisory which explains 21 | the problem, its severity, and how to protect your systems that were built on 22 | OpenBMC. 23 | 4. The responders privately engage community members to create workarounds and 24 | fixes and to negotiate disclosure dates. 25 | 5. The OpenBMC security advisory is published along with any accompanying CVEs. 26 | 27 | Note that the OpenBMC security response team is distinct from the OpenBMC 28 | security working group which remains completely open. 29 | 30 | The 31 | [How to privately report a security vulnerability](./how-to-report-a-security-vulnerability.md) 32 | web page explains how OpenBMC community members can report a security 33 | vulnerability and get a fix for it before public announcement of the 34 | vulnerability. 35 | 36 | The `openbmc-security at lists.ozlabs.org` email address is the primary 37 | communication vehicle between the person who reported the problem and the 38 | security response team, and the initial communication between the security 39 | response team members. 40 | 41 | The 42 | [Guidelines for security response team members](./obmc-security-response-team-guidelines.md) 43 | contain collected wisdom for the response team and community members who are 44 | working to fix the problem. 45 | -------------------------------------------------------------------------------- /maintainer-workflow.md: -------------------------------------------------------------------------------- 1 | # OpenBMC Maintainer/CLA Workflow 2 | 3 | OpenBMC contributors are required to execute an OpenBMC CLA (Contributor License 4 | Agreement) before their contributions can be accepted. This page is a checklist 5 | for sub-project maintainers to follow before approving patches. 6 | 7 | - Manually verify the contributor has signed the ICLA (individual) or is listed 8 | on an existing CCLA (corporate). 9 | - Executed CLAs can be found [in the CLA repository][1]. 10 | - If you were not added to the appropriate CLA repository ACL send an email to 11 | `openbmc@lists.ozlabs.org` with a request to be added. 12 | - If a CLA for the contributor is found, accept the patch(1). 13 | - If a CLA is not found, request that the contributor execute one and send it to 14 | `manager@lfprojects.org`. 15 | - Do not accept the patch(1) until a signed CLA (individual _or_ corporate) 16 | has been uploaded to the CLA repository. 17 | - The CCLA form can be found at [CCLA template][2]. 18 | - The ICLA form can be found at [ICLA template][3]. 19 | 20 | An executed OpenBMC CLA is _not_ required to accept contributions to OpenBMC 21 | forks of upstream projects, like the Linux kernel or U-Boot. 22 | 23 | Review the maintainers' responsibilities in the 24 | [contributing guidelines](./CONTRIBUTING.md). Maintainers are ultimately 25 | responsible for sorting out open source license issues, issues with using code 26 | copied from the web, and maintaining the quality of the code. 27 | 28 | Repository maintainers ought to have the following traits as recognized by a 29 | consensus of their peers: 30 | 31 | - responsible: have a continuing desire to ensure only high-quality code goes 32 | into the repo 33 | - leadership: foster open-source aware practices such as [FOSS][4] 34 | - expertise: typically demonstrated by significant contributions to the code or 35 | code reviews 36 | 37 | (1) The semantics of accepting a patch depend on the sub-project contribution 38 | process. 39 | 40 | - GitHub pull requests - Merging the pull request. 41 | - Gerrit - +2. 42 | - email - Merging the patch. 43 | 44 | Ensure that accepted changes actually merge into OpenBMC repositories. 45 | 46 | [1]: https://drive.google.com/drive/folders/1Ooi0RdTcaOWF1DWFJUAJDdN7tRKde7Nl 47 | [2]: https://drive.google.com/file/d/1d-2M8ng_Dl2j1odsvZ8o1QHAdHB-pNSH 48 | [3]: https://drive.google.com/file/d/1k3fc7JPgzKdItEfyIoLxMCVbPUhTwooY 49 | [4]: https://en.wikipedia.org/wiki/Free_and_open-source_software 50 | -------------------------------------------------------------------------------- /OWNERS: -------------------------------------------------------------------------------- 1 | # OWNERS 2 | # ------ 3 | # 4 | # The OWNERS file maintains the list of individuals responsible for various 5 | # parts of this repository, including code review and approval. We use the 6 | # Gerrit 'owners' plugin, which consumes this file, along with some extra 7 | # keywords for our own purposes and tooling. 8 | # 9 | # For details on the configuration used by 'owners' see: 10 | # https://gerrit.googlesource.com/plugins/owners/+/refs/heads/master/owners/src/main/resources/Documentation/config.md 11 | # 12 | # An OWNERS file must be in the root of a repository but may also be present 13 | # in any subdirectory. The contents of the subdirectory OWNERS file are 14 | # combined with parent directories unless 'inherit: false' is set. 15 | # 16 | # The owners file is YAML and has [up to] 4 top-level keywords. 17 | # * owners: A list of individuals who have approval authority on the 18 | # repository. 19 | # 20 | # * reviewers: A list of individuals who have requested review notification 21 | # on the repository. 22 | # 23 | # * matchers: A list of specific file/path matchers for granular 'owners' and 24 | # 'reviewers'. See 'owners' plugin documentation. 25 | # 26 | # * openbmc: A list of openbmc-specific meta-data about owners and reviewers. 27 | # - name: preferred name of the individual. 28 | # - email: preferred email address of the individual. 29 | # - discord: Discord nickname of the individual. 30 | # 31 | # It is expected that these 4 sections will be listed in the order above and 32 | # data within them will be kept sorted. 33 | 34 | owners: 35 | - patrick@stwcx.xyz 36 | 37 | reviewers: 38 | - andrew@codeconstruct.com.au 39 | - anoo@us.ibm.com 40 | - gunnar@gmills.xyz 41 | - yulei.sh@bytedance.com 42 | 43 | matchers: 44 | - exact: designs/device-tree-gpio-naming.md 45 | reviewers: 46 | - andrew@codeconstruct.com.au 47 | - joel@jms.id.au 48 | - partial_regex: mctp 49 | reviewers: 50 | - jk@ozlabs.org 51 | 52 | openbmc: 53 | - name: Adriana Kobylak 54 | email: anoo@us.ibm.com 55 | discord: anoo 56 | - name: Andrew Jeffery 57 | email: andrew@codeconstruct.com.au 58 | discord: arj 59 | - name: Gunnar Mills 60 | email: gunnar@gmills.xyz 61 | discord: GunnarM 62 | - name: Jeremy Kerr 63 | email: jk@ozlabs.org 64 | discord: jk 65 | - name: Joel Stanley 66 | email: joel@jms.id.au 67 | discord: joel 68 | - name: Lei Yu 69 | email: yulei.sh@bytedance.com 70 | discord: LeiYU 71 | - name: Patrick Williams 72 | email: patrick@stwcx.xyz 73 | discord: stwcx 74 | -------------------------------------------------------------------------------- /SECURITY.md: -------------------------------------------------------------------------------- 1 | # Security Policy 2 | 3 | ## How to report a security vulnerability 4 | 5 | This describes how you can report an OpenBMC security vulnerability privately to 6 | give the project time to address the problem before public disclosure. 7 | 8 | The main ideas are: 9 | 10 | - You have information about a security problem which is not yet publicly 11 | available. 12 | - You want the problem fixed before public disclosure and you are willing to 13 | help make that happen. 14 | - You understand the problem will eventually be publicly disclosed. 15 | 16 | To begin the process: 17 | 18 | - Send an email to `openbmc-security at lists.ozlabs.org` with details about the 19 | security problem such as: 20 | - the version and configuration of OpenBMC the problem appears in 21 | - how to reproduce the problem 22 | - what are the symptoms 23 | - As the problem reporter, you will be included in the email thread for the 24 | problem. 25 | 26 | The OpenBMC security response team (SRT) will respond to you and work to address 27 | the problem. Activities may include: 28 | 29 | - Privately engage community members to understand and address the problem. 30 | Anyone brought onboard should be given a link to the OpenBMC [security 31 | response team guidelines][]. 32 | - Work to determine the scope and severity of the problem, such as [CVSS 33 | metrics][]. 34 | - Work to create or identify an existing [CVE][]. 35 | - Coordinate workarounds and fixes with you and the community. 36 | - Coordinate announcement details with you, such as timing or how you want to be 37 | credited. 38 | - Create an OpenBMC security advisory. 39 | 40 | Please refer to the [CERT Guide to Coordinated Vulnerability Disclosure][], 41 | (SPECIAL REPORT CMU/SEI-2017-SR-022) for additional considerations. 42 | 43 | Alternatives to this process: 44 | 45 | - If the problem is not severe, please write an issue to the affected repository 46 | or email the list. 47 | - Join the OpenBMC community and fix the problem yourself. 48 | - If you are unsure if the error is in OpenBMC (contrasted with upstream 49 | projects such as the Linux kernel or downstream projects such as a customized 50 | version of OpenBMC), please report it and we will help you route it to the 51 | correct area. 52 | - Discuss your topic in other 53 | [OpenBMC communication channels](https://github.com/openbmc/openbmc). 54 | 55 | [security response team guidelines]: ./obmc-security-response-team-guidelines.md 56 | [cvss metrics]: https://www.first.org/cvss/calculator/3.0 57 | [cve]: http://cve.mitre.org/about/index.html 58 | [cert guide to coordinated vulnerability disclosure]: 59 | https://resources.sei.cmu.edu/asset_files/SpecialReport/2017_003_001_503340.pdf 60 | -------------------------------------------------------------------------------- /designs/redfish-pcie.md: -------------------------------------------------------------------------------- 1 | # Redfish PCIe Resources 2 | 3 | Author: Jason Bills, jmbills 4 | 5 | Other contributors: Ed Tanous 6 | 7 | Created: April 3, 2019 8 | 9 | ## Problem Description 10 | 11 | Redfish has resources that describe PCIe devices and functions available on a 12 | system. It would be useful to provide these resources to users out-of-band over 13 | Redfish from OpenBMC. 14 | 15 | ## Background and References 16 | 17 | The Redfish PCIe resources are here: 18 | 19 | [PCIeSlots](https://redfish.dmtf.org/schemas/PCIeSlots_v1.xml) 20 | 21 | [PCIeDevice](https://redfish.dmtf.org/schemas/PCIeDevice_v1.xml) 22 | 23 | [PCIeFunction](https://redfish.dmtf.org/schemas/PCIeFunction_v1.xml) 24 | 25 | ## Requirements 26 | 27 | This feature is intended to meet the Redfish requirements for the PCIe resources 28 | above to provide useful system configuration information to system 29 | administrators and operators. 30 | 31 | ## Proposed Design 32 | 33 | The proposed implementation will follow the standard D-Bus producer-consumer 34 | model used in OpenBMC. The producer will provide the required PCIe values read 35 | from hardware. The consumer will retrieve and parse the D-Bus data to provide 36 | the Redfish PCIe resources. 37 | 38 | The proposed D-Bus interface can be found here: 39 | 40 | 41 | The proposed producer will be a new D-Bus daemon that will be responsible for 42 | gathering and caching PCIe hardware data and maintaining the D-Bus interfaces 43 | and properties. The actual hardware mechanism that is used to gather the PCIe 44 | hardware data will vary. 45 | 46 | For example, on systems that the BMC has access to the host PCI configuration 47 | space, it can directly read the required registers. On systems without access to 48 | the host PCI configuration space, an entity such as the BIOS or OS can gather 49 | the required data and send it to the PCIe daemon through IPMI, etc. 50 | 51 | When reading hardware directly, the PCIe daemon must be aware of power state 52 | changes and any BIOS timing requirements, so it can check for hardware changes, 53 | update its cache, and make the necessary changes to the D-Bus properties. This 54 | will allow a user to retrieve the latest PCIe resource data as of the last 55 | system boot even if it is powered off. 56 | 57 | bmcweb will be the consumer. It will be responsible for retrieving the Redfish 58 | PCIe resource data from the D-Bus properties and providing it to the user. 59 | 60 | ## Alternatives Considered 61 | 62 | None. 63 | 64 | ## Impacts 65 | 66 | Possible performance impact on the hardware-scanning and D-Bus updates. The 67 | piece that implements hardware scanning should use mechanisms, such as caching 68 | of the hardware configuration, to minimize the scanning time and updates to 69 | D-Bus properties. 70 | 71 | ## Testing 72 | 73 | This can be tested using the Redfish Service Validator. 74 | -------------------------------------------------------------------------------- /designs/phosphor-hwmon-refactoring.md: -------------------------------------------------------------------------------- 1 | # Phosphor-hwmon refactoring 2 | 3 | Author: Kun Yi 4 | 5 | Created: 2019/09/05 6 | 7 | ## Problem Description 8 | 9 | Convoluted code in phosphor-hwmon is imparing our ability to add features and 10 | identify/fix bugs. 11 | 12 | ## Background and References 13 | 14 | A few cases of smelly code or bad design decisions throughout the code: 15 | 16 | - Limited unit testing coverage. Currently the unit tests in the repo [1] mostly 17 | test that the sensor can be constructed correctly, but there is no testing of 18 | correct behavior on various sensor reading or failure conditions. 19 | - Bloated mainloop. mainloop::read() sits at 146 lines [2] with complicated 20 | conditions, macros, and try/catch blocks. 21 | - Lack of abstraction and dependency injection. This makes the code hard to test 22 | and hard to read. For example, the conditional at [3] can be replaced by 23 | implementing different sensor::readValue() method for different sensor types. 24 | 25 | [1](https://github.com/openbmc/phosphor-hwmon/tree/master/test) 26 | [2](https://github.com/openbmc/phosphor-hwmon/blob/94a04c4e9162800af7b2823cd52292e3aa189dc3/mainloop.cpp#L390) 27 | [3](https://github.com/openbmc/phosphor-hwmon/blob/94a04c4e9162800af7b2823cd52292e3aa189dc3/mainloop.cpp#L408) 28 | 29 | ## Goals 30 | 31 | 1. Improve unit test coverage 32 | 2. Improve overall design using OOD principles 33 | 3. Improve error handling and resiliency 34 | 4. Improve configurability 35 | - By providing a common configuration class, it will be feasible to add 36 | alternative configuration methods, e.g. JSON, while maintaining backward 37 | compatibility with existing env files approach. 38 | 39 | ## Proposed Design 40 | 41 | Rough breakdown of refactoring steps: 42 | 43 | 1. Sensor configuration 44 | - Add a SensorConfig struct that does all std::getenv() calls in one place 45 | - DI: make the sensor struct take SensorConfig as dependency 46 | - Unit tests for SensorConfig 47 | - Add unit tests for sensor creation with various SensorConfigs 48 | 2. Abstract sensors 49 | - Refine the sensor object interface and make it abstract 50 | - Define sensor types that inherit from the common interface 51 | - Add unit tests for sensor interface 52 | - DI: make the sensor map take sensor interface as dependency 53 | - Add a fake sensor that can exhibit controllable behavior 54 | 3. Refactor sensor management logic 55 | - Refactor sensor map to allow easier lookup/insertion 56 | - Add unit tests for sensor map 57 | - DI: make all other functions take sensor map as dependency 58 | 4. Abstract error handling 59 | - Add overridable error handler to sensor interface 60 | - Define different error handlers 61 | - Add unit tests for error handlers using the fake sensor 62 | 63 | ## Alternatives Considered 64 | 65 | N/A. 66 | 67 | ## Impacts 68 | 69 | The refactoring should have no external API impact. Performance impact should be 70 | profiled. 71 | 72 | ## Testing 73 | 74 | One of the goals is to have better unit test coverage. Overall functionality to 75 | be tested through functional and regression tests. 76 | -------------------------------------------------------------------------------- /designs/platform-init.md: -------------------------------------------------------------------------------- 1 | # Platform init 2 | 3 | Author: Ed Tanous (edtanous) 4 | 5 | Created: 7-21-25 6 | 7 | ## Problem Description 8 | 9 | There are a number of platforms that require handling of state that requires 10 | interacting with hardware in a consolidated way. Some examples of this are: 11 | 12 | 1. Resetting an i2c driver that initially is without power. 13 | 2. Bringing up a power rail under the control of the BMC. 14 | 3. Initing a power rail dependent on the state of a plug detect pin. 15 | 16 | ## Background and References 17 | 18 | And any number of other cases. Some concrete examples of this kind of init of 19 | these things exists here. [1] 20 | 21 | Very routinely, significant bash scripts are used to do some of this init. Those 22 | bash scripts suffer some minor performance penalty on startup, and are generally 23 | checked into meta layers, reducing the reuse between platforms. 24 | 25 | ## Requirements 26 | 27 | 1. OpenBMC must be able to init a system with devices on power rails that it 28 | controls. 29 | 2. During the control of aformentioned power rails, the OpenBMC must be able to 30 | monitor GPIO signals. 31 | 3. OpenBMC must be able to reset i2c lines that might not be available. 32 | 4. (secondary) Must be able to init multiple platforms from a single binary 33 | (dc-scm) 34 | 35 | ## Proposed Design 36 | 37 | Initially, a new repository would be created to house the platform-init for 38 | gb200nvl platform, and get static analysis autobumps, and recipes reused between 39 | platforms. 40 | 41 | Platforms will be separated by folder to ensure that platform owners can review 42 | and create their platform configurations as required, and identical to the 43 | meta-layer process that exists today. 44 | 45 | Top level structure will be 46 | 47 | platform_init.cpp platform1/init.cpp platform2/init.cpp 48 | 49 | Initially a cli argument will be used to compile the appropriate paths for a 50 | given platform. At some point in the future, some level of detection _may_ be 51 | added that allows detecting platforms at runtime. Design for that is to be 52 | determined based on future requirements. 53 | 54 | Guard rails will need to evolve over time, but initially this repository will 55 | not interact with DBus or the OpenBMC model. As defined (at this time) it is 56 | purely for initial bringup of hardware. 57 | 58 | ## Alternatives Considered 59 | 60 | Status quo, continue building init scripts in bash. This leads to a lack of code 61 | reuse, and while some layers have done an excellent job keeping the code clean, 62 | it's still very difficult to refactor/consolidate. 63 | 64 | ## Impacts 65 | 66 | 1. Will require a new repository, recipe, and CI build. 67 | 2. A new service will be launched for platforms opting into platform-init. 68 | 69 | ### Organizational 70 | 71 | - Does this proposal require a new repository? Yes Request for the repository is 72 | available[2] 73 | - Who will be the initial maintainer(s) of this repository? Ed Tanous and 74 | Patrick Williams 75 | - Which repositories are expected to be modified to execute this design? 76 | openbmc/openbmc New repository 77 | 78 | ## Testing 79 | 80 | Testing section omitted. Platform boot will be tested using individual 81 | platforms, with no change. 82 | 83 | [1]: 84 | https://github.com/openbmc/openbmc/blob/master/meta-nvidia/meta-gb200nvl-obmc/recipes-nvidia/platform-init/files/platform_init.cpp 85 | [2]: https://github.com/openbmc/technical-oversight-forum/issues/51 86 | -------------------------------------------------------------------------------- /designs/management-console/service-discovery.md: -------------------------------------------------------------------------------- 1 | # Service processor discovery through Avahi 2 | 3 | Author: Ratan Gupta 4 | 5 | Other contributors: Asmitha KR 6 | 7 | Created: 2019-07-12 8 | 9 | ## Background and References 10 | 11 | 1. 12 | 2. : comparison of mDns v/s UPnP. 13 | 3. 14 | 4. 15 | 16 | Apple’s Bonjour uses mDNS and DNS-SD. Linux’s Avahi uses IPv4LL, mDNS, and 17 | DNS-SD. Linux’s systemd uses resolve hostnames on a network via DNS, mDNS, and 18 | LMMNR. 19 | 20 | ## Problem Description 21 | 22 | In a network where there are thousands of system, Management console should be 23 | able to discover the server. We have a requirement where the management console 24 | wants to discover the vendor-specific server. 25 | 26 | eg: Management console wants to discover the low-end server of manufacturer XYZ. 27 | 28 | ## Proposed Design 29 | 30 | Currently in openBMC, Avahi is being used as service discovery. Avahi is a 31 | system which facilitates service discovery on a local network via the 32 | mDNS/DNS-SD protocol suite. BMC publishes the hostname and interface details to 33 | the network using the Avahi service. 34 | 35 | The services that are being published by Avahi have various fields like - 36 | service name, type, port, hostname, address, port, and a text record. To solve 37 | the above-listed problem, we are proposing a solution in which the 38 | vendor-specific information is included in the text record field of the Avahi 39 | service file. 40 | 41 | To do so, currently, in OpenBMC we have the infrastructure where the 42 | service-specific data is passed through a systemd service specific bb file. 43 | Depending on the distro feature(Avahi) enabled or not, it generates the Avahi 44 | service file with the given data. We are enhancing this infrastructure to add 45 | the vendor-specific information in the avahi service file(under txt-record). 46 | 47 | Following commits implements the behaviour. 48 | 49 | - 50 | - 51 | 52 | As part of avahi discovery response, the client receives the following: 53 | 54 | 1. Hostname 55 | 2. IP address 56 | 3. Service Port 57 | 4. Service Type 58 | 5. Additional data 59 | 60 | ### How to do discovery through avahi 61 | 62 | The following command may be used to discover the BMC systems in the network. 63 | `avahi-browse -rt ` e.g. To discover service type : 64 | \_obmc_rest.\_tcp avahi-browse -rt \_obmc_rest.\_tcp Output of the above command 65 | is as follows avahi-browse -rt \_obmc_rest.\_tcp 66 | 67 | - eth0 IPv6 obmc_rest \_obmc_rest.\_tcp local 68 | - eth0 IPv4 obmc_rest \_obmc_rest.\_tcp local = eth0 IPv6 obmc_rest 69 | \_obmc_rest.\_tcp local hostname = 70 | [witherspoon-cdcb785972fb41f082c7ca747e287fa6.local] address = 71 | [fe80::72e2:84ff:fe14:2390] port = [443] txt = ["Manufacturer=XYZ"] txt = 72 | ["Type=abc"] = eth0 IPv4 obmc_rest \_obmc_rest.\_tcp local hostname = 73 | [witherspoon-cdcb785972fb41f082c7ca747e287fa6.local] address = [9.5.180.233] 74 | port = [443] txt = ["Manufacturer=XYZ"] txt = ["Type=abc"] 75 | 76 | ## Alternatives Considered 77 | 78 | openSLP 79 | 80 | ## Impacts 81 | 82 | None. 83 | 84 | ## Testing 85 | 86 | The path /etc/avahi/services contain all the services that avahi publishes on 87 | startup. 88 | -------------------------------------------------------------------------------- /architecture/code-update/code-update-diagrams.md: -------------------------------------------------------------------------------- 1 | # Code Update Diagrams 2 | 3 | 1. [High-Level Overview](#High-Level Overview) 4 | 5 | ## High-Level Overview 6 | 7 | ```ascii 8 | ┌──────────────┐ ┌─────────────┐ ┌────────────┐ 9 | │User Interface│ │Image Manager│ │Item Updater│ 10 | └──────┬───────┘ └──────┬──────┘ └──────┬─────┘ 11 | │ Upload │ │ 12 | │ Firmware │ │ 13 | │ Image to BMC │ │ 14 | ├──────────────────────────▶│ │ 15 | │ │ │ 16 | │ │ Extract │ 17 | │ │ image │ 18 | │ │ contents │ 19 | │ │ │ │ 20 | │ ├─────┘ │ 21 | │ ▼ │ 22 | │ │ │ 23 | │ │ Create │ 24 | │ │Software D-Bus │ 25 | │ │ object[1] │ 26 | │ │ │ │ 27 | │ ├───────┘ │ 28 | │ ▼ │ 29 | │ │ │ 30 | │ Request to ● │ 31 | │ Activate │ 32 | │ Software │ 33 | │ D-Bus Object │ 34 | ├────────────────────────────────────────────────▶│ 35 | │ │ Verify 36 | │ │ digital 37 | │ │ signatures 38 | │ │ │ 39 | │ ├──────┘ 40 | │ ▼ 41 | │ │ 42 | │ │ Write 43 | │ │ image to 44 | │ │ flash[*] 45 | │ │ │ 46 | │ ├─────┘ 47 | │ ▼ 48 | │ │ 49 | │ Success │ 50 | │◀────────────────────────────────────────────────┤ 51 | │ │ 52 | │ ● 53 | ▼ 54 | BMC Reboot is 55 | required to boot 56 | from the updated 57 | image 58 | 59 | ``` 60 | 61 | - [1] 62 | [Software D-Bus Object](https://github.com/openbmc/phosphor-dbus-interfaces/tree/master/yaml/xyz/openbmc_project/Software) 63 | - [*] In a static layout configuration, the images are stored in RAM and the 64 | content is written to flash during BMC reboot. Reference the update and 65 | shutdown scripts provided by 66 | [initrdscripts](https://github.com/openbmc/openbmc/tree/master/meta-phosphor/recipes-phosphor/initrdscripts) 67 | -------------------------------------------------------------------------------- /architecture/optionality.md: -------------------------------------------------------------------------------- 1 | # Optionality 2 | 3 | OpenBMC does its best to be widely applicable to all BMC deployments in the 4 | world, including many varieties of hardware. To do this requires care in the way 5 | new features are developed, to ensure stability of systems over time. With that 6 | as a goal, any given feature should fit into one of the following categories. 7 | 8 | ## Core 9 | 10 | Required for the deployment of _any_ OpenBMC build. Examples of this include the 11 | Linux kernel, systemd, sdbusplus, and phosphor object mapper. These features are 12 | expected to remain widely applicable to all systems. 13 | 14 | ## Subsystem 15 | 16 | These are subsystems that, while widely applicable, a user might choose to 17 | remove entire portions of the codebase that might not be needed in that 18 | deployment, or not used. This might be done to save binary size in the flash 19 | image, or might be done to reduce the security attack surface. These kids of 20 | features should be architected to ensure that, when removed, they do not cause 21 | functional impacts to other subsystems. Examples of these include the webui, 22 | Redfish, IPMI, and others. 23 | 24 | ## Feature Configuration Types 25 | 26 | Features within an individual subsystem must be built such that they fall into 27 | one of these categories. For non-trivial feature additions, the commit message 28 | of the feature, as well as the design doc should explicitly state one of the 29 | following classes of feature. 30 | 31 | ### Non configurable features 32 | 33 | Theses are features that are broadly applicable to all all deployments of a 34 | subsystem either by general usage, or by requirements in a specification, and 35 | therefore don't need to be able to be configured. Examples of these would 36 | include, Http keep alive, Security features like timeouts and payload size 37 | limits, and required commands. These types of features generally show no 38 | user-facing impact to function, although might do things like improve 39 | performance. 40 | 41 | Requires: Standards conformance, applicability to all flash-size systems, as 42 | well as all processor classes. 43 | 44 | ### User opt-in features 45 | 46 | User opt-in features are features for which an external user must explicitly 47 | change their behavior to "opt in" to using a feature. Features like this, while 48 | they may be configurable at compile time, are not required to be configurable at 49 | compile time. Examples of this include Redfish query parameters, or IPMI OEM 50 | commands. 51 | 52 | Requires: Explicit, non-default user opt-in to execute the various features. 53 | 54 | ### Developer opt-in features 55 | 56 | Many times a system or specific team might want a feature that is intended 57 | _only_ for a subset of the OpenBMC audience, and might add OEM parameters to 58 | non-standard interfaces, new command sets, or new APIs that might be applicable. 59 | Features of this nature MUST be configurable at either compile time or runtime, 60 | and generally will default to disabled. Features of this nature, when disabled, 61 | must take care to make no changes to the behavior of systems for which the 62 | feature is disabled. Company or feature specific functions, as well as the 63 | associated metadata must not be visible on a system for which the feature is 64 | disabled. Note, there are cases where _removing_ a feature might cause user 65 | impact, and therefore requires an option. 66 | 67 | CI will generally enable all developer opt-in features to ensure the most 68 | coverage of build configurations. 69 | 70 | Specific mechanisms to enable or disable these features are commonly: 71 | 72 | 1. Meson options 73 | 2. Entity-manager configuration 74 | 3. Yocto recipe changes 75 | 4. Phosphor ObjectMapper searches 76 | -------------------------------------------------------------------------------- /logo/OpenBMC-Logo.svg: -------------------------------------------------------------------------------- 1 | Asset 1 -------------------------------------------------------------------------------- /designs/management-console/Authorities_List_Management.md: -------------------------------------------------------------------------------- 1 | # Authorities List Management 2 | 3 | Author: Nan Zhou 4 | 5 | Created: 12/01/2021 6 | 7 | ## Problem Description 8 | 9 | There are use cases where a system has multiple root certificates installed to 10 | verify different clients. For example, In Google, a trust bundle file ( which is 11 | a list of authorities) is installed on BMC for mTLS authentication. 12 | 13 | The current phosphor-certificate-manager doesn't have good support to manage 14 | multiple root certificates: 15 | 16 | 1. It only allows replacing a single Authority object in dbus; however, Google's 17 | use case requires bulk replacement (see the ReplaceAll interface below) 18 | 19 | 2. It only extracts the first certificate given a PEM encoded file with multiple 20 | certs; however, Google's trust bundle file contains multiple PEM encoded 21 | certificates 22 | 23 | ## Requirements 24 | 25 | Phosphor-certificate-manager (only the Authority Manager) and BMCWeb will 26 | support authorities list: 27 | 28 | 1. Bulk Installation: given a PEM file with multiple root certificates, it 29 | validates & installs all of them and returns a list of created objects 30 | 31 | 2. Bulk Replacement: given a PEM file with multiple root certificates, it will 32 | firstly delete all current root certificates and redo the installation 33 | 34 | 3. Redfish: BMCWeb will export all authorities as Redfish Certificate 35 | 36 | 4. Recovery at boot up: when the phosphor-certificate-manager gets instantiated, 37 | if it finds a authorities list in the installation path, it will recover from 38 | the list via a bulk installation 39 | 40 | 5. Atomic: Bulk Installation and Bulk Replacement are atomic; that is, if there 41 | is an invalid certificate in the list, the service won't install any of the 42 | certificates in the list 43 | 44 | ## Proposed Design 45 | 46 | We propose two new interfaces: 47 | 48 | 1. InstallAll 49 | 2. ReplaceAll 50 | 51 | ### xyz.openbmc_project.Certs.InstallAll 52 | 53 | When certificate type is Authority, rather than just extract the first 54 | certificate, we will iterate through each certificate, validate it, create 55 | corresponding object in DBus, dump individual certificates into PEM files in the 56 | installation path, creates alias according to subject hash (requirements from 57 | boost's `ssl_context`) for each certificate, and finally copy the PEM file to 58 | the installation path(the PEM file will have a fixed name) 59 | 60 | We return all created object paths as a vector of strings. 61 | 62 | For other types of certificates (server & client), the service throws a NOT 63 | ALLOWED error. 64 | 65 | ### xyz.openbmc_project.Certs.ReplaceAll 66 | 67 | The new interface contains a ReplaceAll method which takes a path to the input 68 | PEM file. 69 | 70 | The certificate manager will implement the new ReplaceAll interface. Upon 71 | invocation, it deletes all current authority objects, takes the input PEM, and 72 | redo the installation. 73 | 74 | For other types of certificate manager (server & client), the service throws a 75 | NOT ALLOWED error. 76 | 77 | ### xyz.openbmc_project.Certs.Replace 78 | 79 | No changes. Individual authority certificate can still be replaced respectively. 80 | It only extracts the first certificate even if the PEM contains multiple root 81 | certificates. 82 | 83 | ## Impacts 84 | 85 | None besides new APIs are added 86 | 87 | ## Alternatives Considered 88 | 89 | We can also create a trust bundle interface (instead of using multiple 90 | Certificates) and implement its standalone manager daemon. It has less impact in 91 | existing codes. However, trust bundle isn't in BMCWeb, neither in Redfish 92 | schema. 93 | 94 | ## Testing 95 | 96 | Enhance existing unit tests in phosphor-certificates-manager to test bulk 97 | installation and replacements. 98 | -------------------------------------------------------------------------------- /security/how-to-report-a-security-vulnerability.md: -------------------------------------------------------------------------------- 1 | # How to report a security vulnerability 2 | 3 | This describes how you can report an OpenBMC security vulnerability privately to 4 | give the project time to address the problem before public disclosure. 5 | 6 | The main ideas are: 7 | 8 | - You have information about a security problem or vulnerability which is not 9 | yet publicly available. 10 | - You want the problem fixed before public disclosure and you are willing to 11 | help make that happen. 12 | - You understand the problem will eventually be publicly disclosed. 13 | 14 | To begin the process: Privately contact the OpenBMC security response team and 15 | (if known) the project maintainer: 16 | 17 | - Suggest sending an email. Use `openbmc-security at lists.ozlabs.org`. 18 | - If you know which source code repository is affected, find the repository 19 | owner or maintainer contact information in the OWNERS or MAINTAINERS file. If 20 | not, the security response team will help route the problem. 21 | - Include details about the security problem such as: 22 | - The version and configuration of OpenBMC the problem appears in. 23 | - How to reproduce the problem. 24 | - What are the symptoms. 25 | - As the problem reporter, you will be included in the problem response. 26 | 27 | Please note the OpenBMC project has multiple source code repositories. Each has 28 | separate owners. If you do not know which repository is affected, the owner or 29 | the security response team can help you route the problem. 30 | 31 | When the project owners get a new security problem, they will create a [GitHub 32 | security advisory][] in their repository and begin work. The advisory has draft 33 | status which means only the collaborators can see it. Collaborators should be 34 | added as follows: 35 | 36 | - The problem reporter. 37 | - The OpenBMC security response team. 38 | - Developers responsible for fixing the problem. 39 | 40 | The collaborators work to resolve the problem. Activities may include: 41 | 42 | - The OpenBMC [CVE Numbering Authority (CNA)][] (members of the OpenBMC security 43 | response team) will help clarify the problem and assign CVEs. 44 | - Privately engage community members to understand and address the problem. 45 | Anyone brought onboard should be given a link to the OpenBMC [security 46 | response team guidelines][]. 47 | - Work to determine the scope and severity of the problem, such as [CVSS 48 | metrics][]. 49 | - Coordinate workarounds and fixes with you and the community. 50 | - Coordinate announcement details with you, such as timing or how you want to be 51 | credited. 52 | - At the agreed time, publish the OpenBMC security advisory, reveal the fix, and 53 | publish the [CVE][]. 54 | 55 | Please refer to the [CERT Guide to Coordinated Vulnerability Disclosure][], 56 | (SPECIAL REPORT CMU/SEI-2017-SR-022) for additional considerations. 57 | 58 | Alternatives to this process: 59 | 60 | - If the problem is not severe, please write an issue to the affected repository 61 | or email the list. 62 | - Join the OpenBMC community and fix the problem yourself. 63 | - If you are unsure if the error is in OpenBMC (contrasted with upstream 64 | projects such as the Linux kernel or downstream projects such as a customized 65 | version of OpenBMC), please report it and we will help you route it to the 66 | correct area. 67 | - Discuss your topic in other 68 | [OpenBMC communication channels](https://github.com/openbmc/openbmc). 69 | 70 | [security response team guidelines]: ./obmc-security-response-team-guidelines.md 71 | [cvss metrics]: https://www.first.org/cvss/calculator/3.0 72 | [cve]: http://cve.mitre.org/about/index.html 73 | [cert guide to coordinated vulnerability disclosure]: 74 | https://resources.sei.cmu.edu/asset_files/SpecialReport/2017_003_001_503340.pdf 75 | [github security advisory]: 76 | https://docs.github.com/en/code-security/repository-security-advisories/creating-a-repository-security-advisory 77 | [cve numbering authority (cna)]: https://www.cve.org/ProgramOrganization/CNAs 78 | -------------------------------------------------------------------------------- /designs/thermal-control-modes.md: -------------------------------------------------------------------------------- 1 | # Control.ThermalMode dbus interface with Supported and Current properties 2 | 3 | Author: Matthew Barth !msbarth 4 | 5 | Other contributors: None 6 | 7 | Created: 2019-02-06 8 | 9 | ## Problem Description 10 | 11 | An issue was discovered where the exhaust heat from the system GPUs causes 12 | overtemp warnings on optical cables on certain system configurations. The issue 13 | can be resolved by altering the fan control application's floor table, 14 | effectively raising the floor when these optical cables exist but an interface 15 | is needed to do so. Since the issue revolves around the optical cables 16 | themselves, where no current mechanism exists to detect the presence of the 17 | optical cables plugged into a card downwind from the GPUs' exhaust, an end-user 18 | must be presented with an ability to enable this raised floor speed table. 19 | 20 | ## Background and References 21 | 22 | The witherspoon system supports pci cards that could have optical cables plugged 23 | in place of copper cables. These optical cables can report overtemp warnings to 24 | the OS when high GPU utilization workloads exist. When this occurs with low 25 | enough CPU utilization, the fans could be kept at a given floor speed that 26 | sufficiently cools the components within the chassis, but not the optical cables 27 | with the slow moving hot exhaust. 28 | 29 | Without an available exhaust temp sensor, there's no direct way to determine the 30 | exhaust temp and include that within the fan control algorithm. A similar issue 31 | exists on other system where mathematical calculations are done based on the 32 | overall power dissipation. 33 | 34 | Mathematical calculations to logically estimate exit air temps: 35 | 36 | 37 | ## Requirements 38 | 39 | Create the ability for an end-user to enable the use of a thermal control mode 40 | other than the default. In this use-case, the mode is specific to an 41 | undetectable configuration that alters the fan floor speeds unrelated to 42 | standardized profile/modes such "Acoustic" and "Performance". Once the end-user 43 | selects a documented mode for the platform, the thermal control application 44 | alters its control algorithm according to the defined mode, which is 45 | implementation specific to that instance of the application on that platform. 46 | 47 | ## Proposed Design 48 | 49 | Create a Control.ThermalMode dbus interface containing a supported list of 50 | available thermal control modes along with what current mode is in use. 51 | Initially the current mode would be set to "Default" and the implementation of 52 | the interface would populate the supported list of modes. 53 | 54 | As one implementation, phosphor-fan-presence/control would be updated to extend 55 | this dbus interface object which would fill in the list of supported modes from 56 | its fan control configuration for the platform. Once the fan control application 57 | starts, the interface would be added on the zone object and available to be 58 | queried for supported modes or update the current mode. An end-user may set the 59 | current mode to any of those supported modes and the current mode would be 60 | persisted each time it is updated. This is to ensure each time the fan control 61 | application zone objects are started, the last set control mode is used. 62 | 63 | ## Alternatives Considered 64 | 65 | Mathematical calculation to create a virtual exhaust temp sensor value based on 66 | overall power dissipation. However, in the witherspoon situation, using this 67 | technique would not be reliable in adjusting the floor speeds for only 68 | configurations using optical cables. This would instead present the possibility 69 | of raising floor speeds for configurations where its unnecessary. 70 | 71 | ## Impacts 72 | 73 | The thermal control application used must be configured to provide what thermal 74 | control modes are supported/available on the interface as well as perform the 75 | associated control changes when a mode is set. 76 | 77 | ## Testing 78 | 79 | Trigger the use of an alternative fan floor table based on the thermal control 80 | mode selected on a witherspoon system. 81 | -------------------------------------------------------------------------------- /designs/nmi-dbus-interface.md: -------------------------------------------------------------------------------- 1 | # Design proposal for issuing NMI on servers that use OpenBMC 2 | 3 | Author: Lakshminarayana Kammath 4 | 5 | Other contributors: Jayanth Othayoth 6 | 7 | Created: 2019-05-21 8 | 9 | ## Problem Description 10 | 11 | Currently, servers that use OpenBMC cannot have the ability to capture relevant 12 | debug data when the host is unresponsive or hung. These systems need the ability 13 | to diagnose the root cause of hang and perform recovery along with debugging 14 | data collected. 15 | 16 | ## Background and References 17 | 18 | There is a situation at customer places/lab where the host goes unresponsive 19 | causing system hang(). This means 20 | there is no way to figure out what went wrong with the host in a hung state. One 21 | has to recover the system with no relevant debug data captured. 22 | 23 | Whenever the host is unresponsive/running, Admin needs to trigger an NMI event 24 | which, in turn, triggers an architecture-dependent procedure that fires an 25 | interrupt on all the available processors on the system. 26 | 27 | ## Proposed Design for servers that use OpenBMC 28 | 29 | This proposal aims to trigger NMI, which in turn will invoke an 30 | architecture-specific procedure that enables data collection followed by 31 | recovery of the Host. This will enable Host/OS development teams to analyze and 32 | fix any issues where they see host hang and unresponsive system. 33 | 34 | ### D-Bus 35 | 36 | Introducing new D-Bus interface in the control.host namespace 37 | (/openbmc/phosphor-dbus-interfaces/xyz/openbmc_project/Control/Host/ 38 | NMI.interface.yaml) and implement the new D-Bus back-end for respective 39 | processor specific targets. 40 | 41 | ### BMC Support 42 | 43 | Enable NMI D-Bus phosphor interface and support this via Redfish 44 | 45 | ### Redfish Schema used 46 | 47 | - Reference: DSP2046 2018.3, 48 | - ComputerSystem 1.6.0 schema provides an action called #ComputerSystem.Reset, 49 | This action is used to reset the system. The ResetType parameter is used for 50 | indicating the type of reset needs to be performed. In this case, we can use 51 | An NMI type 52 | - Nmi: Generate a Diagnostic Interrupt (usually an NMI on x86 systems) to 53 | cease normal operations, perform diagnostic actions and typically halt the 54 | system. 55 | 56 | ## High-Level Flow 57 | 58 | 1. Host/OS is hung or unresponsive or one need to take kernel dump to debug some 59 | error conditions. 60 | 2. Admin/User can use the Redfish URI ComputerSystem.Reset that allows POST 61 | operations and change the Action and ResetType properties to 62 | {"Action":"ComputerSystem.Reset","ResetType":"Nmi"} to trigger NMI. 63 | 3. Redfish URI will invoke a D-Bus NMI back-end call which will use an arch 64 | specific back-end implementation of xyz.openbmc_project.Control.Host.NMI to 65 | trigger an NMI on all the processors on the system. 66 | 4. On receiving the NMI, the host will automatically invoke Architecture 67 | specific actions. One such action could be; invoking the kdump followed by 68 | the reboot. 69 | 70 | - Note: NMI can be sent to the host in any state, not just at an unresponsive 71 | state. 72 | 73 | ## Alternatives Considered 74 | 75 | Extending the existing D-Bus interface state.Host namespace 76 | (/openbmc/phosphor-dbus-interfaces/xyz/openbmc_project/State/Host.interface.yaml) 77 | to support new RequestedHostTransition property called Nmi. D-Bus back-end can 78 | internally invoke processor-specific target to invoke NMI and do associated 79 | actions. 80 | 81 | There were strong reasons to move away from the above approach. 82 | phosphor-state-manager has always been focused on the states of the BMC, 83 | Chassis, and Host. NMI will be more of action against the host than a state. 84 | 85 | ## Impacts 86 | 87 | This implementation only needs to make some changes to the system state when NMI 88 | is initiated irrespective of what host OS state is in, so it has minimal impact 89 | on the rest of the system. 90 | 91 | ## Testing 92 | 93 | Depending on the platform hardware design, this test requires a host OS kernel 94 | module driver to create hard lockup/hang and then check the scenario is good. 95 | Also, one can invoke NMI to get the crash dump and confirm HOST received NMI via 96 | console logs. 97 | -------------------------------------------------------------------------------- /style/c/.clang-format: -------------------------------------------------------------------------------- 1 | # SPDX-License-Identifier: GPL-2.0 2 | # 3 | # Originally from Linux v5.6 4 | --- 5 | AccessModifierOffset: -4 6 | AlignAfterOpenBracket: Align 7 | AlignConsecutiveMacros: true 8 | AlignConsecutiveAssignments: false 9 | AlignConsecutiveDeclarations: false 10 | #AlignEscapedNewlines: Left # Unknown to clang-format-4.0 11 | AlignOperands: Align 12 | AlignTrailingComments: 13 | Kind: Always 14 | OverEmptyLines: 1 15 | AllowAllParametersOfDeclarationOnNextLine: false 16 | AllowShortBlocksOnASingleLine: false 17 | AllowShortCaseLabelsOnASingleLine: false 18 | AllowShortFunctionsOnASingleLine: None 19 | AllowShortIfStatementsOnASingleLine: false 20 | AllowShortLoopsOnASingleLine: false 21 | AlwaysBreakAfterDefinitionReturnType: None 22 | AlwaysBreakAfterReturnType: None 23 | AlwaysBreakBeforeMultilineStrings: false 24 | AlwaysBreakTemplateDeclarations: false 25 | BinPackArguments: true 26 | BinPackParameters: true 27 | BraceWrapping: 28 | AfterClass: false 29 | AfterControlStatement: false 30 | AfterEnum: false 31 | AfterFunction: true 32 | AfterNamespace: true 33 | AfterObjCDeclaration: false 34 | AfterStruct: false 35 | AfterUnion: false 36 | #AfterExternBlock: false # Unknown to clang-format-5.0 37 | BeforeCatch: false 38 | BeforeElse: false 39 | IndentBraces: false 40 | #SplitEmptyFunction: true # Unknown to clang-format-4.0 41 | #SplitEmptyRecord: true # Unknown to clang-format-4.0 42 | #SplitEmptyNamespace: true # Unknown to clang-format-4.0 43 | BreakAfterAttributes: Never 44 | BreakBeforeBinaryOperators: None 45 | BreakBeforeBraces: Custom 46 | #BreakBeforeInheritanceComma: false # Unknown to clang-format-4.0 47 | BreakBeforeTernaryOperators: false 48 | BreakConstructorInitializersBeforeComma: false 49 | #BreakConstructorInitializers: BeforeComma # Unknown to clang-format-4.0 50 | BreakAfterJavaFieldAnnotations: false 51 | BreakStringLiterals: false 52 | ColumnLimit: 80 53 | CommentPragmas: '^ IWYU pragma:' 54 | #CompactNamespaces: false # Unknown to clang-format-4.0 55 | ConstructorInitializerAllOnOneLineOrOnePerLine: false 56 | ConstructorInitializerIndentWidth: 8 57 | ContinuationIndentWidth: 8 58 | Cpp11BracedListStyle: false 59 | DeriveLineEnding: false 60 | DerivePointerAlignment: false 61 | DisableFormat: false 62 | ExperimentalAutoDetectBinPacking: false 63 | #FixNamespaceComments: false # Unknown to clang-format-4.0 64 | #IncludeBlocks: Preserve # Unknown to clang-format-5.0 65 | IncludeCategories: 66 | - Regex: '.*' 67 | Priority: 1 68 | IncludeIsMainRegex: '(Test)?$' 69 | IndentCaseLabels: false 70 | IndentExternBlock: NoIndent 71 | #IndentPPDirectives: None # Unknown to clang-format-5.0 72 | IndentWidth: 8 73 | IndentWrappedFunctionNames: false 74 | InsertNewlineAtEOF: true 75 | JavaScriptQuotes: Leave 76 | JavaScriptWrapImports: true 77 | KeepEmptyLinesAtTheStartOfBlocks: false 78 | LineEnding: LF 79 | MacroBlockBegin: '' 80 | MacroBlockEnd: '' 81 | MaxEmptyLinesToKeep: 1 82 | NamespaceIndentation: Inner 83 | #ObjCBinPackProtocolList: Auto # Unknown to clang-format-5.0 84 | ObjCBlockIndentWidth: 8 85 | ObjCSpaceAfterProperty: true 86 | ObjCSpaceBeforeProtocolList: true 87 | 88 | # Taken from git's rules 89 | PenaltyBreakAssignment: 10 90 | PenaltyBreakBeforeFirstCallParameter: 30 91 | PenaltyBreakComment: 10 92 | PenaltyBreakFirstLessLess: 0 93 | PenaltyBreakString: 10 94 | PenaltyExcessCharacter: 100 95 | PenaltyReturnTypeOnItsOwnLine: 60 96 | 97 | PointerAlignment: Right 98 | ReflowComments: false 99 | SortIncludes: false 100 | #SortUsingDeclarations: false # Unknown to clang-format-4.0 101 | SpaceAfterCStyleCast: false 102 | SpaceAfterTemplateKeyword: true 103 | SpaceBeforeAssignmentOperators: true 104 | #SpaceBeforeCtorInitializerColon: true # Unknown to clang-format-5.0 105 | #SpaceBeforeInheritanceColon: true # Unknown to clang-format-5.0 106 | SpaceBeforeParens: ControlStatements 107 | #SpaceBeforeRangeBasedForLoopColon: true # Unknown to clang-format-5.0 108 | SpaceInEmptyParentheses: false 109 | SpacesBeforeTrailingComments: 1 110 | SpacesInAngles: false 111 | SpacesInContainerLiterals: false 112 | SpacesInCStyleCastParentheses: false 113 | SpacesInParentheses: false 114 | SpacesInSquareBrackets: false 115 | Standard: Cpp03 116 | TabWidth: 8 117 | UseTab: Always 118 | ... 119 | -------------------------------------------------------------------------------- /designs/ci-authorization.md: -------------------------------------------------------------------------------- 1 | # Continuous integration and authorization for OpenBMC 2 | 3 | Author: Brad Bishop !radsquirrel 4 | 5 | Other contributors: None 6 | 7 | Created: 2019-01-30 8 | 9 | ## Problem Description 10 | 11 | The OpenBMC project maintains a number of Jenkins CI jobs to ensure incoming 12 | contributions to the project source code meet a level of quality. Incoming 13 | contributions can be made by the general public - anyone with a GitHub account. 14 | However unlikely, it is possible for a bad actor to make code submissions that 15 | attempt to compromise project resources, e.g. build systems, and as such some 16 | amount of authorization of contributors must occur to provide some level of 17 | protection from potential bad actors. 18 | 19 | The project already has contributor authorization for CI. This proposal serves 20 | to describe the drawbacks of the current solution and propose an alternative 21 | that addresses those drawbacks. 22 | 23 | ## Background and References 24 | 25 | The current authorization solution checks the user for membership in the 26 | openbmc/general-developers GitHub team. If the contributor is a member of the 27 | team (or a general-developers sub-team), the automated CI processes are 28 | triggered without any human intervention. If the contributor is not a member of 29 | the general-developers team, manual intervention (ok-to-test) is required by a 30 | project maintainer to trigger the automated CI processes. 31 | 32 | Additional reading: 33 | 34 | - 35 | - 36 | - 37 | 38 | ## Requirements 39 | 40 | The existing method for authorization has a singular problem - the GitHub 41 | organization owner role. In order for contributors to be added to the 42 | openbmc/general-developers GitHub team, the contributor must first be a member 43 | of the openbmc GitHub organization. Only organization owners can invite GitHub 44 | users to become members of an organization. Organization owners have 45 | unrestricted access to all aspects of the project - it would be unwise to bestow 46 | organization ownership for the sole purpose of enabling 47 | openbmc/general-developers group membership administrative capability. 48 | 49 | An alternative authorization method for CI should: 50 | 51 | - Not require the GitHub organization owner role to administer the list of users 52 | authorized for CI. 53 | - Enable a hierarchical trust model for user authorization (groups nested within 54 | groups). 55 | 56 | ## Proposed Design 57 | 58 | The proposal is to simply migrate the current openbmc/general-developers GitHub 59 | team, and all subordinate teams, to Gerrit groups: 60 | 61 | group: `openbmc/ci-authorized` 62 | 63 | group: `xyzcorp/ci-authorized` 64 | 65 | group: `abccorp/ci-authorized` 66 | 67 | The openbmc/ci-authorized group can contain users that are not associated with 68 | any specific organization, as well as organizational groups: 69 | 70 | group: `openbmc/ci-authorized` contains -> 71 | 72 | group `xyzcorp/ci-authorized` 73 | 74 | group `abccorp/ci-authorized` 75 | 76 | user `nancy` 77 | 78 | user `joe` 79 | 80 | This proposal also specifies a convention for administration of organizational 81 | groups: 82 | 83 | group: `xyzcorp/ci-authorized-owners` administers -> `xyzcorp/ci-authorized` 84 | 85 | group: `abccorp/ci-authorized-owners` administers -> `abccorp/ci-authorized` 86 | 87 | group: `openbmc/ci-authorized` administers -> `openbmc/ci-authorized` 88 | 89 | Finally, any Jenkins CI jobs must be updated to test for membership of the 90 | Gerrit group instead of the GitHub team. 91 | 92 | New organizational groups (and associated owner groups) will be created when a 93 | CCLA is signed and accepted by the project. 94 | 95 | ## Alternatives Considered 96 | 97 | Assigning GitHub organization owner roles to organizational group administrators 98 | was considered but is a major violation of the least-privilege-required 99 | principle. 100 | 101 | ## Impacts 102 | 103 | GitHub has vastly superior load balancing and backup capability so there is a 104 | potential for decreased service availability and data loss. 105 | 106 | ## Testing 107 | 108 | Deploy on a live production server 😀 109 | -------------------------------------------------------------------------------- /designs/firmware-update-via-usb.md: -------------------------------------------------------------------------------- 1 | # In-Band Update of BMC Firmware using USB 2 | 3 | Author: George Liu 4 | 5 | Created: 2021-10-12 6 | 7 | ## Problem Description 8 | 9 | When Redfish or scp cannot be used, BMC needs a new mechanism for images to get 10 | into the machine. 11 | 12 | ## Background and References 13 | 14 | The openbmc project currently has a [phosphor-software-manager][1] repository. 15 | In order to perform an update, need first to bring the image into the BMC 16 | directory (/tmp/images). However, only TFTP and HTTP are currently supported, 17 | and USB is not yet supported. 18 | 19 | The intent of this new application design is to enable the USB driver of BMC to 20 | enter the new image into BMC. 21 | 22 | ## Requirements 23 | 24 | The following statements are reflective of the initial requirements. 25 | 26 | - Monitor whether the USB key is inserted. 27 | - The first tar file found in the sorted list of files on the USB device is 28 | copied to `/tmp/images`. 29 | - Manually trigger firmware upgrade. 30 | - Disable automatic reboot the BMC firmware after upgrade is complete to prevent 31 | a potential loop in the event of a key inserted. 32 | - This mechanism attempts to maintain security, for example this feature is 33 | disabled by default or can be enabled or disabled via Redfish. 34 | 35 | ## Proposed Design 36 | 37 | The new code would be part of the phosphor-software-manager repository(eg: 38 | phosphor-usb-code-update). The design process is as follows: 39 | 40 | - Define a macro switch (`usb-code-update`) in [phosphor-software-manager][1] 41 | repository to identify whether to enable the USB Code Update function, which 42 | is _enabled_ by default. 43 | - If `usb-code-update` enabled, install the udev rules file to 44 | `/lib/udev/rules.d` during compilation. 45 | - Once the udev rules are met, the systemd service is directly triggered and 46 | start the phosphor-usb-code-update daemon. 47 | - This daemon verifies the `/run/media/usb/sda1` directory and copies the first 48 | `.tar` file in the directory to `/tmp/images` and starts verification. 49 | - Set ApplyTime to OnReset so that the proposed usb code update app does not 50 | reboot the BMC after activation. 51 | - Set RequestedActivation to Active, follow the updated status, start to update 52 | the firmware, and restart the BMC after completion. 53 | - Exit the phosphor-usb-code-update daemon. 54 | 55 | ## Pseudocode 56 | 57 | The udev rules files for example: 58 | 59 | ```udev 60 | SUBSYSTEM=="block", ACTION=="add", ENV{ID_USB_DRIVER}=="usb-storage", ENV{DEVTYPE}=="partition", ENV{SYSTEMD_WANTS}="usb-code-update@%k", TAG+="systemd" 61 | ``` 62 | 63 | ## Security 64 | 65 | - It is recommended to run a local CI run and analyze & avoid potential 66 | vulnerabilities via cppcheck. 67 | - Assuming that the USB drive has a physical security vulnerability (such as 68 | memory overflow, etc.), should disable "USB code update" via Redfish. After 69 | the vulnerability is fixed, enable "USB code update" again via Redfish. 70 | 71 | ## Alternatives Considered 72 | 73 | If the OS fails to boot due to an error, so the firmware update cannot be done 74 | through the OS, or the network fails, and the update cannot be done through 75 | Redfish or scp, the server support staff can only uninstall the flash chip and 76 | re-flashing, this is not Reasonably, service support should have local access to 77 | the machine and update the system to a working firmware level. 78 | 79 | ## Impacts 80 | 81 | This impacts security because it can copy files to the BMC via an external USB 82 | key. There is no expected performance impact since the process just copies files 83 | during runtime and exits automatically after completion. 84 | 85 | ## Testing 86 | 87 | - When the USB code update is disabled, the service will return directly without 88 | any update. 89 | - Manually insert the USB key with the firmware upgrade package, and check 90 | whether the upgrade file is correct through the log. 91 | - Simulate `dev/sda1` on qemu with some test scripts and start the service(eg: 92 | `systemcl start usb-code-update@sda1.service`) 93 | - Verify that the ApplyTime attribute value is set to OnRest. 94 | - Verify that the RequestedActivation property value is set to Active. 95 | - Verify that the firmware update was successful. 96 | 97 | [1]: https://github.com/openbmc/phosphor-bmc-code-mgmt 98 | -------------------------------------------------------------------------------- /style/cpp/.clang-format: -------------------------------------------------------------------------------- 1 | --- 2 | Language: Cpp 3 | # BasedOnStyle: LLVM 4 | AccessModifierOffset: -2 5 | AlignAfterOpenBracket: Align 6 | AlignConsecutiveAssignments: false 7 | AlignConsecutiveDeclarations: false 8 | AlignEscapedNewlines: Right 9 | AlignOperands: Align 10 | AlignTrailingComments: 11 | Kind: Always 12 | OverEmptyLines: 1 13 | AllowAllParametersOfDeclarationOnNextLine: true 14 | AllowShortBlocksOnASingleLine: Empty 15 | AllowShortCaseLabelsOnASingleLine: false 16 | AllowShortFunctionsOnASingleLine: Empty 17 | AllowShortIfStatementsOnASingleLine: Never 18 | AllowShortLambdasOnASingleLine: true 19 | AllowShortLoopsOnASingleLine: false 20 | AlwaysBreakBeforeMultilineStrings: false 21 | BinPackArguments: true 22 | BinPackParameters: true 23 | BitFieldColonSpacing: None 24 | BraceWrapping: 25 | AfterCaseLabel: true 26 | AfterClass: true 27 | AfterControlStatement: true 28 | AfterEnum: true 29 | AfterExternBlock: true 30 | AfterFunction: true 31 | AfterNamespace: true 32 | AfterObjCDeclaration: true 33 | AfterStruct: true 34 | AfterUnion: true 35 | BeforeCatch: true 36 | BeforeElse: true 37 | BeforeLambdaBody: false 38 | BeforeWhile: false 39 | IndentBraces: false 40 | SplitEmptyFunction: false 41 | SplitEmptyRecord: false 42 | SplitEmptyNamespace: false 43 | BreakAfterAttributes: Never 44 | BreakAfterReturnType: Automatic 45 | BreakBeforeBinaryOperators: None 46 | BreakBeforeBraces: Custom 47 | BreakBeforeTernaryOperators: true 48 | BreakConstructorInitializers: AfterColon 49 | BreakInheritanceList: AfterColon 50 | BreakStringLiterals: false 51 | BreakTemplateDeclarations: Yes 52 | ColumnLimit: 80 53 | CommentPragmas: '^ IWYU pragma:' 54 | CompactNamespaces: false 55 | ConstructorInitializerIndentWidth: 4 56 | ContinuationIndentWidth: 4 57 | Cpp11BracedListStyle: true 58 | DerivePointerAlignment: false 59 | DisableFormat: false 60 | FixNamespaceComments: true 61 | ForEachMacros: 62 | - foreach 63 | - Q_FOREACH 64 | - BOOST_FOREACH 65 | IncludeBlocks: Regroup 66 | IncludeCategories: 67 | - Regex: '^[<"](gtest|gmock)' 68 | Priority: 7 69 | - Regex: '^"config.h"' 70 | Priority: -1 71 | - Regex: '^".*\.h"' 72 | Priority: 1 73 | - Regex: '^".*\.hpp"' 74 | Priority: 2 75 | - Regex: '^<.*\.h>' 76 | Priority: 3 77 | - Regex: '^<.*\.hpp>' 78 | Priority: 4 79 | - Regex: '^<.*' 80 | Priority: 5 81 | - Regex: '.*' 82 | Priority: 6 83 | IndentCaseLabels: true 84 | IndentExternBlock: NoIndent 85 | IndentRequiresClause: true 86 | IndentWidth: 4 87 | IndentWrappedFunctionNames: true 88 | InsertNewlineAtEOF: true 89 | KeepEmptyLinesAtTheStartOfBlocks: false 90 | LambdaBodyIndentation: Signature 91 | LineEnding: LF 92 | MacroBlockBegin: '' 93 | MacroBlockEnd: '' 94 | MaxEmptyLinesToKeep: 1 95 | NamespaceIndentation: None 96 | ObjCBlockIndentWidth: 2 97 | ObjCSpaceAfterProperty: false 98 | ObjCSpaceBeforeProtocolList: true 99 | PackConstructorInitializers: BinPack 100 | PenaltyBreakAssignment: 25 101 | PenaltyBreakBeforeFirstCallParameter: 50 102 | PenaltyBreakComment: 300 103 | PenaltyBreakFirstLessLess: 120 104 | PenaltyBreakString: 1000 105 | PenaltyBreakTemplateDeclaration: 10 106 | PenaltyExcessCharacter: 1000000 107 | PenaltyReturnTypeOnItsOwnLine: 150 108 | PenaltyIndentedWhitespace: 1 109 | PointerAlignment: Left 110 | QualifierAlignment: Left 111 | ReferenceAlignment: Left 112 | ReflowComments: true 113 | RequiresClausePosition: OwnLine 114 | RequiresExpressionIndentation: Keyword 115 | SortIncludes: CaseSensitive 116 | SortUsingDeclarations: true 117 | SpaceAfterCStyleCast: false 118 | SpaceAfterTemplateKeyword: true 119 | SpaceBeforeAssignmentOperators: true 120 | SpaceBeforeCpp11BracedList: false 121 | SpaceBeforeCtorInitializerColon: true 122 | SpaceBeforeInheritanceColon: true 123 | SpaceBeforeParens: ControlStatements 124 | SpaceBeforeRangeBasedForLoopColon: true 125 | SpaceInEmptyParentheses: false 126 | SpacesBeforeTrailingComments: 1 127 | SpacesInAngles: Never 128 | SpacesInContainerLiterals: true 129 | SpacesInCStyleCastParentheses: false 130 | SpacesInParentheses: false 131 | SpacesInSquareBrackets: false 132 | Standard: Latest 133 | TabWidth: 4 134 | UseTab: Never 135 | ... 136 | 137 | -------------------------------------------------------------------------------- /logo/OpenBMC-Logo2.svg: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | 13 | 14 | 15 | 18 | 19 | 20 | 21 | 22 | 23 | 24 | 25 | 26 | 27 | 28 | 29 | 30 | 31 | 32 | 33 | 34 | 35 | -------------------------------------------------------------------------------- /designs/virtual-sensors.md: -------------------------------------------------------------------------------- 1 | # Virtual sensors 2 | 3 | Author: Vijay Khemka ; 4 | 5 | Created: 2020-05-13 6 | 7 | ## Problem Description 8 | 9 | There are some sensors in the system whose values are derived from actual sensor 10 | data and some other factor like fan speed for temperature sensors, some complex 11 | and non standard scale factors or some other algorithmic calculations. Some of 12 | Virtual sensor examples are: 13 | 14 | 1. Airflow: Function of Fan RPM reported in units of cubic-feet per second. 15 | 2. Voltage delta between two ADC inputs. When the actual diff is what which 16 | should not cross a threshold. 17 | 3. Power consumption when we have Energy/time. 18 | 19 | This design will allow to generate a new virtual sensors which are defined to be 20 | specific manipulation/function of existing sensors. 21 | 22 | ## Background and References 23 | 24 | None. 25 | 26 | ## Requirements 27 | 28 | This should implement a new virtual sensor for every given sensor and update 29 | them as per changes in existing sensors. This implementation should provide 30 | 31 | - a daemon to create and monitor each sensor defined in config file and update 32 | them based on value change in each given sensor. 33 | - Every virtual sensor will be waiting for event for change in dbus value of 34 | each sensor parameter and will update this sensor. 35 | - Sensor parameter can be any sensor dbus path and it also supports chaining of 36 | virtual sensors. 37 | - a dbus interface like other sensors to allow other services to access its data 38 | - capability to read parameter details from config file 39 | - capability to read a algorithm string from config file and use the same 40 | algorithm in calculating value for new virtual sensor 41 | 42 | ## Proposed Design 43 | 44 | Create a D-bus service "xyz.openbmc_project.VirtualSensor" with object paths for 45 | each sensor: "/xyz/openbmc_project/sensor/temperature/sensor_name" 46 | 47 | There is a JSON configuration file for name, old path and algorithm. For 48 | example, 49 | 50 | ```json 51 | { 52 | "Desc" : 53 | { 54 | "Name" : "Virtual_Inlet_Temp", 55 | "SensorType" : "temperature" 56 | }, 57 | "Params": 58 | { 59 | "ConstParam" : 60 | [ 61 | { 62 | "ParamName" : "P1", 63 | "Value" : 1.1 64 | } 65 | ], 66 | "DbusParam" : 67 | [ 68 | { 69 | "ParamName" : "P2", 70 | "Desc" : 71 | { 72 | "Name" : "MB_INLET_TEMP", 73 | "SensorType" : "temperature" 74 | } 75 | }, 76 | { 77 | "ParamName" : "P3", 78 | "Desc" : 79 | { 80 | "Name" : "MB_FAN0_TACH", 81 | "SensorType" : "fan_tach" 82 | } 83 | } 84 | ] 85 | }, 86 | "Expression": "P1 + P2 + 5 - P3 * 0.1", 87 | "Thresholds": 88 | { 89 | "CriticalHigh": 90, 90 | "CriticalLow": 20, 91 | "WarningHigh": 70, 92 | "WarningLow": 30 93 | } 94 | } 95 | 96 | Desc: It defines name and unit of a sensor. Main Desc object defines 97 | details about new virtual sensor and inside DbusParam object, 98 | it defines details about existing dbus sensors. 99 | Name: Name of virtual sensor 100 | SensorType: Unit type of sensors and supported 101 | Expression: An algorithm to be used to calculate sensor value 102 | Params: There are currently 2 types of parameter supported ConstParam 103 | and DbusParam. Every pamas should have a name to be reffered 104 | in expression 105 | ConstParam: This is a parameter which has a constant value defined here 106 | DbusParam: This is an existing/virtual sensor which is listed in dbus and 107 | it's value can be read from dbus path 108 | Thresholds: It has critical and warning high/low value to monitor sensor 109 | value and used as per sensor interface defined in 110 | phosphor-dbus-interfaces. 111 | 112 | ``` 113 | 114 | ## Alternatives Considered 115 | 116 | None 117 | 118 | ## Impacts 119 | 120 | This application is monitoring existing sensors whenever they change values then 121 | only it will update this sensors so impact should be very minimal. 122 | 123 | ## Testing 124 | 125 | Testing can be done by monitoring data read from dbus interface over a period of 126 | time and also can see these data if it changes by comparing with given sensors. 127 | -------------------------------------------------------------------------------- /designs/certificate-revocation-list.md: -------------------------------------------------------------------------------- 1 | # Certificate Revocation List on BMC 2 | 3 | Author: Nan Zhou 4 | 5 | Created: 02/25/2022 6 | 7 | ## Problem Description 8 | 9 | This design is to add management interfaces for certificate revocation list in 10 | OpenBMC. 11 | 12 | ## Background and References 13 | 14 | A certificate revocation list (CRL) is a list of digital certificates that have 15 | been revoked by the issuing certificate authority (CA) before their actual or 16 | assigned expiration date. In Google, there are use cases that BMC needs to 17 | install CRLs to the Redfish server, so that clients with revoked certificates 18 | will be rejected in TLS handshake. Supporting CRL is also recommended in most 19 | applications. 20 | 21 | Current OpenBMC certificate management architecture contains two main 22 | components. 23 | 24 | 1. [phosphor-certificate-manager](https://github.com/openbmc/phosphor-certificate-manager) 25 | owns certificate objects and implements management interfaces; currently 26 | there are three types of certificates supported: client, server, and 27 | authority. 28 | 29 | 2. [BMCWeb](https://github.com/openbmc/bmcweb): the Redfish front-end which 30 | translates certificate objects into Redfish resources. BMCWeb is also a 31 | consumer of these certificates; it uses certificates in its TLS handshake. 32 | 33 | DMTF doesn't support CRLs yet in the Redfish spec. Adding them is WIP. See 34 | [this discussion](https://redfishforum.com/thread/618/resource-certificate-revocation-list?page=1&scrollTo=2173). 35 | Google doesn't plan on using Redfish interfaces to manage certificates and CRLs. 36 | Instead, Google has a dedicated daemon for credentials installation, and this 37 | daemon interacts with the OpenBMC certificate management architecture via DBus 38 | APIs. 39 | 40 | ## Requirements 41 | 42 | OpenBMC supports management interface for CRLs: 43 | 44 | 1. clients shall be able to install/delete/replace CRLs via DBus APIs 45 | 2. whenever CRLs change, the certificate management system shall notify 46 | consumers which use old CRLs to refresh with the newly given CRLs 47 | 3. other daemons, e.g., BMCWeb shall consume CRLs the same way as existing 48 | authority/server/client certificates, that is, via file path or directory 49 | determined at compile time. 50 | 51 | ## Proposed Design 52 | 53 | ### phosphor-dbus-interfaces 54 | 55 | We propose to introduce a new interface `CRL` in 56 | [Certs](https://github.com/openbmc/phosphor-dbus-interfaces/tree/master/yaml/xyz/openbmc_project/Certs). 57 | 58 | Because no Redfish spec is available, we propose the only attribute of the 59 | interface to be `CRLString`, which contains the PEM encoded CRL. We can add more 60 | attributes as needed in the future. 61 | 62 | ### phosphor-certificate-manager 63 | 64 | We propose to add a new type of certificate-manager (CRL-manager) to the 65 | existing three types of Manager. 66 | 67 | The CRL-manager will implement the following common interfaces: 68 | 69 | 1. [InstallAll](https://github.com/openbmc/phosphor-dbus-interfaces/blob/master/yaml/xyz/openbmc_project/Certs/InstallAll.interface.yaml): 70 | install multiple CRLs and notify consumers. The notification process is the 71 | existing behaviour which phosphor-certificate-manager uses to tell consumers 72 | to reload newly installed credentials. 73 | 74 | 2. [ReplaceAll](https://github.com/openbmc/phosphor-dbus-interfaces/blob/master/yaml/xyz/openbmc_project/Certs/ReplaceAll.interface.yaml): 75 | replace all existing CRLs with multiple new CRLs and notify consumers 76 | 77 | 3. [DeleteAll](https://github.com/openbmc/phosphor-dbus-interfaces/blob/master/yaml/xyz/openbmc_project/Collection/DeleteAll.interface.yaml): 78 | delete all existing CRLs and notify consumers 79 | 80 | ### BMCWeb 81 | 82 | We propose to introduce CRLs into BMCWeb's SSL Context. Whenever BMCWeb reloads, 83 | it not only refreshes authority and server certificates, but also CRLs. Example 84 | codes can be found in many opensource projects, e.g., this 85 | [snippet](https://github.com/Icinga/icinga2/blob/master/lib/base/tlsutility.cpp#L338). 86 | 87 | ## Alternatives Considered 88 | 89 | We can model the whole CRLs list as a single object, but that's not aligned with 90 | the existing authorities list design. 91 | 92 | ## Impacts 93 | 94 | 1. New DBus interfaces 95 | 2. More complete security support 96 | 97 | ## Testing 98 | 99 | Add new unit tests in phosphor-certificate-manager. 100 | 101 | Manual integration tests: install CRLs and verify clients' revoked certificates 102 | are rejected. 103 | -------------------------------------------------------------------------------- /development/gerrit-setup.md: -------------------------------------------------------------------------------- 1 | # OpenBMC Gerrit Setup/Integration 2 | 3 | **Document Purpose:** Walkthrough configuring your workstation and a Gerrit 4 | account. This is needed to participate in OpenBMC's Gerrit-based code reviews. 5 | 6 | **Prerequisites:** Current Linux, Mac, or Windows system. Git packages 7 | installed. E-mail account (recommended to use the same e-mail address for both 8 | Gerrit and GitHub). 9 | 10 | ## Initial Setup 11 | 12 | ### Update Git Identity 13 | 14 | - `git config --global --add user.name "Your name" (eg. John Smith)` 15 | - `git config --global --add user.email "youremail@your-domain" (eg. jsmith@somedomain.com)` 16 | - (Optional) 17 | `git config --global --add diff.tool "preferred diff tool" (eg. gvimdiff or meld)` 18 | 19 | ### Setup SSH Keys 20 | 21 | Create keys: `ssh-keygen -t ed25519 -C "your_email@your-domain"` 22 | 23 | - Recommended to use the defaults instead of picking your own directory/file 24 | names. 25 | 26 | Add Keys to GitHub: 27 | 28 | - 29 | 30 | Add Keys to OpenBMC's Gerrit Server: 31 | 32 | - Login to [Gerrit](https://gerrit.openbmc.org/) with your GitHub account. 33 | - Go to 34 | - Your information should be auto-filled, so click "Next". 35 | - If successful you should see a blank screen, feel free to exit out. 36 | 37 | **NOTE** If you receive a "Not found" error while trying to add the keys to 38 | Gerrit you can add them manually: 39 | 40 | - Login to [Gerrit](https://gerrit.openbmc.org/) 41 | - Enter your public SSH key created before in Settings -> SSH Keys -> New SSH 42 | key 43 | - Click on "ADD NEW SSH KEY" 44 | - If succesfull you should see your public key added and with the status "Valid" 45 | 46 | ### Add e-mail to Gerrit 47 | 48 | - Login to [Gerrit](https://gerrit.openbmc.org/) 49 | - Enter e-mail in Settings -> Contact Information -> Register New E-Mail 50 | - Check e-mail for confirmation and click the link to confirm 51 | 52 | ### Add full name to Gerrit 53 | 54 | - Enter your full name in Settings -> Profile -> Full name 55 | 56 | ### Add SSH config entry 57 | 58 | Add the following to `~/.ssh/config`: 59 | 60 | ```bash 61 | Host openbmc.gerrit 62 | Hostname gerrit.openbmc.org 63 | Port 29418 64 | User 65 | ``` 66 | 67 | - **NOTE**: There is a bug in AFS that requires `AFSTokenPassing no` to be added 68 | to the SSH entry if using AFS. 69 | - Your Gerrit Username can be found in Gerrit under Settings -> Profile -> 70 | Username 71 | - Ensure proper permissions for for your .ssh directory: `chmod 600 ~/.ssh/*` 72 | 73 | ### Confirm Setup Success 74 | 75 | Test connectivity to Gerrit by attempting to clone a repo 76 | 77 | - `git clone ssh://openbmc.gerrit/openbmc/docs` 78 | - If successful you should see something like: 79 | `Checking out files: 100% (45/45), done.` 80 | 81 | ### Add Hooks 82 | 83 | Inside the repo you just cloned, enter the following commands: 84 | 85 | ```bash 86 | gitdir=$(git rev-parse --git-dir) 87 | curl https://gerrit.openbmc.org/tools/hooks/commit-msg -o ${gitdir}/hooks/commit-msg 88 | chmod +x ${gitdir}/hooks/commit-msg 89 | ``` 90 | 91 | This will enhance the `git commit` command to add a `Change-Id` to your commit 92 | message which Gerrit uses to track the review. 93 | 94 | ### Push Code Change to Gerrit 95 | 96 | Now that your workstation and Gerrit are configured, you are ready to make code 97 | changes and push them to Gerrit for code review. Here is what the basic workflow 98 | will look like. 99 | 100 | - Make your code changes 101 | - Add those files to the index to be committed: 102 | `git add [file1 file2 ... fileN]` 103 | - Commit your changes, adding a Signed-off-by line to it (more on 104 | [writing good commit messages](https://github.com/openbmc/docs/blob/master/CONTRIBUTING.md#submitting-changes)): 105 | `git commit --signoff` 106 | - Push your changes to Gerrit for code review: 107 | `git push origin HEAD:refs/for/master` 108 | - Go to [Gerrit web interface](https://gerrit.openbmc.org/), click on your new 109 | review, and add reviewers based on `OWNERS` file in the repo. 110 | 111 | ## Conclusion 112 | 113 | If you've completed all of the above steps successfully, that's it! You have now 114 | set up Gerrit and know how to submit your code changes for review! 115 | 116 | Submitting changes for review is just one of many steps in the contributing 117 | process. Please see 118 | [CONTRIBUTING](https://github.com/openbmc/docs/blob/master/CONTRIBUTING.md) for 119 | best practices. 120 | -------------------------------------------------------------------------------- /designs/sol-sysrq.md: -------------------------------------------------------------------------------- 1 | # SysRq Support in SOL 2 | 3 | Author: Lei Yu 4 | 5 | Other contributors: Chen Tingting, Xie Xinnan 6 | 7 | Created: Aug 02, 2023 8 | 9 | ## Problem Description 10 | 11 | [SysRq][1] is a special key combination used by Linux to perform various 12 | low-level commands. BMC usually provides SysRq support in KVM and SOL functions, 13 | but this is not available in OpenBMC. This doc is to provide the SysRq support 14 | in OpenBMC's SOL. 15 | 16 | ## Background and References 17 | 18 | The key combination consists of Alt+SysRq (usually the `PrintScreen` key) and 19 | another key, which controls the command issued. This is not typical key code and 20 | requires special handling. A serial console usually invokes SysRq feature by 21 | sending a serial break signal, followed by the desired key. The "break signal" 22 | is usually generated by `ctrl+break` key combination.[2] 23 | 24 | In ipmitool, the "break signal" is implemented in [ipmi_sol.c][3] by handling 25 | the special `\n~B` keys. 26 | 27 | ## Requirements 28 | 29 | OpenBMC SOL involves several ways: 30 | 31 | - The ipmitool SOL. 32 | - The SOL in WebUI. 33 | - The console with SSH (default) 2200 port. 34 | 35 | ## Proposed Design 36 | 37 | In OpenBMC, the service `obmc-console-server` provides the host console and 38 | could be connected by multiple clients, using unix domain socket. 39 | 40 | To implement the SysRq in OpenBMC SOL for ipmi and WebUI, the special key code 41 | sequence `\n~B` is used to send the "break signal" between clients and 42 | console-server. In `obmc-console`, a state machine shall handle the sequence. 43 | Once the sequence is detected, it could invoke `tcsendbreak()` to send the 44 | "break signal" to the Host. 45 | 46 | ### netipmid 47 | 48 | In `phosphor-ipmi-net`, the code in `processInboundPayload()` shall handle the 49 | break signal from ipmitool, and send the sequence `\n~B` to the server. 50 | 51 | Then in ipmitool SOL session, user could enter `\n~B` keys to trigger the break, 52 | and then enter a keycode as the SysRq command. 53 | 54 | ### WebUI 55 | 56 | There are no changes required in WebUI, like netipmid, the user could enter the 57 | key code sequence `\n~B` to trigger the break, and then user could enter a 58 | keycode as the SysRq command. 59 | 60 | ### obmc-console 61 | 62 | As the obmc-console server, in `console-server.h`, a simple state machine is 63 | used to detect the sequence `\n~B`: 64 | 65 | ```mermaid 66 | --- 67 | title: SysRq escape state machine 68 | --- 69 | stateDiagram-v2 70 | [*] --> Empty 71 | Empty --> Emit: [^#92;n] 72 | Emit --> [*] 73 | Empty --> Newline: [#92;n] 74 | Newline --> Escape: [~] 75 | Newline --> EmitNewline: [^#92;n] 76 | Escape --> EmitEscapeCode: [B] 77 | EmitEscapeCode --> [*] 78 | EmitNewline --> [*] 79 | Escape --> EmitNewlineTilde: [^B] 80 | EmitNewlineTilde --> [*] 81 | ``` 82 | 83 | If `EmitEscapeCode` state is reached, it shall call `tcsendbreak()` to send the 84 | "break message" to the Host. 85 | 86 | ## Alternatives Considered 87 | 88 | An alternative way to send the "break signal" between clients and console-server 89 | is use `MSG_OOB` as the indicator of sysrq. The `MSG_OOB` was already introduced 90 | to [netipmid][4] as the indicator of sysrq. In this solution, bmcweb shall be 91 | modified to send `MSG_OOB` to obmc-console when the user enter the key code 92 | sequence `\n~B`. When obmc-console receive `MSG_OOB`, it shall send the "break 93 | message" to the Host. 94 | 95 | However, in this solution, in some scenarios, obmc-console can not handle the 96 | input sequence correctly, as `MSG_OOB` can be anywhere in the input sequence. It 97 | is possible to synchronise the `MSG_OOB` with the stream with 98 | [sockatmark(3)][5]. But it requires signalling the `MSG_OOB` in all obmc-console 99 | clients, which is more work than the state machine solution. 100 | 101 | ## Impacts 102 | 103 | Below services need minor changes to add the SysRq support: 104 | 105 | - netipmid 106 | - obmc-console 107 | 108 | ## Testing 109 | 110 | The SysRq in SOL could be verified in both ipmitool SOL and WebUI SOL. In SOL 111 | with SSH, we need enter the key code sequence with more than one tilde. Like 112 | sequence `\n~~B`, the first tilde will be processed by obmc-console-client, the 113 | second tilde will reach obmc-console-server. 114 | 115 | [1]: https://en.wikipedia.org/wiki/Magic_SysRq_key 116 | [2]: https://www.kernel.org/doc/html/latest/admin-guide/sysrq.html 117 | [3]: https://github.com/ipmitool/ipmitool/blob/master/lib/ipmi_sol.c#L1398-L1401 118 | [4]: 119 | https://github.com/openbmc/phosphor-net-ipmid/commit/ec4374146147e339132243725d345eb30ec2da1d 120 | [5]: https://man7.org/linux/man-pages/man3/sockatmark.3.html 121 | -------------------------------------------------------------------------------- /release/metrics/2019-11: -------------------------------------------------------------------------------- 1 | ampere 2 | 1000252 chuongtranle,0 3 | 1000249 hyche,0 4 | 1000245 TungVuX,0 5 | 1000248 hienvpham,0 6 | 1000267 thinhp,0 7 | November, 0 8 | 9 | facebook 10 | 1000212 amithash,0 11 | 1000223 sdasari73,0 12 | 1000271 vijaykhemka,7 13 | November, 7 14 | 15 | google 16 | 1000233 BenjaminFair,14 17 | 1000388 brandonkimbk,3 18 | 1000099 nasamuffin,1 19 | 1000156 kunyi731,9 20 | 1000313 mgersh,0 21 | 1000052 yuennancy,0 22 | 1000265 osenft,0 23 | 1000100 pstrinkle,7 24 | 1000188 wak-google,2 25 | 1000337 linyy1106,0 26 | 1000442 oferye,0 27 | November, 36 28 | 29 | ibm 30 | 1000453 sotaoverride,4 31 | 1000160 aditya0124,0 32 | 1000003 anoo1,6 33 | 1000177 agusrod28,0 34 | 1000353 Alpana07,2 35 | 1000004 geissonator,8 36 | 1000009 amboar,1 37 | 1000075 antwil,1 38 | 1000358 adathatri,6 39 | 1000401 asmithakarun,0 40 | 1000085 bjwyman,1 41 | 1000364 nomuken007,0 42 | 1000002 bradbishop,199 43 | 1000355 bstegmiller,0 44 | 1000360 cnpalmer,0 45 | 1000193 camvanng,0 46 | 1000440 wangkair,2 47 | 1000058 charleshofer,0 48 | 1000001 causten,0 49 | 1000078 cbostic,0 50 | 1000040 legoater,0 51 | 1000056 dkodihal,7 52 | 1000281 derick-montague,1 53 | 1000084 dhruvibm,0 54 | 1000396 dixsie,2 55 | 1000025 eddiejames,1 56 | 1000171 vazpando,0 57 | 1000170 ernestrcmx,0 58 | 1000018 gkeishin,6 59 | 1000020 gtmills,12 60 | 1000102 iftekharuli,0 61 | 1000086 ojayanth,0 62 | 1000207 jaypadath,0 63 | 1000441 jenkins-openbmc-ibm,0 64 | 1000016 jk-ozlabs,15 65 | 1000348 jinuthomas,0 66 | 1000013 shenki,11 67 | 1000235 joseph-reynolds,0 68 | 1000202 onye1,1 69 | 1000110 thalerj,0 70 | 1000049 krtaylor,0 71 | 1000103 lkammath,2 72 | 1000044 mine260309,19 73 | 1000089 devenrao,2 74 | 1000206 manojkiraneda,0 75 | 1000152 garzam,2 76 | 1000008 spinler,26 77 | 1000029 msbarth,1 78 | 1000145 youhour,0 79 | 1000026 micwalsh,14 80 | 1000021 mdmillerii,0 81 | 1000403 miramurali23,0 82 | 1000141 ngorugan,0 83 | 1000435 NamanNH,2 84 | 1000370 Paul-Greenwood,0 85 | 1000053 prkatti1,0 86 | 1000362 PriyangaRamasamy,1 87 | 1000028 rahulmah,6 88 | 1000427 RameshIyyar,1 89 | 1000022 ratagupt,0 90 | 1000350 raviteja-b,0 91 | 1000258 BeccaBroek,0 92 | 1000214 ryanarnell,0 93 | 1000181 sampmisr,3 94 | 1000015 sammj,0 95 | 1000346 sansomas,0 96 | 1000338 santoshpuranik,0 97 | 1000148 Shakeebbk,0 98 | 1000331 smccarney,16 99 | 1000019 sivassrr,0 100 | 1000027 SrideviRamesh,2 101 | 1000042 swanman,0 102 | 1000129 ssombar,3 103 | 1000081 sjitindarsingh,0 104 | 1000423 susilsi7,2 105 | 1000073 swe12345,0 106 | 1000344 trajeswaran,0 107 | 1000005 tomjoseph83,0 108 | 1000393 vkaverap,3 109 | 1000402 yoshiemuranaka,5 110 | 1000421 zaxxed,0 111 | 1000359 zane131,3 112 | 1000369 bentyner,0 113 | 1000162 navrathi,0 114 | 1000121 samahaba,2 115 | 1000382 sunharis,0 116 | November, 401 117 | 118 | inspur 119 | 1000400 ChicagoDuan,0 120 | 1000397 lxwinspur,3 121 | 1000305 wangzqbj,17 122 | 1000444 XiaochaoMa,1 123 | November, 21 124 | 125 | intel 126 | 1000269 apuli1,8 127 | 1000290 czarOn,0 128 | 1000376 ygangch,3 129 | 1000304 cyang29,1 130 | 1000253 dfrycki,0 131 | 1000419 sahudx,0 132 | 1000153 edtanous,14 133 | 1000412 Gade-RajasekharReddy,5 134 | 1000166 yoojae,0 135 | 1000164 feistjj,22 136 | 1000157 JamesMihm,0 137 | 1000276 jmbills,9 138 | 1000300 hcleepinga,0 139 | 1000215 cjia4,0 140 | 1000278 Howitzer105mm,4 141 | 1000415 Joshi-Mansi,2 142 | 1000438 kamkowalski,2 143 | 1000439 KlaudiaJ,0 144 | 1000218 kuiyingw,2 145 | 1000413 nitin1sx,0 146 | 1000374 nipot,0 147 | 1000246 prapkiewicz,0 148 | 1000472 pmatuszc,1 149 | 1000460 phawryle,0 150 | 1000298 radivojejovanovic,0 151 | 1000414 Rashmi-RV,0 152 | 1000424 yuren1x,0 153 | 1000168 rthomaiy,11 154 | 1000418 saravanan-palanisamy,0 155 | 1000411 Smriti-Ayushi,1 156 | 1000410 sumbhat90,0 157 | 1000295 htnakayrus,0 158 | 1000409 tsdunc,0 159 | 1000163 vmauery,2 160 | 1000434 wgolgowski,0 161 | 1000330 qiangxu1,0 162 | 1000107 yongli3,8 163 | 1000371 yli-i,0 164 | 1000433 zkurzyns,9 165 | 1000366 RodgerZhu,0 166 | 1000417 anilkumarappana,1 167 | 1000416 jayaprakashmutyala,3 168 | November, 108 169 | 170 | inventec 171 | 1000228 YangBrianCW,0 172 | 1000104 KenChenIEC,0 173 | November, 0 174 | 175 | nuvoton 176 | 1000273 maxdog988,1 177 | 1000343 medadyoung,1 178 | 1000289 oshalk,0 179 | 1000342 stanleychuys,1 180 | 1000294 timlee66,0 181 | 1000190 tmaimon,0 182 | 1000268 warp5tw,0 183 | November, 3 184 | 185 | quanta 186 | 1000384 dukedu83,0 187 | 1000325 Fran-Hsu,0 188 | 1000357 georgehung1210,0 189 | 1000391 hank93304,0 190 | 1000317 PKLee-Quanta,0 191 | 1000329 jiangchyishian,1 192 | 1000335 tonylee79,0 193 | 1000322 YHLiang85,1 194 | November, 2 195 | 196 | yadro 197 | 1000192 AlexanderAmelkin,0 198 | 1000219 nest1ing,1 199 | 1000131 artemsen,0 200 | 1000182 fr0st61te,0 201 | 1000225 Ramkosh,0 202 | 1000422 alexeistepanov,0 203 | November, 1 204 | 205 | -------------------------------------------------------------------------------- /features.md: -------------------------------------------------------------------------------- 1 | # OpenBMC Features 2 | 3 | Follow links to learn more about OpenBMC features: 4 | 5 | - [BMCWeb][] HTTP/Web server 6 | - [WebUI Vue][] web application 7 | - REST Management: [BMCWeb Redfish][], [Phosphor REST APIs][] includes [Host 8 | management REST APIs][] 9 | - [D-Bus interfaces][] describes internal interfaces 10 | - [D-Bus Object Mapper][] 11 | - [Remote KVM][] 12 | - [IPMI in band][] and [IPMI out of band][] 13 | - Full IPMI 2.0 Compliance with DCMI 14 | - SSH based SOL: [How to use][sol how to use] 15 | - Power and Cooling Management: [Phosphor Fan Control][] 16 | - [Logging][phosphor logging] and [Callouts][logging callouts] 17 | - Zeroconf discoverable through `systemd-networkd` 18 | - [Sensors][] 19 | - Inventory: [Entity manager][], [Phosphor inventory manager][] and its [MSL 20 | application][] 21 | - [LEDs][]: see also [LED Groups][] 22 | - Host Watchdog: [Phosphor Watchdog Implementation][] 23 | - [Power State management] and [Chassis Power control][] 24 | - [Network management][] 25 | - [Factory reset][] 26 | - [User management][phosphor user management] 27 | - Time (time of day clock) management 28 | - [Certificate management][]: [Phosphor Certificate Manager][] 29 | - [Simulation][] via QEMU 30 | - [Firmware update support][] 31 | - [Automated Testing][] 32 | - LDAP 33 | - Remote syslog 34 | 35 | ## OpenPOWER Features 36 | 37 | - [POWER OCC Support][power occ implementation] (On Chip Controller) 38 | - [Hardware Diagnostics][] for POWER Systems fatal hardware errors. 39 | 40 | [automated testing]: 41 | https://github.com/openbmc/openbmc-test-automation/blob/master/README.md 42 | [bmcweb]: https://github.com/openbmc/bmcweb/blob/master/README.md 43 | [bmcweb redfish]: 44 | https://github.com/openbmc/bmcweb/blob/master/DEVELOPING.md#redfish 45 | [certificate management]: 46 | https://github.com/openbmc/phosphor-dbus-interfaces/tree/master/yaml/xyz/openbmc_project/Certs/README.md 47 | [chassis power control]: 48 | https://github.com/openbmc/phosphor-dbus-interfaces/blob/master/yaml/xyz/openbmc_project/Chassis/README.md 49 | [d-bus interfaces]: 50 | https://github.com/openbmc/phosphor-dbus-interfaces/blob/master/README.md 51 | [d-bus object mapper]: 52 | https://github.com/openbmc/docs/blob/master/architecture/object-mapper.md 53 | [entity manager]: 54 | https://github.com/openbmc/entity-manager/blob/master/README.md 55 | [factory reset]: 56 | https://github.com/openbmc/phosphor-dbus-interfaces/tree/master/yaml/xyz/openbmc_project/Common/FactoryReset/README.md 57 | [firmware update support]: 58 | https://github.com/openbmc/docs/blob/master/architecture/code-update/code-update.md 59 | [hardware diagnostics]: 60 | https://github.com/openbmc/openpower-hw-diags/blob/master/README.md 61 | [host management rest apis]: 62 | https://github.com/openbmc/docs/blob/master/host-management.md 63 | [ipmi in band]: 64 | https://github.com/openbmc/docs/blob/master/architecture/ipmi-architecture.md 65 | [ipmi out of band]: https://github.com/openbmc/ipmitool/blob/master/README 66 | [led groups]: 67 | https://github.com/openbmc/phosphor-dbus-interfaces/blob/master/yaml/xyz/openbmc_project/Led/README.md 68 | [leds]: 69 | https://github.com/openbmc/docs/blob/master/architecture/LED-architecture.md 70 | [logging callouts]: 71 | https://github.com/openbmc/phosphor-dbus-interfaces/tree/master/yaml/xyz/openbmc_project/Common/Callout/README.md 72 | [msl application]: 73 | https://github.com/openbmc/phosphor-dbus-monitor/blob/master/mslverify/README.md 74 | [network management]: 75 | https://github.com/openbmc/phosphor-dbus-interfaces/blob/master/yaml/xyz/openbmc_project/Network/README.md 76 | [phosphor certificate manager]: 77 | https://github.com/openbmc/phosphor-certificate-manager/blob/master/README.md 78 | [phosphor fan control]: 79 | https://github.com/openbmc/phosphor-fan-presence/blob/master/README.md 80 | [phosphor inventory manager]: 81 | https://github.com/openbmc/phosphor-inventory-manager/blob/master/README.md 82 | [phosphor logging]: 83 | https://github.com/openbmc/phosphor-logging/blob/master/README.md 84 | [phosphor rest apis]: https://github.com/openbmc/docs/blob/master/rest-api.md 85 | [phosphor user management]: 86 | https://github.com/openbmc/docs/blob/master/architecture/user-management.md 87 | [phosphor watchdog implementation]: https://github.com/openbmc/phosphor-watchdog 88 | [power occ implementation]: https://github.com/openbmc/openpower-occ-control 89 | [remote kvm]: https://github.com/openbmc/obmc-ikvm/blob/master/README.md 90 | [sensors]: 91 | https://github.com/openbmc/docs/blob/master/architecture/sensor-architecture.md 92 | [simulation]: 93 | https://github.com/openbmc/docs/blob/master/development/dev-environment.md 94 | [power state management]: 95 | https://github.com/openbmc/phosphor-dbus-interfaces/blob/master/yaml/xyz/openbmc_project/State/README.md 96 | [sol how to use]: https://github.com/openbmc/docs/blob/master/console.md 97 | [webui vue]: https://github.com/openbmc/webui-vue/blob/master/README.md 98 | -------------------------------------------------------------------------------- /testing/run-test-docker.md: -------------------------------------------------------------------------------- 1 | # Run OpenBMC Test Automation Using Docker 2 | 3 | Running OpenBMC automation using Docker involves creating a Docker image and 4 | then running automation tests inside the Docker container. 5 | 6 | ## Build Docker Image 7 | 8 | `Note: Prerequisite is to have Docker installed.` 9 | 10 | 1. Create a workspace directory. 11 | 12 | `mkdir ${HOME}/OpenBMC_Automation` 13 | 14 | 2. Change directory to workspace created. 15 | 16 | `cd ${HOME}/OpenBMC_Automation` 17 | 18 | 3. Clone openbmc-build-scripts repository. 19 | 20 | `git clone https://github.com/openbmc/openbmc-build-scripts` 21 | 22 | 4. Change directory to openbmc-build-scripts. 23 | 24 | `cd openbmc-build-scripts` 25 | 26 | 5. Build the Docker image required to execute the robot tests (it may take close 27 | to 15 mins for the first time). The default Docker image name is 28 | "openbmc/ubuntu-robot-qemu". You can check images using "docker images" 29 | command. 30 | 31 | `./scripts/build-qemu-robot-docker.sh` 32 | 33 | **Note:** When your Docker is behind a proxy, add the following parameters to 34 | the build command (use proper IP and PORT values.) 35 | 36 | ```bash 37 | --build-arg http_proxy=: --build-arg https_proxy=: 38 | ``` 39 | 40 | ## Code update process using robot test code 41 | 42 | 1. Change directory to HOME workspace. 43 | 44 | `cd ${HOME}/OpenBMC_Automation` 45 | 46 | 2. Clone openbmc-test-automation repository. 47 | 48 | `git clone https://github.com/openbmc/openbmc-test-automation` 49 | 50 | 3. Execute docker run to initiate BMC code update. 51 | 52 | **Note:** Download BMC fw image file (`_.all.tar`) before executing this. 53 | `BMC\*IMG_PATH` below points to this downloaded file. 54 | 55 | ```bash 56 | docker run --user root \ 57 | --env HOME=${HOME} \ 58 | --workdir ${HOME} \ 59 | --volume ${HOME}/OpenBMC_Automation:${HOME} \ 60 | --tty openbmc/ubuntu-robot-qemu python -m robot \ 61 | -v OPENBMC_HOST: \ 62 | -v FILE_PATH: \ 63 | -i Initiate_Code_Update_BMC \ 64 | ${HOME}/openbmc-test-automation/extended/code_update/update_bmc.robot 65 | ``` 66 | 67 | Example to run BMC code update using witherspoon-20170614071422.all.tar image 68 | file from HOME directory of the system where docker run command is executed: 69 | 70 | ```bash 71 | docker run --user root \ 72 | --env HOME=${HOME} \ 73 | --workdir ${HOME} \ 74 | --volume ${HOME}/OpenBMC_Automation:${HOME} \ 75 | --tty openbmc/ubuntu-robot-qemu python -m robot \ 76 | -v OPENBMC_HOST:1.11.222.333 \ 77 | -v FILE_PATH:/home/witherspoon-20170614071422.all.tar \ 78 | -i Initiate_Code_Update_BMC \ 79 | ${HOME}/openbmc-test-automation/extended/code_update/update_bmc.robot 80 | ``` 81 | 82 | 4. On code update completion, logs generated from robot framework execution will 83 | be available in the following location: 84 | 85 | ```bash 86 | ${HOME}/OpenBMC_Automation/log.html 87 | ${HOME}/OpenBMC_Automation/report.html 88 | ${HOME}/OpenBMC_Automation/output.xml 89 | ``` 90 | 91 | ## Executing Automation Test 92 | 93 | 1. Execute docker run to execute OpenBMC automation test cases. 94 | 95 | **Note:** This runs a Docker container using openbmc/ubuntu-robot-qemu image. 96 | 97 | Robot test code is extracted and ran on this container using run-robot.sh 98 | script. 99 | 100 | ```bash 101 | docker run --user root \ 102 | --env HOME=${HOME} \ 103 | --env IP_ADDR= \ 104 | --env SSH_PORT=22 \ 105 | --env HTTPS_PORT=443 \ 106 | --env ROBOT_TEST_CMD="tox -e -- " \ 107 | --workdir ${HOME} \ 108 | --volume ${WORKSPACE}:${HOME} \ 109 | --tty openbmc/ubuntu-robot-qemu \ 110 | ${HOME}/openbmc-build-scripts/scripts/run-robot.sh 111 | ``` 112 | 113 | Example to run entire test suite: 114 | 115 | ```bash 116 | docker run --user root \ 117 | --env HOME=${HOME} \ 118 | --env IP_ADDR=1.11.222.333 \ 119 | --env SSH_PORT=22 \ 120 | --env HTTPS_PORT=443 \ 121 | --env ROBOT_TEST_CMD="tox -e witherspoon -- tests" \ 122 | --workdir ${HOME} \ 123 | --volume ${HOME}/OpenBMC_Automation:${HOME} \ 124 | --tty openbmc/ubuntu-robot-qemu \ 125 | ${HOME}/openbmc-build-scripts/scripts/run-robot.sh 126 | ``` 127 | 128 | 2. After the execution, test results will be available in below files. 129 | 130 | ```bash 131 | ${HOME}/OpenBMC_Automation/log.html 132 | ${HOME}/OpenBMC_Automation/report.html 133 | ${HOME}/OpenBMC_Automation/output.xml` 134 | ``` 135 | -------------------------------------------------------------------------------- /designs/cper-records.md: -------------------------------------------------------------------------------- 1 | # CPER records - CPER 2 | 3 | Author: Ed Tanous - edtanous 4 | 5 | Created: 5-22-2024 6 | 7 | ## Problem Description 8 | 9 | Server CPUs expose a managability interface refered to as CPER records. A user 10 | outside of the BMC would like to read these records in a decoded state, rather 11 | than as a raw package. 12 | 13 | ## Background and References 14 | 15 | CPER stands for Common Platform Error Record and is defined as an industry 16 | standard in the [UEFI Specification][uefi_spec], with CPU ISA specific 17 | definitions for aarch64, x64, Itanium, and IA32. Within this document there are 18 | several architecture definitions for BMC, including section C.2.2 RAS IPMI 19 | Message Format, and IPMI based RAS Event Receiver. 20 | 21 | In Redfish specification drop 2021.3, Redfish added support for CPER records 22 | into the [LogEntry resource][logentry]. These expose a section by section 23 | decoded CPER instance. In addition to Redfish, there is a proposed DMTF 24 | interface for sending CPER log events to the BMC using [MCTP/PLDM][cperevent], 25 | which is proposed to be added in a future version of DMTF [DSP0248]. 26 | 27 | ARM has developed a reference library for decoding CPER records that does not 28 | have a contribution mechanism, releases, or maintenance, and they have made 29 | [clear][cper_examples] that they would like OpenBMC to be the long-term 30 | custodian of this library. 31 | 32 | This library hosts the meson-dev branch, which was added for the purpose of this 33 | design, and passes the OpenBMC CI tests currently. This is the proposed branch 34 | that will be pushed to openbmc/libcper, if approved. 35 | 36 | ## Requirements 37 | 38 | - A BMC should be able to decode binary CPER records originated from a CPER 39 | compatible CPU. 40 | 41 | - BMC should be able to recieve and decode CPER records from a CPU per the [CPER 42 | specification][arm_sbmr]. 43 | 44 | - A BIOS/EDK2 build should be able to share decoding code with OpenBMC, to the 45 | end that added records do not require manual effort to implement in each 46 | codebase. 47 | 48 | - A CPU vendor should be able to add support for CPER extensions that OpenBMC 49 | will now be able to decode, without impacting users of other vendors, as 50 | promised in the CPER specification. 51 | 52 | - CPER decoder should allow decoding of multiple CPU complexes. 53 | 54 | ## Proposed Design 55 | 56 | While this design fits into a much more elaborate design alluded to in the 57 | aformentioned ARM document, this document only requests the first step, creating 58 | a shared library implementation within the OpenBMC organization that can be 59 | built upon over time, but might not implement the complete implementation at 60 | this time. It is expected that the ubiquity of CPER records in the BMC ecosystem 61 | justifies the creation of the repository, even if the initial implementation 62 | might not meet all design goals for all contributors, having a common 63 | contribution model, CI testing, and license is beneficial as a whole. 64 | 65 | Future design docs (or amendments to this design) will iterate on implementing 66 | more of the design referenced in this [CPER specification][arm_sbmr], for common 67 | ARM platforms, but getting the custody transferred for the libcper repo, getting 68 | the quality up to standards is the initial goal of this design. 69 | 70 | ## Alternatives Considered 71 | 72 | Rewrite libcper decoding from a new design point. While this is certainly 73 | possible given the small size of the libcper repo as it exists today, it would 74 | bifurcate already existing implementations of the decode. 75 | 76 | ## Impacts 77 | 78 | New repo will be created within the organization. New recipe will be added to 79 | OpenBMC. 80 | 81 | ### Organizational 82 | 83 | - Does this repository require a new repository? Yes 84 | - Who will be the initial maintainer(s) of this repository? Ed Tanous 85 | - Which repositories are expected to be modified to execute this design? 86 | - openbmc/openbmc 87 | - openbmc/libcper 88 | 89 | #### Potentionally in the future 90 | 91 | - openbmc/phosphor-debug-collector 92 | - openbmc/bmcweb 93 | - openbmc/phosphor-logging 94 | 95 | ## Testing 96 | 97 | Unit tests are already present in the repo to verify basic functionality. 98 | CPU-model specific error generators will be used to simulate the full path, once 99 | design is complete. 100 | 101 | [arm_sbmr]: https://developer.arm.com/documentation/den0069/latest/ 102 | [uefi_spec]: https://uefi.org/specifications 103 | [logentry]: 104 | https://github.com/DMTF/Redfish-Publications/blob/5b217908b5378b24e4f390c063427d7a707cd308/csdl/LogEntry_v1.xml#L1403 105 | [cperevent]: 106 | https://www.dmtf.org/sites/default/files/PMCI_CPEREvent_Proposal_v3.pdf 107 | [DSP0248]: https://www.dmtf.org/dsp/DSP0248 108 | [cper_examples]: 109 | https://gitlab.arm.com/server_management/libcper/-/blob/b8b687c2e05846afd37b60222a0b4253acda81fd/README.md#usage-examples 110 | -------------------------------------------------------------------------------- /designs/bmc-reboot-cause-update.md: -------------------------------------------------------------------------------- 1 | # BMC Boot Cause Event Log 2 | 3 | Author: Patrick Lin (patrick_lin_wiwynn) 4 | 5 | Other contributors: Delphine Chiu(delphinechiu), Bonnie Lo(bonnielo), Ricky 6 | Wu(ricky_cx_wu) 7 | 8 | Created: Aug 19, 2024 9 | 10 | ## Problem Description 11 | 12 | Currently, OpenBMC lacks a unified method that meets the needs of various 13 | vendors to record different types of BMC reboot cause event logs. The purpose of 14 | this proposal is to update the existing method, consolidating more BMC reboot 15 | causes to better align with current usage needs. 16 | 17 | ## Background and References 18 | 19 | In the current approach, the only defined reboot causes are **WDIOF_EXTERN1** 20 | and **WDIOF_CARDRESET**, but this is insufficient to meet today's needs. 21 | However, due to varying needs among different vendors, it’s not feasible to 22 | cover all possible reboot causes. In this update, we will add support for 23 | several more common types. 24 | 25 | ## Requirements 26 | 27 | 1. Each BMC vendor needs to provide or update their driver to retrieve the 28 | corresponding BMC reboot cause. 29 | 2. Each BMC vendor needs to record the results of the retrieved reboot cause to 30 | the specified path. 31 | 3. Each vendor needs to ensure the accuracy of interpreting the reboot cause 32 | results. 33 | 4. New reboot cause types need to be defined to cover the requirements 34 | 5. Revise the definitions of certain existing reboot cause types to better 35 | represent their respective conditions. 36 | 6. Ensure that methods based on the original design can adapt well to this 37 | change. 38 | 39 | ## Proposed Design 40 | 41 | ```mermaid 42 | flowchart TD 43 | A[BMC reboot] --> B[Driver get the reboot cause] 44 | B --> C[Driver set the corresponding flag based on the reboot cause to /sys/class/watchdog/watchdog0/bootstatus] 45 | C --> D[phosphor-state-manager get the flag] 46 | D --> E[Log the corresponding event based the the different flag] 47 | ``` 48 | 49 | After a BMC reboot, each BMC vendor’s driver first retrieves the reboot cause. 50 | Then, based on the reboot cause, it sets different flags to the specified path. 51 | The PSM (Phosphor-state-manager) reads the flags from the specified path to 52 | determine the type of reboot cause. Finally, it generates the corresponding 53 | event log based on the determination. 54 | 55 | This process ensures accurate logging and handling of different BMC reboot 56 | causes, improving system reliability and monitoring. Belows are the details of 57 | the new additions and changes: 58 | 59 | 1. Driver Provision by BMC Vendors: 60 | - Each BMC vendor must provide a driver to retrieve the BMC reboot cause and 61 | record the result at the specified location. 62 | 63 | 2. Definition and Identification of Reboot Cause Type **Software Reset**: 64 | - This one is still under discussion, please refer to the following link for 65 | more detail: 66 | 67 | 68 | 3. Revise the Definition of **WDIOF_CARDRESET**: 69 | - The **WDIOF_CARDRESET** type will now specifically indicate resets caused 70 | by the watchdog. 71 | 72 | 4. Clarification of The **Power-on-reset case**: 73 | - When a BMC reset occured, but the flag in the bootstatus remains unchanged 74 | by the watchdog driver (i.e., it stays at 0), this indicates that a 75 | **Power-on-reset** has occurred. 76 | 77 | 5. Update Reboot Cause Interpretation: 78 | 79 | | phosphor-state-manager | bootstatus value | watchdog driver | 80 | | ---------------------- | ---------------- | -------------------------------- | 81 | | WDIOF_CARDRESET | 0x20 | return 0x20 if reset by Watchdog | 82 | | POR | 0x00 | Do nothing | 83 | 84 | 6. Generate Corresponding Event Log: 85 | - After interpreting the reboot cause, the system should issue the 86 | corresponding event log based on the determined type. 87 | 88 | ## Alternatives Considered 89 | 90 | In the original approach, **WDIOF_CARDRESET** was used to represent a **POR** 91 | (power-on-reset). However, with the new method, we need to distinguish between 92 | watchdog resets and power-on resets. Therefore, we now use **WDIOF_CARDRESET** 93 | to represent watchdog resets, aligning with the existing kernel documentation 94 | and driver implementation. 95 | 96 | ## Impacts 97 | 98 | 1. Common reboot causes across vendors can be consolidated to issue a unified 99 | event log. 100 | 2. If any functions rely on the original reboot cause, the code must be adjusted 101 | to align with the new definitions. 102 | 103 | ### Organizational 104 | 105 | Which repositories are expected to be modified to execute this design? 106 | phosphor-state-manager 107 | 108 | ## Testing 109 | 110 | Reboot the BMC under various conditions and check whether the corresponding 111 | event logs are generated correctly. 112 | -------------------------------------------------------------------------------- /designs/cable-monitor.md: -------------------------------------------------------------------------------- 1 | # Cable Monitor 2 | 3 | Author: Jagpal Singh Gill 4 | 5 | Created: July 26, 2024 6 | 7 | ## Problem Description 8 | 9 | Cables are components that can be intentionally or unintentionally inserted or 10 | removed while a system is running. Additionally, the specific configuration of 11 | cables connected for a particular hardware setup may need to be determined at 12 | runtime based on datacenter deployments. Currently, there is no service 13 | available in openBMC that can be configured at runtime to monitor connected 14 | cables and compare them against the expected cables. Hence, there is no way to 15 | generate Redfish events based on this comparison. 16 | 17 | ## Background and References 18 | 19 | openBMC provides a GPIO monitoring framework through 20 | [phosphor-gpio-monitor](https://github.com/openbmc/phosphor-gpio-monitor), but 21 | this framework is too generic in its design that allows for watching a GPIO and 22 | running a related systemd target. For more information, please refer to the 23 | Alternative section. 24 | 25 | ## Requirements 26 | 27 | 1. Able to support runtime configuration of cable connectivity. 28 | 2. Able to monitor inventory interface events related to cables and generate 29 | corresponding Redfish events. 30 | 31 | ## Proposed Design 32 | 33 | ### Cable Monitor 34 | 35 | ```mermaid 36 | --- 37 | config: 38 | layout: fixed 39 | --- 40 | flowchart LR 41 | A["cable-config.json"] --> B["Cable Monitor"] 42 | C["EntityManager"] -- xyz.openbmc_project.Inventory.Item.Cable 43 | inventory updates --> B 44 | B -- Generate Cable Events --> D["bmcweb"] 45 | ``` 46 | 47 | #### cable.conf 48 | 49 | The format of the runtime configuration is as under - 50 | 51 | ##### JSON schema 52 | 53 | ```json 54 | { 55 | "$schema": "https://json-schema.org/draft/2020-12/schema", 56 | "$defs": { 57 | "CablesDef": { 58 | "description": "The connected cable definition.", 59 | "type": "object", 60 | "properties": { 61 | "ConnectedCables": { 62 | "description": "The connected cable list.", 63 | "type": "array", 64 | "prefixItems": [ 65 | { 66 | "type": "string", 67 | "description": "The name of the cable" 68 | } 69 | ] 70 | } 71 | }, 72 | "required": ["ConnectedCables"] 73 | } 74 | }, 75 | "$ref": "#/$defs/CablesDef" 76 | } 77 | ``` 78 | 79 | ##### Example cablemonitor/cable-config.json 80 | 81 | ```json 82 | { 83 | "ConnectedCables": ["Cable_1", "Cable_2"] 84 | } 85 | ``` 86 | 87 | The configuration lists the cables that should be connected and monitored. 88 | 89 | This fulfills requirement #1. 90 | 91 | #### cable-monitor 92 | 93 | The cable monitor is responsible for processing the cable-config.json file and 94 | parsing its contents. It uses this information to raise appropriate alerts based 95 | on expected cable connectivity and inventory item status. Additionally, it 96 | continuously monitors any changes in the cable inventory item status and raises 97 | or resolves alerts accordingly. This fulfills requirement #2. 98 | 99 | ### Error Reporting 100 | 101 | A definition for 102 | [missing cable](https://gerrit.openbmc.org/c/openbmc/phosphor-dbus-interfaces/+/74397) 103 | event is proposed for Redfish, which is based on 104 | [event logging design](https://github.com/openbmc/docs/blob/master/designs/event-logging.md). 105 | 106 | ### Future Enhancements 107 | 108 | The cable monitor can be extended to support runtime cable configurations 109 | through the Redfish 110 | [Cable](https://redfish.dmtf.org/schemas/v1/Cable.v1_2_3.json) schema by using 111 | the CableStatus property. 112 | 113 | ## Alternatives Considered 114 | 115 | ### phosphor-gpio-monitor 116 | 117 | The phosphor-gpio-monitor does not currently support monitoring inventory items 118 | such as cable inventory items, although it could be extended to do so. However, 119 | this would not align with its intended purpose and nomenclature. Additionally, 120 | there is no support for runtime configuration in phosphor-gpio-monitor. Any 121 | change to add these features would result in a monolithic daemon that would need 122 | to be extended for every other inventory item type. 123 | 124 | ## Impacts 125 | 126 | ### API Impacts 127 | 128 | - A cable connect event api is being suggested as the source of Redfish event. 129 | 130 | ### Organizational 131 | 132 | - Does this repository require a new repository? No. 133 | - Which repositories are expected to be modified to execute this design? 134 | `dbus-sensors` 135 | - Make a list, and add listed repository maintainers to the gerrit review. 136 | 137 | ## Testing 138 | 139 | ### Unit Testing 140 | 141 | All the functional testing of the reference implementation will be performed 142 | using GTest. 143 | 144 | ### Integration Testing 145 | 146 | Integration testing for generating Redfish events will be carried out using the 147 | inventory item interface by creating and deleting cable inventory. 148 | -------------------------------------------------------------------------------- /yocto-development.md: -------------------------------------------------------------------------------- 1 | # Yocto in OpenBMC 2 | 3 | The Yocto Project is an open source collaboration project that provides 4 | templates, tools and methods to help you create custom Linux-based systems for 5 | embedded products regardless of the hardware architecture. 6 | 7 | OpenBMC uses the Yocto tools to manage configuration and creation of BMC images. 8 | 9 | ## Developing with Yocto 10 | 11 | There are two main use-cases for Yocto in OpenBMC: 12 | 13 | 1. Building from master or existing tags 14 | 2. Developing changes for submission to master 15 | 16 | The first is the easy case, and largely involves picking the system 17 | configuration to build before invoking `bitbake`. Examples for 18 | [Palmetto](cheatsheet.md#building-for-palmetto) and 19 | [Zaius](cheatsheet.md#building-for-zaius) are in the 20 | [cheatsheet](cheatsheet.md). 21 | 22 | The second case can be helped with Yocto's `devtool`. After running 23 | `. setup `, a tool called `devtool` will be in your path, and can be 24 | applied in several ways. 25 | 26 | If you have an existing source tree you'd like to integrate, running 27 | `devtool modify -n ${PACKAGE} ${SRCTREE}` first creates a new Yocto layer in 28 | your build directory where devtool stores recipe modifications. It then 29 | constructs a `.bbappend` for the package recipe and uses the `externalsource` 30 | class to replace the download, fetch, and patch steps with no-ops. The result is 31 | that when you build the package, it will use the local source directory as is. 32 | Keep in mind that the package recipe may not perform a clean and depending on 33 | what you are doing, you may need to run `${PACKAGE}` build system's clean 34 | command in `${SRCTREE}` to clear any built objects. Also if you change the 35 | source, you may need to run `bitbake -c cleansstate ${PACKAGE}` to clear 36 | BitBake's caches. 37 | 38 | Alternatively, if you don't already have a local source tree but would still 39 | like to modify the package, invoking `devtool modify ${PACKAGE}` will handle the 40 | fetch, unpack and patch phases for you and drop a source tree into your default 41 | workspace location. 42 | 43 | When you are all done, run `devtool reset ${PACKAGE}` to remove the `.bbappend` 44 | from the devtool Yocto layer. 45 | 46 | Further information on [devtool][0] can be found in the [Yocto Mega Manual][1]. 47 | 48 | ### Adding a file to your image 49 | 50 | There are a lot of examples of working with BitBake out there. The [recipe 51 | example][2] from OpenEmbedded is a great one and the premise of this OpenBMC 52 | tailored section. 53 | 54 | So you wrote some code. You've been scp'ing the compiled binary on to the 55 | OpenBMC system for a while and you know there is a better way. Have it built as 56 | part of your flash image. 57 | 58 | Run the devtool command to add your repo to the workspace. In my example I have 59 | a repo out on GitHub that contains my code. 60 | 61 | ```bash 62 | devtool add welcome https://github.com/causten/hello.git 63 | ``` 64 | 65 | Now edit the bb file it created for you. You can just use `vim` but `devtool` 66 | can also edit the recipe `devtool edit-recipe welcome` without having to type 67 | the complete path. 68 | 69 | Add/Modify these lines. 70 | 71 | ```bash 72 | do_install() { 73 | install -m 0755 -d ${D}${bindir} ${D}${datadir}/welcome 74 | install -m 0644 ${S}/hello ${D}${bindir} 75 | install -m 0644 ${S}/README.md ${D}${datadir}/welcome/ 76 | } 77 | ``` 78 | 79 | The install directives create directories and then copies the files into them. 80 | Now BitBake will pick them up from the traditional `/usr/bin` and 81 | `/usr/shared/doc/hello/README.md`. 82 | 83 | The Final Step is to tell BitBake that you need the `welcome` recipe 84 | 85 | ```bash 86 | vim conf/local.conf 87 | IMAGE_INSTALL_append = " welcome" 88 | ``` 89 | 90 | That's it, recompile and boot your system, the binary `hello` will be in 91 | `/usr/bin` and the `README.md` will be in `/usr/shared/doc/welcome`. 92 | 93 | ### Know what your image has 94 | 95 | Sure you could flash and boot your system to see if your file made it, but there 96 | is a faster way. The `rootfs` directory down in the depths of the `build/tmp` 97 | path is the staging area where files are placed to be packaged. 98 | 99 | In my example to check if README.md was going to be added just do... 100 | 101 | ```bash 102 | ls build/tmp/work/${MACHINE}-openbmc-linux-gnueabi/obmc-phosphor-image/1.0-r0/rootfs/usr/share/welcome/README.md 103 | ``` 104 | 105 | NXP wrote a few examples of [useful](https://community.nxp.com/docs/DOC-94953) 106 | commands with BitBake that find the file too 107 | 108 | ```bash 109 | bitbake -g obmc-phosphor-image && cat pn-depends.dot |grep welcome 110 | ``` 111 | 112 | [0]: 113 | https://www.yoctoproject.org/docs/latest/mega-manual/mega-manual.html#using-devtool-in-your-sdk-workflow 114 | "devtool" 115 | [1]: 116 | http://www.yoctoproject.org/docs/latest/mega-manual/mega-manual.html 117 | "Yocto Mega Manual" 118 | [2]: 119 | http://www.embeddedlinux.org.cn/OEManual/recipes_examples.html 120 | "Recipe Example" 121 | -------------------------------------------------------------------------------- /designs/oem/google/root_of_trust.md: -------------------------------------------------------------------------------- 1 | # Google Specific APIs - A New Service Root for Google 2 | 3 | Author: Feras Aldahlawi (faldahlawi) 4 | 5 | Other contributors: None 6 | 7 | Created: March 30, 2021 8 | 9 | ## Problem Description 10 | 11 | Redfish API does not have a resource type that is similar to Google's Root of 12 | Trust (RoT) chips. Google needs APIs that are not in the Redfish standard yet. 13 | There are working groups dedicated to bring RoT chips support to the Redfish 14 | standard already. Hence adding this support under a Google namespace would avoid 15 | conflict with those working groups. This document provides the schema of what 16 | Google needs for its new service root. 17 | 18 | ## Background and References 19 | 20 | At Google, we rely on communicating with RoT chips using a variety of transport 21 | mechanisms. Google wants to extend the support to include REST based APIs. The 22 | future of RoT devices at Google will adopt the 23 | [SPDM protocol](https://www.dmtf.org/sites/default/files/PMCI_Security-Architecture_12-11-2019.pdf). 24 | However, this design doc is targeting a group of RoT devices that will never be 25 | capable of supporting standards based interface. 26 | 27 | ## Requirements 28 | 29 | - Create a new service root of Google specific APIs. 30 | - Create a schema for a RootOfTrust resource. 31 | - Be able to execute RoT actions (attestation etc) from the API. 32 | 33 | ## Proposed Design 34 | 35 | A new service root under `google/v1`. This service root will contain a 36 | collection of `RootOfTrust` entities that have the following properties and 37 | Actions: 38 | 39 | - Chip type string 40 | - Unique Hardware id string 41 | - Firmware version map string to string 42 | - Mailbox API 43 | 44 | This new API is designed to forward calls to RoT devices and avoid and 45 | inspections of data. An example call would be: 46 | 47 | ```json 48 | { 49 | "#RootOfTrust.Mailbox": { 50 | "target": "/redfish/v1/RootsOfTrust/0/Actions.Mailbox", 51 | "@Redfish.ActionInfo": "/redfish/v1/RootsOfTrust/0/Actions.Mailbox" 52 | } 53 | "RawRequest": "some_bytes_to_be_parsed_by_receiver" 54 | } 55 | ``` 56 | 57 | This new service root is very similar to `/ibm/v1`. This would require a new 58 | dbus interface to service this API: 59 | 60 | ```yaml 61 | description: > 62 | Forward bytes to Google RoT devices. 63 | methods: 64 | - name: Mailbox 65 | description: > 66 | A method to forward bytes to RoT device. 67 | parameters: 68 | - name: rawRequest 69 | type: array[byte] 70 | description: > 71 | Value to be updated for the keyword. 72 | errors: 73 | - xyz.openbmc_project.Common.Error.InvalidArgument 74 | - xyz.openbmc_project.Common.Error.InternalFailure 75 | ``` 76 | 77 | ## Alternatives Considered 78 | 79 | Considered adding the new APIs as an OEM extension to the TPM resource. However, 80 | it was an unnatural extension. Here are the reason why it is somewhat unnatural 81 | to use TPM for Google's RoT: 82 | 83 | - FirmwareVersion1/2 84 | - Somewhat closely fixed to the design of TPM. TPM 1.2 had 32-bit firmware 85 | version and TPM 2.0 extended it clumsily by just tacking on another firmware 86 | version 32-bit field. 87 | - TPM "Firmware 1" and "Firmware 2" together refer to the 64-bit firmware 88 | version number. Most TPM2.0 vendors divide this into 4 fields each 2 bytes 89 | wide: (big-endian, each character is a byte:) 0xMMmmrrbb (M major, m minor, 90 | r rev, b build). Infineon uses a different convention for firmware version 91 | numbers than the rest of the TPM vendors, reserving some bits and expressing 92 | only a 1-byte wide "build number" as 0xMMmm_rrb 93 | - These being exposed as a string out to the Redfish interface works for 94 | Google. But I am just trying to provide info on how uniform this currently 95 | is (not) within the TPM ecosystem. 96 | - InterfaceType 97 | - Currently closely fixed to the ecosystem of TPM variants. 98 | - Which flavor of TPM interface is implemented. TCM is the "China version" of 99 | TPM 1.2. The Chinese TPM switched over to TPM 2.0 after that version of the 100 | spec was available. 101 | - TPM 1.2 and 2.0 are entirely different API surfaces, analogous to the 102 | difference between any TPM and Google's RoT chips. 103 | - InterfaceTypeSelection 104 | - Currently closely fixed to the ecosystem of TPM variants. 105 | - Some TPMs can be switched between TPM 1.2 and 2.0. This could be ignorable 106 | by Google unless Google start shipping an open sourced RoT that could be 107 | switched into a TPM mode via firmware update. (Which would be a good move) 108 | 109 | Though we can put everything under TPM's OEM (e.g. version numbers and other 110 | functionality), most of the fields will be unusable for Google's RoT. 111 | 112 | ## Impacts 113 | 114 | New daemon, new Rest API. 115 | 116 | ## Testing 117 | 118 | Testing will be done in Google internally. This feature should not impact CI 119 | testing. We will try golden paths and bad paths. We will also implement fuzz 120 | tests as well. 121 | -------------------------------------------------------------------------------- /designs/bmc-boot-ready.md: -------------------------------------------------------------------------------- 1 | # BMC Boot Ready 2 | 3 | Author: Andrew Geissler (geissonator) 4 | 5 | Other contributors: 6 | 7 | Created: May 12, 2022 8 | 9 | ## Problem Description 10 | 11 | There are services which run on the BMC which are required for the BIOS (host 12 | firmware) to power on and boot the system. The goal of this design is to define 13 | a mechanism to ensure these dependencies are met before a power on or boot is 14 | started. 15 | 16 | For example, on some system, you can not power on the chassis until the VPD has 17 | been collected from the VRM's by the BMC to determine their characteristics. On 18 | other systems, the BIOS service is needed so the host firmware can look for any 19 | overrides. 20 | 21 | Currently, OpenBMC has an undefined behavior in this area. If a particular BMC 22 | has a large time gap between when the webserver is available and when all BMC 23 | services have completed running, there is a window there that a user could 24 | request a power on via the webserver when not all needed services are running. 25 | 26 | ## Background and References 27 | 28 | The [mailing list discussion][1] can be found. The BMC currently has three major 29 | [state][2] management interfaces in a system. The BMC, Chassis, and Host. Within 30 | each state interface, the current state and requested state are tracked. 31 | 32 | The [BMC][3] state object is considered `Ready` once the systemd 33 | `multi-user.target` has successfully started all if its services. 34 | 35 | There are three options that have been discussed to solve this issue: 36 | 37 | 1. D-Bus objects don't exist until the backend is prepared to handle them. 38 | 2. If a user tries something that system is not in proper state to handle then 39 | return an error code. 40 | 3. If a user tries something that system is not in proper state to handle then 41 | queue it up. 42 | 43 | Option 1 is challenging because D-Bus interfaces provided by OpenBMC state 44 | applications have a mix of read-only properties (like current state) and 45 | writeable properties that are used to request state changes. Not showing any 46 | until everything is available could have unknown consequences. This also has 47 | similar issues to option 2 in that applications and clients must have proper 48 | code to handle missing interfaces. 49 | 50 | Option 2 is challenging because Redfish clients and internal applications like 51 | the op-panel code now need to properly handle error codes like this. You can 52 | argue that they already should, but that is definitely not the case with a lot 53 | of OpenBMC applications and clients. 54 | 55 | Option 3 is the most user friendly option. No client or OpenBMC application 56 | changes would be needed. One concern is that having a system somewhat randomly 57 | power on at some later point in time could be unexpected. The general consensus 58 | in this review though has been that this is the most preferred option. 59 | 60 | [1]: https://lists.ozlabs.org/pipermail/openbmc/2022-April/030175.html 61 | [2]: 62 | https://github.com/openbmc/phosphor-dbus-interfaces/tree/master/yaml/xyz/openbmc_project/State 63 | [3]: 64 | https://github.com/openbmc/phosphor-dbus-interfaces/blob/master/yaml/xyz/openbmc_project/State/BMC.interface.yaml 65 | 66 | ## Requirements 67 | 68 | - Queue up chassis and host requested state changes until the BMC is in the 69 | proper state to allow the request 70 | - What the "proper state" is will be implementation specific but by default 71 | phosphor-state-manager will queue all requests until the BMC state has 72 | reached `Ready` 73 | 74 | ## Proposed Design 75 | 76 | If a power on or boot request is made to the Chassis or Host state objects and 77 | the BMC is not at `Ready` then the request will be queued and the state 78 | management code will begin monitoring for BMC `Ready`. Once reached, the 79 | requested operation will be automatically executed. 80 | 81 | ## Alternatives Considered 82 | 83 | The "Background and References" section covered some alternative options and the 84 | complexity behind them. 85 | 86 | Another option is to code the dependencies directly into the services. For 87 | example, if the power on service requires the vrm vpd collection service, encode 88 | that dependency in the systemd files. This is easy to say but in practice has 89 | been challenging. Some OpenBMC services have built in assumptions that the 90 | multi-user.target and all of it's dependent services have completed prior to a 91 | power on being started. The general consensus within IBM was that it's much 92 | easier and safer to just have a global wait-for-bmc-ready function as proposed 93 | in this design. 94 | 95 | ## Impacts 96 | 97 | Users will need to understand that their request to power on the system may be 98 | delayed by an undefined amount of time. In general, a BMC gets to Ready state 99 | within a couple of minutes. 100 | 101 | ### Organizational 102 | 103 | This function will be implemented within the existing phosphor-state-manager 104 | repository. x86-power-control, an alternative to phosphor-state-manager, could 105 | also implement this logic. 106 | 107 | ## Testing 108 | 109 | - Ensure a power on request is properly queued and executed when it is made 110 | prior to the BMC being `Ready`. 111 | -------------------------------------------------------------------------------- /designs/oem/ibm/system-power-mode.md: -------------------------------------------------------------------------------- 1 | # System Power Mode and Idle Power Saver Support 2 | 3 | Author: Chris Cain 4 | 5 | Other contributors: Martha Broyles 6 | 7 | Created: 12/03/2020 8 | 9 | ## Problem Description 10 | 11 | Power management on POWER platforms needs assistance from the BMC for managing 12 | the system power mode and idle power save modes. We need the ability to set and 13 | query the system power mode and also the ability to control and set idle power 14 | save parameters. This design is only applicable to POWER processors. 15 | 16 | ## Background and References 17 | 18 | Each POWER processor contains an embedded PowerPC 405 processor that is referred 19 | to as the On Chip Controller or OCC. The OCC provides real time power and 20 | thermal monitoring and control. When a system is powered on, the OCCs will go to 21 | an Active state. Anytime the OCC state changes to active, the BMC will need to 22 | send a mode change and idle power saver (IPS) settings to the OCC. It will also 23 | need to send the commands if the user changes the mode or idle power save 24 | parameters. 25 | 26 | ## Requirements 27 | 28 | When a system is booted, the OCC will move to an ACTIVE state. In the ACTIVE 29 | state, the OCC is managing the processor frequency, power consumption, and 30 | monitoring the systems thermal sensors. For certain error conditions it may be 31 | necessary to reset the OCC. When this happens, the OCC will move out of ACTIVE 32 | state. After recovery, the OCC will be put back into the ACTIVE state. Anytime 33 | the OCC state changes to ACTIVE or the customer updates these new parameters at 34 | runtime, the BMC will need to send the mode and the idle power saver settings to 35 | the OCC. 36 | 37 | PowerMode was added to version 2021.1 Redfish Schema Supplement: 38 | 39 | 40 | Current Customer Settable System Power Modes that will be sent to the OCCs: 41 | 42 | - Static 43 | - Power Saver 44 | - Maximum Performance 45 | 46 | A proposal for adding Idle Power Saving parameters was submitted to the Redfish 47 | committee and will be used if/when approved. 48 | 49 | Customer Settable Idle Power Save Parameters: 50 | 51 | - Enabled / Disabled 52 | - Enter Delay Time (in seconds) 53 | - Enter Utilization threshold (percentage) 54 | - Exit Delay Time (in seconds) 55 | - Exit Utilization threshold (percentage) 56 | 57 | Defaults will need to be configurable by the system owner (via JSON file) 58 | 59 | ## Proposed Design 60 | 61 | The new code would be part of the openpower-occ-control repository. New code 62 | will be triggered by the following: 63 | 64 | - OCC poll response data showing a new state of Active (0x03) 65 | - OCC Active sensor is enabled (may be covered in above bullet) 66 | - Customer updates system power mode user interface or Redfish interface 67 | - Customer updates idle power save setting or Redfish interface 68 | 69 | Code will need to trigger off of OCC state changes. The kernel currently sends a 70 | POLL command to the OCC periodically (every second). The OCC state is available 71 | in the OCC poll response data. 72 | 73 | When initiated, the new code will send a SET_MODE_AND_STATE command (0x20) to 74 | the OCC and a SET_CONFIG_DATA (0x21) command with the Idle Power Saver 75 | parameters. These commands are defined in the OCC Interface Spec: 76 | 77 | 78 | Default values will also be defined for Power Mode and Idle Power Saver 79 | parameters for the system. If the customer has not yet set any of these 80 | parameters, these default values will be used. If/when the customer does set any 81 | of these, that new customer parameter will become current and the default value 82 | will no longer be used. 83 | 84 | The customer requested PowerMode and Idle Power Saver parameters will be stored 85 | as D-Bus object in the phosphor-dbus-interfaces repository: 86 | xyz/openbmc_project/Control/Power/Mode.interface.yaml Once set, these values 87 | will be retained across power cycles, AC loss, code updates, etc. 88 | 89 | ## Alternatives Considered 90 | 91 | - Using hardcoded power mode and Idle Power Save parameters (no flexibility to 92 | control system power usage) 93 | 94 | ## Impacts 95 | 96 | New interfaces that were described in the requirements section will be 97 | implemented. Parameters should be able to be set via user interface or via 98 | Redfish. API impact - Add Redfish support for new parameters as well as new user 99 | interface to allow customer to set power mode and idle power saver settings 100 | Security impact - update of these parameters should be able to be restricted to 101 | specific users/groups (may not want any user updating these parameters) 102 | Documentation impact - need to document new parameters Performance impact - 103 | minimal, new code will only execute on OCC state change which should normally 104 | happen once at boot time or when user changes parameters. The new code is only 105 | sending 2 additional commands which should complete within a few seconds. 106 | Developer impact - code to be written by OCC team with guidance from OpenBMC 107 | power management team Upgradability impact - None 108 | 109 | ## Testing 110 | 111 | This will be able to be tested by directly updating the power mode and idle 112 | power saver setting. This testing will be automated 113 | -------------------------------------------------------------------------------- /designs/design-template.md: -------------------------------------------------------------------------------- 1 | --- 2 | 3 | # Document Guidelines - _Delete this section_ 4 | 5 | ## Document Content 6 | 7 | - Not all new features need a design document. If a feature can be contributed 8 | in a single reasonably small patchset that has little impact to any other 9 | areas, it doesn't need a design discussion and documentation. 10 | 11 | - The focus of the document is to define the problem we need to solve and 12 | analyse the trade-offs of different solutions. You should concentrate on 13 | interactions between components, though analysing the trade-offs often 14 | requires you to explore how each might be implemented. 15 | 16 | - Write this document as an [argumentative essay][argumentative-essay]. Good 17 | design proposals compel the reviewers agree with the proposal's conclusions. 18 | 19 | [argumentative-essay]: https://www.grammarly.com/blog/argumentative-essay/ 20 | 21 | - This is not intended to be extensive documentation for a new feature. 22 | 23 | - You should get your design reviewed and merged before writing your code. 24 | However you are free to prototype the implementation, but remember that you 25 | may learn of new requirements during the design review process that could 26 | result in a very different solution. 27 | 28 | ## Document Formatting 29 | 30 | - Your spec should be in Markdown format, like this template. 31 | 32 | - Please wrap text at 79 columns. 33 | 34 | - Please do not delete any of the sections in this template. If you have nothing 35 | to say for a whole section, just write: None 36 | 37 | - To view your .md file, see: https://stackedit.io/ 38 | 39 | - If you would like to provide a diagram with your spec, ASCII diagrams are 40 | required. http://asciiflow.com/ is a very nice tool to assist with making 41 | ASCII diagrams. Plain text will allow the review to proceed without having to 42 | look at additional files which can not be viewed in Gerrit. It will also allow 43 | inline feedback on the diagram itself. 44 | 45 | - Once ready for review, submit to gerrit and set the topic of the review to 46 | "design" 47 | 48 | --- 49 | 50 | # Example design - this is the design title 51 | 52 | Author: < Name and Discord nickname > 53 | 54 | Other contributors: < Name and/or Discord nickname or `None` > 55 | 56 | Created: < Date initially created in Month D, Yr format (e.g. June 17, 2020 or 57 | Dec 19, 2019)> 58 | 59 | ## Problem Description 60 | 61 | (1 paragraph) What are we doing and why? What problem are you trying to solve? 62 | What are the goals and NON-goals? Please make the objective understandable for 63 | someone unfamiliar with this project by including the necessary context, but 64 | keep it short. Elaborate on the details below in the Background and Requirements 65 | sections. 66 | 67 | ## Background and References 68 | 69 | (1-2 paragraphs) What background context is necessary? You should mention 70 | related work inside and outside of OpenBMC. What other Open Source projects are 71 | trying to solve similar problems? Try to use links or references to external 72 | sources (other docs or Wikipedia), rather than writing your own explanations. 73 | Please include document titles so they can be found when links go bad. Include a 74 | glossary if necessary. Note: this is background; do not write about your design, 75 | specific requirements details, or ideas to solve problems here. 76 | 77 | ## Requirements 78 | 79 | (2-5 paragraphs) What are the constraints for the problem you are trying to 80 | solve? Who are the users of this solution? What is required to be produced? What 81 | is the scope of this effort? Your job here is to quickly educate others about 82 | the details you know about the problem space, so they can help review your 83 | implementation. Roughly estimate relevant details. How big is the data? What are 84 | the transaction rates? Bandwidth? How will the feature be configured, and what 85 | option class does it fall into? (see architecture/optionality.md) 86 | 87 | ## Proposed Design 88 | 89 | (2-5 paragraphs) A short and sweet overview of your implementation ideas. If you 90 | have alternative solutions to a problem, list them concisely in a bullet list. 91 | This should not contain every detail of your implementation, and do not include 92 | code. Use a diagram when necessary. Cover major structural elements in a very 93 | succinct manner. Which technologies will you use? What new components will you 94 | write? What technologies will you use to write them? 95 | 96 | ## Alternatives Considered 97 | 98 | (2 paragraphs) Include alternate design ideas here which you are leaning away 99 | from. Elaborate on why a design was considered and why the idea was rejected. 100 | Show that you did an extensive survey about the state of the art. Compares your 101 | proposal's features & limitations to existing or similar solutions. 102 | 103 | ## Impacts 104 | 105 | API impact? Security impact? Documentation impact? Performance impact? Developer 106 | impact? Upgradability impact? 107 | 108 | ### Organizational 109 | 110 | - Does this proposal require a new repository? (Yes, No) 111 | - Who will be the initial maintainer(s) of this repository? 112 | - Which repositories are expected to be modified to execute this design? 113 | - Make a list, and add listed repository maintainers to the gerrit review. 114 | 115 | ## Testing 116 | 117 | How will this be tested? How will this feature impact CI testing? 118 | -------------------------------------------------------------------------------- /designs/ecc-dbus-sel.md: -------------------------------------------------------------------------------- 1 | # ECC Error SEL for BMC 2 | 3 | Author: Will Liang 4 | 5 | Created: 2019-02-26 6 | 7 | ## Problem Description 8 | 9 | The IPMI SELs only define memory Error Correction Code (ECC) errors for host 10 | memory rather than BMC. 11 | 12 | The aim of this proposal is to record ECC events from the BMC in the IPMI System 13 | Event Log (SEL). Whenever ECC occurs, the BMC generates an event with the 14 | appropriate information and adds it to the SEL. 15 | 16 | ## Background and References 17 | 18 | The IPMI specification defines memory system event log about ECC/other 19 | correctable or ECC/other uncorrectable and whether ECC/other correctable memory 20 | error logging limits are reached.[1]. The BMC ECC SEL will follow IPMI SEL 21 | format and creates BMC memory ECC event log. 22 | 23 | OpenBMC currently support for generating SEL entries based on parsing the D-Bus 24 | event log. It does not yet support the BMC ECC SEL feature in OpenBMC project. 25 | Therefore, the memory ECC information will be registered to D-Bus and generate 26 | memory ECC SEL as well. 27 | 28 | [[1]Intelligent Platform Management Interface Specification v2.0 rev 1.1, section 41](https://www.intel.com/content/www/us/en/servers/ipmi/ipmi-second-gen-interface-spec-v2-rev1-1.html) 29 | 30 | ## Requirements 31 | 32 | Currently, the OpenBMC project does not support ECC event logs in D-Bus because 33 | there is no relevant ECC information in the OpenBMC D-Bus architecture. The new 34 | ECC D-Bus information will be added to the OpenBMC project and an ECC monitor 35 | service will be created to fetch the ECC count (ce_count/ue_count) from the EDAC 36 | driver. And make sure the EDAC driver must be loaded and ECC/other correctable 37 | or ECC/other uncorrectable counts need to be obtained from the EDAC driver. 38 | 39 | ## Proposed Design 40 | 41 | ECC-enabled memory controllers can detect and correct errors in operating 42 | systems (such as certain versions of Linux, macOS, and Windows) that allow 43 | detection and correction of memory errors, which helps identify problems before 44 | they become catastrophic faulty memory module. 45 | 46 | Many ECC memory systems use an "external" EDAC between the CPU and the memory to 47 | fix memory error. Most host integrate EDAC into the CPU's integrated memory 48 | controller. 49 | 50 | According to Section 42.2 of the IPMI specification, Table 42 [2], these SEL 51 | sensor types will be defined as `Memory` and `Event Data 3` field can be used to 52 | provide an event extension. Therefore, the BMC ECC event sets "Event Data 3" 53 | with the value FEh to identify the BMC ECC error. 54 | 55 | [[2] Intelligent Platform Management Interface Specification v2.0 rev 1.1, section 42.2](https://www.intel.com/content/www/us/en/servers/ipmi/ipmi-second-gen-interface-spec-v2-rev1-1.html) 56 | 57 | The main purpose of this function is to provide the BMC with the ability to 58 | record ECC error SELs. 59 | 60 | There are two new applications for this design: 61 | 62 | - poll the ECC error count 63 | - create the ECC SEL 64 | 65 | It also devised a mechanism to limit the "maximum number" of logs to avoid 66 | creating a large number of correctable ECC logs. When the `maximum quantity` is 67 | reached, the ECC service will stop to record the ECC log. The `maximum quantity` 68 | (default:100) is saved in the configuration file, and the user can modify the 69 | value if necessary. 70 | 71 | ### phosphor-ecc.service 72 | 73 | This will always run the application and look up the ECC error count every 74 | second after service is started. On first start, it resets all correctable ECC 75 | counts and uncorrectable ECC counts in the EDAC driver. 76 | 77 | It also provide the following path on D-Bus: 78 | 79 | - bus name : `xyz.openbmc_project.Memory.ECC` 80 | - object path : `/xyz/openbmc_project/metrics/memory/BmcECC` 81 | - interface : `xyz.openbmc_project.Memory.MemoryECC` 82 | 83 | The interface with the following properties: | Property | Type | Description | | 84 | -------- | ---- | ----------- | | isLoggingLimitReached | bool | ECC logging 85 | reach limits| | ceCount| int64 | correctable ECC events | | ueCount| int64 | 86 | uncorrectable ECC events | | state| string | bmc ECC event state | 87 | 88 | The error types for `xyz::openbmc_project::Memory::Ecc::Error::ceCount` and 89 | `ueCount` and `isLoggingLimitReached` will be created which generated the error 90 | type for the ECC logs. 91 | 92 | ### Create the ECC SEL 93 | 94 | Use the `phosphor-sel-logger` package to record the following logs in BMC SEL 95 | format. 96 | 97 | - correctable ECC log : when fetching the `ce_count` from EDAC driver parameter 98 | and the count exceeds previous count. 99 | - uncorrectable ECC log : when fetching the `ue_count` from EDAC driver 100 | parameter and the count exceeds previous count. 101 | - logging limit reached log : When the correctable ECC log reaches the 102 | `maximum quantity`. 103 | 104 | ## Alternatives Considered 105 | 106 | Another consideration is that there is no stopping the recording of the ECC 107 | logging mechanism. When the checks `ce_count` and value exceeds the previous 108 | value, it will record the ECC log. But this will encounter a lot of ECC logs, 109 | and BMC memory will also be occupied. 110 | 111 | ## Impacts 112 | 113 | This application implementation only needs to make some changes when creating 114 | the event log, so it has minimal impact on the rest of the system. 115 | 116 | ## Testing 117 | 118 | Depending on the platform hardware design, this test requires an ECC driver to 119 | make fake ECC errors and then check the scenario is good. 120 | -------------------------------------------------------------------------------- /architecture/code-update/host-code-update.md: -------------------------------------------------------------------------------- 1 | # Host Code Update 2 | 3 | Reference: 4 | 5 | 6 | Following are the steps to update the host firmware (or "BIOS"). This assumes 7 | the host is not accessing its firmware. 8 | 9 | 1. Get a squashfs image: 10 | - Build op-build: 11 | - After building, the image should be a tarball in the output/images 12 | directory called `.pnor.squashfs.tar` 13 | 14 | 2. Transfer the generated squashfs image to the BMC via one of the following 15 | methods: 16 | - Method 1: Via scp: Copy the generated squashfs image to the `/tmp/images/` 17 | directory on the BMC. 18 | - Method 2: Via REST Upload: 19 | 20 | - Method 3: Via TFTP: Perform a POST request to call the `DownloadViaTFTP` 21 | method of `/xyz/openbmc_project/software`. 22 | 23 | ```bash 24 | curl -b cjar -k -H "Content-Type: application/json" -X POST \ 25 | -d '{"data": ["", " MANIFEST | sed -ne '/version=/ {s/version=//;p}' | head -n1 | tr -d '\n' | sha512sum | cut -b 1-8 60 | ``` 61 | 62 | 4. To initiate the update, set the `RequestedActivation` property of the desired 63 | image to `Active`, substitute `` with the hash value noted on the 64 | previous step, this will write the contents of the image to a UBI volume in 65 | the PNOR chip via one of the following methods: 66 | - Method 1: From the BMC command line: 67 | 68 | ```bash 69 | busctl set-property org.open_power.Software.Host.Updater \ 70 | /xyz/openbmc_project/software/ \ 71 | xyz.openbmc_project.Software.Activation RequestedActivation s \ 72 | xyz.openbmc_project.Software.Activation.RequestedActivations.Active 73 | 74 | ``` 75 | 76 | - Method 2: Using the REST API: 77 | 78 | ```bash 79 | curl -b cjar -k -H "Content-Type: application/json" -X PUT \ 80 | -d '{"data": 81 | "xyz.openbmc_project.Software.Activation.RequestedActivations.Active"}' \ 82 | https://${bmc}/xyz/openbmc_project/software//attr/RequestedActivation 83 | ``` 84 | 85 | 5. (Optional) Check the flash progress. This interface is only available during 86 | the activation progress and is not present once the activation is completed 87 | via one of the following: 88 | - Method 1: From the BMC command line: 89 | 90 | ```bash 91 | busctl get-property org.open_power.Software.Host.Updater \ 92 | /xyz/openbmc_project/software/ \ 93 | xyz.openbmc_project.Software.Activation Progress 94 | ``` 95 | 96 | - Method 2: Using the REST API: 97 | 98 | ```bash 99 | curl -b cjar -k https://${bmc}/xyz/openbmc_project/software//attr/Progress 100 | ``` 101 | 102 | 6. Check the activation is complete by verifying the Activation property is set 103 | to Active via one of the following methods: 104 | - Method 1: From the BMC command line: 105 | 106 | ```bash 107 | busctl get-property org.open_power.Software.Host.Updater \ 108 | /xyz/openbmc_project/software/ \ 109 | xyz.openbmc_project.Software.Activation Activation 110 | ``` 111 | 112 | - Method 2: Using the REST API: 113 | 114 | ```bash 115 | curl -b cjar -k https://${bmc}/xyz/openbmc_project/software/ 116 | ``` 117 | 118 | ## Patching the host firmware 119 | 120 | Copy the partition binary file to `/usr/local/share/pnor/` on the BMC. 121 | 122 | The partition binary file must be named the same as the partition name that 123 | intends to patch, ex: `ATTR_TMP`. 124 | 125 | ## Associations, MANIFEST File, Deleting an Image, Software Field Mode, and Software Factory Reset 126 | 127 | Information about associations, the MANIFEST file, deleting an image, software 128 | field mode, and software factory reset can be found at 129 | [code-update.md#associations](code-update.md#associations) 130 | 131 | ## Implementation 132 | 133 | 134 | -------------------------------------------------------------------------------- /architecture/redfish-logging-in-bmcweb.md: -------------------------------------------------------------------------------- 1 | # Redfish Event Logging in bmcweb 2 | 3 | This guide is intended to help developers add new messages to the bmcweb Redfish 4 | event log. 5 | 6 | Redfish Message Objects can be represented in different ways. In bmcweb, we have 7 | chosen to use Message Registries with Message Objects that are referenced using 8 | a MessageId and MessageArgs fields. 9 | 10 | Additional details can be found in the 11 | [Redfish Specification](http://redfish.dmtf.org/schemas/DSP0266_1.6.1.html). 12 | 13 | ## Message Registries 14 | 15 | The first step when adding a new message to the Redfish event log is to find or 16 | add an appropriate message in a Message Registry. 17 | 18 | The bmcweb Message Registries are located under 19 | "\redfish-core\include\registries" in source code, and they can be examined 20 | through Redfish under "/redfish/v1/Registries". 21 | 22 | If an appropriate message exists, note the 23 | 24 | 1. Title of the Message Object (required as the MessageKey in the MessageId). 25 | 2. Args (notated as "%x") in the "Message" field (required for the MessageArgs). 26 | 27 | If an appropriate message does not exist, new messages can be added as follows: 28 | 29 | 1. Choose a Message Registry for the new message 30 | 2. Choose a MessageKey to use as the title for the new Message entry 31 | 3. Insert a new Message entry (preferably with the title in alphabetical order) 32 | 4. Add a `description` and `resolution` 33 | 5. Set the `severity` to "Critical", "Warning", or "OK" 34 | 6. Define the `message` with any necessary args 35 | 7. Set the `numberOfArgs` and `paramTypes` to match the message args 36 | 37 | ## Logging Messages 38 | 39 | Logging messages is done by providing a Redfish MessageId and any corresponding 40 | MessageArgs to bmcweb. 41 | 42 | A Redfish MessageId is represented in this format: 43 | 44 | `RegistryName.MajorVersion.MinorVersion.MessageKey` 45 | 46 | bmcweb will search the specified Message Registry for the MessageKey, construct 47 | the final message using the MessageArgs, and display that in the event log. 48 | 49 | ### journal-based Redfish Logging 50 | 51 | The journal is the current mechanism used to log Redfish Messages. bmcweb looks 52 | for two fields in the journal metadata: 53 | 54 | - `REDFISH_MESSAGE_ID`: A string holding the MessageId 55 | - `REDFISH_MESSAGE_ARGS`: A string holding a comma-separated list of args 56 | 57 | These fields can be added to a journal entry using either the 58 | `phosphor::logging::entry()` command or directly using the `sd_journal_send()` 59 | command. 60 | 61 | ### Examples 62 | 63 | #### Logging a ResourceCreated event 64 | 65 | The 66 | [Resource Event Message Registry](https://redfish.dmtf.org/registries/ResourceEvent.1.0.0.json) 67 | holds the ResourceCreated message: 68 | 69 | ```json 70 | { 71 | "ResourceCreated": { 72 | "Description": "Indicates that all conditions of a successful 73 | creation operation have been met.", 74 | "Message": "The resource has been created successfully.", 75 | "NumberOfArgs": 0, 76 | "Resolution": "None", 77 | "Severity": "OK" 78 | } 79 | }, 80 | ``` 81 | 82 | Since there are no parameters, no MessageArgs are required, so this message can 83 | be logged to the journal as follows: 84 | 85 | ```cpp 86 | phosphor::logging::log( 87 | "journal text", 88 | phosphor::logging::entry("REDFISH_MESSAGE_ID=%s", 89 | "ResourceEvent.1.0.ResourceCreated")); 90 | ``` 91 | 92 | or 93 | 94 | ```cpp 95 | sd_journal_send("MESSAGE=%s", "journal text", "PRIORITY=%i", , 96 | "REDFISH_MESSAGE_ID=%s", 97 | "ResourceEvent.1.0.ResourceCreated", NULL); 98 | ``` 99 | 100 | #### Logging a ResourceErrorThresholdExceeded event 101 | 102 | The 103 | [Resource Event Message Registry](https://redfish.dmtf.org/registries/ResourceEvent.1.0.0.json) 104 | holds the ResourceErrorThresholdExceeded message: 105 | 106 | ```json 107 | { 108 | "ResourceErrorThresholdExceeded": { 109 | "Description": "The resource property %1 has exceeded error 110 | threshold of value %2. Examples would be drive IO errors, or 111 | network link errors.", 112 | "Message": "The resource property %1 has exceeded error 113 | threshold of value %2.", 114 | "NumberOfArgs": 2, 115 | "ParamTypes": [ 116 | "string", 117 | "value" 118 | ], 119 | "Resolution": "None.", 120 | "Severity": "Critical" 121 | } 122 | }, 123 | ``` 124 | 125 | This message has two parameters, `%1` and `%2`, as indicated in the 126 | `"NumberOfArgs"` field. The meaning and types of these parameters are derived 127 | from the `"Message"` and `"ParamTypes"` fields in the Message Registry. 128 | 129 | In this example, `%1` is a string holding the property name and `%2` is a number 130 | holding the threshold value. 131 | 132 | The parameters are filled from a comma-separated list of the MessageArgs, so 133 | this message can be logged to the journal as follows: 134 | 135 | ```cpp 136 | phosphor::logging::log( 137 | "journal text", 138 | phosphor::logging::entry("REDFISH_MESSAGE_ID=%s", 139 | "ResourceEvent.1.0.ResourceErrorThresholdExceeded"), 140 | phosphor::logging::entry("REDFISH_MESSAGE_ARGS=%s,%d", 141 | "Property Name", propertyValue)); 142 | ``` 143 | 144 | or 145 | 146 | ```cpp 147 | sd_journal_send("MESSAGE=%s", "journal text", "PRIORITY=%i", , 148 | "REDFISH_MESSAGE_ID=%s", 149 | "ResourceEvent.1.0.ResourceErrorThresholdExceeded", 150 | "REDFISH_MESSAGE_ARGS=%s,%d", "Property Name", 151 | propertyValue, NULL); 152 | ``` 153 | -------------------------------------------------------------------------------- /kernel-development.md: -------------------------------------------------------------------------------- 1 | # OpenBMC kernel development 2 | 3 | > [!IMPORTANT] 4 | > 5 | > The kernel development philosphy described below also applies to OpenBMC's 6 | > u-boot fork. 7 | 8 | The OpenBMC project maintains a kernel tree for use by the project. The tree's 9 | general development policy is that code must be upstream first. This is strongly 10 | desirable but not a hard requirement, and exceptions may be made on a 11 | case-by-case basis. If in doubt, start a discussion on the mailing list. 12 | 13 | The OpenBMC kernel tree is hosted at and 14 | contains the set of patches that we carry. Ideally there would be no patches 15 | carried, as everything should be upstream. 16 | 17 | Your code will make it into the OpenBMC tree in these ways, from most to least 18 | desirable: 19 | 20 | 1. When the OpenBMC kernel moves to a new upstream release 21 | 2. By backporting upstream commits from a newer kernel version to the OpenBMC 22 | kernel 23 | 3. Patches included in the OpenBMC tree temporarily 24 | 25 | ## TL;DR 26 | 27 | If you require a patch added to the tree, follow these steps: 28 | 29 | 1. Submit your patch upstream. It doesn't need to be upstream, but it should be 30 | on it's way, and not have any unresolved design concerns 31 | 2. Use 32 | `git format-patch --subject-prefix="PATCH linux ${BRANCH}" --to=openbmc@lists.ozlabs.org --to=joel@jms.id.au --to=andrew@codeconstruct.com.au` 33 | to create a formatted patch 34 | 35 | ## Developing a new driver 36 | 37 | When developing a new driver, your goal is to have the code accepted upstream. 38 | The first step should be to check that there is no existing driver for the 39 | hardware you wish to support. Check the OpenBMC `dev-` branches, check upstream, 40 | and if you do not find support there ask on the mailing list. 41 | 42 | Once you are sure a driver needs to be written, you should develop and test the 43 | driver, before sending it upstream to the relevant maintainers. You should feel 44 | welcome to cc the OpenBMC list when sending upstream, so other kernel developers 45 | can provide input where appropriate. Be sure to follow the (upstream development 46 | process)[https://www.kernel.org/doc/Documentation/process/submitting-patches.rst]. 47 | 48 | In the past patches underwent 'pre-review' on the OpenBMC mailing list. While 49 | this is useful for developers who are not familiar with writing kernel code, it 50 | has lead to confusion about the upstreaming process, so now we do all of our 51 | development in the community. 52 | 53 | Once the driver has been accepted upstream, send the good news to the OpenBMC 54 | list with a reference to the upstream tree. This may be Linus' tree, or it might 55 | be one of the subsystem maintainers. From there the OpenBMC kernel team can 56 | decide how best to include your code in the OpenBMC tree. 57 | 58 | ### Exceptions 59 | 60 | There are cases where waiting for upstream acceptance will delay the bring-up of 61 | a new system. This should be avoided through careful planning and early 62 | development of the features upstream, but where this has not happened we can 63 | choose to carry the patches in the OpenBMC tree while upstream development 64 | continues. 65 | 66 | Another exception to the upstream first rule is where patches are modifying 67 | files that are not upstream. This currently includes the aspeed board file 68 | `arch/arm/mach-aspeed/aspeed.c`, and the device tree source files `dts`. The 69 | board file should go away when we get drivers written for all of the 70 | functionality; for now it contains some hacks relating to LPC and early init. 71 | 72 | If you find yourself adding to `arch/arm/mach-aspeed/aspeed.c`, first send an 73 | email to the OpenBMC list to get the opinion of the kernel developers. Patches 74 | to `aspeed.c` will be treated with some prejudice as the file will be removed 75 | once we have drivers for all of the Aspeed peripherals. 76 | 77 | ## Testing 78 | 79 | Before submitting patches it is recommended you boot test on at least the Qemu 80 | platforms, and whatever hardware you have available. 81 | 82 | ## Tips and Tricks 83 | 84 | Some general hints for kernel development 85 | 86 | ### Out-of-tree builds 87 | 88 | You can build a kernel out of the yocto environment, by using the initramfs 89 | (from a pre-existing yocto build) directly: 90 | 91 | ```sh 92 | make ARCH=arm \ 93 | O=obj \ 94 | CROSS_COMPILE=arm-linux-gnueabihf- \ 95 | CONFIG_INITRAMFS_SOURCE=.../obmc-phosphor-image-palmetto.cpio.gz 96 | ``` 97 | 98 | (adjust `O` and `CROSS_COMPILE` parameters as appropriate). 99 | 100 | You'll need to use a relevant BMC defconfig (e.g. `aspeed_g4_defconfig` or 101 | `aspeed_g5_defconfig`) as your base kernel configuration. 102 | 103 | The cpio can be found under the relevant machine directory in the following 104 | yocto output directory: 105 | 106 | ```sh 107 | build/tmp/deploy/images/ 108 | ``` 109 | 110 | ### Building a uImage 111 | 112 | To build a uImage (for example, to netboot): 113 | 114 | ```sh 115 | # build a zImage using the obmc rootfs 116 | make ARCH=arm \ 117 | O=obj \ 118 | CROSS_COMPILE=arm-linux-gnueabihf- \ 119 | CONFIG_INITRAMFS_SOURCE=/path/tp/obmc-phosphor-image-palmetto.cpio.gz 120 | 121 | # create a combined zImage + DTB image 122 | cat obj/arch/arm/boot/zImage \ 123 | obj/arch/arm/boot/dts/aspeed-bmc-opp-palmetto.dtb \ 124 | > obj/aspeed-zimage 125 | 126 | # create a uImage 127 | ./scripts/mkuboot.sh -A arm -O linux -C none -T kernel \ 128 | -a 0x40008000 -e 0x40008000 -n $USER-`date +%Y%m%d%H%M` \ 129 | -d obj/aspeed-zimage obj/uImage 130 | ``` 131 | 132 | Note that some systems may have upgraded to a FIT-based u-boot, where the old 133 | uImage format is no longer accepted. 134 | -------------------------------------------------------------------------------- /tof/contract.md: -------------------------------------------------------------------------------- 1 | # OpenBMC Technical Oversight Forum (TOF) 2 | 3 | This is a working document and subject to change. 4 | 5 | The OpenBMC TOF or Technical Oversight Forum represents the technical leadership 6 | of the OpenBMC project. 7 | 8 | The TOF handles the processes around accepting new features into OpenBMC, 9 | creating new subprojects (git repositories), approving subproject maintainers, 10 | handling and enforcement of subproject maintainer issues, and many other 11 | technical leadership concerns related to OpenBMC. This source of this document 12 | is in the [OpenBMC documentation repository](https://github.com/openbmc/docs). 13 | The TOF updates and maintains this document, using the process documented 14 | within, and it can be considered authoritative unless directly overridden by the 15 | TSC. 16 | 17 | ## Working Principles 18 | 19 | - Decision making is a spectrum between building broad consensus, in which 20 | everyone has agreement, and providing guidance quickly, even when there are 21 | strongly differing view-points. This group should intend to work towards broad 22 | consensus, with a balance towards moving forward when there is minor 23 | disagreement. 24 | - Members within this forum are representatives of the development community as 25 | a whole and not as representatives for the entities they are employed by. As 26 | such, decisions should be made based on merits of the decision at hand and not 27 | on impacts to various member entities. 28 | - Encouraging progress, experimentation, and decision making within the project 29 | is the core purpose of the TOF and not to create processes and barriers to 30 | development. Velocity should be favored over perfection, except as a rationale 31 | for ignoring well-reasoned issues. 32 | 33 | ## Role and responsibilities 34 | 35 | Issues the TOF handle include: 36 | 37 | - Approval of new bitbake meta layers. 38 | - Approval of new subprojects. 39 | - Supervising subproject maintainers. 40 | - Resolving subproject maintainer disputes. 41 | - Guidance and oversight of the technical direction of OpenBMC. 42 | 43 | ## Current members 44 | 45 | The current TOF members and terms are maintained in the 46 | [TOF membership](https://github.com/openbmc/docs/blob/master/tof/membership-and-voting.md#terms-and-elections) 47 | doc. 48 | 49 | The TOF shall have a minimum of 5 and maximum of 9 members at any given time. 50 | 51 | The chair rotates month to month. 52 | 53 | Chair responsibilities: 54 | 55 | - Preparing the agenda. 56 | - Taking meeting minutes. 57 | - Documenting decisions on GitHub. 58 | 59 | Members are elected by community contributors yearly. The voting process will be 60 | determined by the TOF at a later date and updated in this document. TOF 61 | candidates should have a breadth of knowledge about the OpenBMC project. Ideal 62 | candidates will also have a public history of fostering collaboration between 63 | teams. 64 | 65 | Resignation of TOF members will be handled as an empty/reduced seat until the 66 | next voting session. 67 | 68 | ## Github issues 69 | 70 | The TOF tracks any ongoing decisions using GitHub issues in the 71 | [TOF repository](https://github.com/openbmc/technical-oversight-forum/issues). 72 | Issues can be opened by anyone, including TOF members themselves. Issues can be 73 | requests for process or technical changes, or solicitations for the opinion of 74 | the TOF. When an issue is opened the TOF will respond to a proposal or a 75 | solicitation, or add it to the next TOF meeting agenda for TOF discussion. 76 | 77 | Once an issue has a proposal, TOF members have 8 days to vote on the proposal in 78 | one of three ways: for, against, or “needs discussion”. After 8 days, if the 79 | proposal has at least three votes for and no other votes, the proposal is 80 | approved. Alternatively, if the proposal has at least three votes against and no 81 | other votes, the proposal is rejected and closed. Any other vote count results 82 | in the issue being put on the next TOF meeting agenda. To ensure proposals do 83 | not stagnate, if the initial 8 days elapses and the minimum number of votes has 84 | not been met, the proposal is extended by an additional 6 days and then put onto 85 | the next TOF meeting agenda after 2 weeks. 86 | 87 | Issue vote indicators by reacting to the top post: 88 | 89 | - For - 👍 (`:+1:`) 90 | - Against - 👎 (`:-1:`) 91 | - Needs discussion - 👀 (`:eyes:`) 92 | 93 | ## Meetings 94 | 95 | The TOF meets bi-weekly. Any requests for consideration by the TOF should be 96 | submitted via a GitHub issue using the process documented earlier in this 97 | document. 98 | 99 | Meetings require a quorum of the TOF to be present; quorum is defined as: 100 | 101 | | Active TOF membership | Quorum | 102 | | --------------------- | ------ | 103 | | 5 | 4 | 104 | | 6 | 5 | 105 | | 7 | 5 | 106 | | 8 | 5 | 107 | | 9 | 6 | 108 | 109 | During the meeting, the TOF discusses proposals under dispute and votes on them. 110 | A proposal is rejected if it does not reach majority approval or there is more 111 | than one dissenting vote. 112 | 113 | It is the responsibility of the TOF chairperson to make a public record of the 114 | decisions of the meeting. 115 | 116 | ## Discord channel 117 | 118 | The TOF has a private Discord channel for forum member coordination and, in rare 119 | situations, potentially sensitive topics. Sensitive topics would be topics 120 | having security or privacy concerns, such as those involving actions of an 121 | individual developer. The TOF chairperson is responsible for coordinating the 122 | public posting of any information or decisions that do not need to remain 123 | private, using the same process as public issues. 124 | -------------------------------------------------------------------------------- /testing/local-ci-build.md: -------------------------------------------------------------------------------- 1 | # Local CI Build 2 | 3 | These instructions pertain to running the upstream OpenBMC CI locally. 4 | 5 | ## Install Docker 6 | 7 | Please install and configure Docker. The installation of Docker CE (Community 8 | Edition) varies by platform and may differ in your organization, but the 9 | [Docker Docs](https://docs.docker.com/install/) are a good place to start 10 | looking. 11 | 12 | Check that the installation was successful by running 13 | `sudo docker run hello-world`. 14 | 15 | Each repository is built locally within the CI using the bootstrap.sh and 16 | automake toolchain. 17 | 18 | ## Download the CI Image 19 | 20 | Start by making a place for your CI repositories to live, and clone the CI 21 | scripts first: 22 | 23 | ```shell 24 | mkdir ci_test_area 25 | cd ci_test_area 26 | git clone https://github.com/openbmc/openbmc-build-scripts.git 27 | ``` 28 | 29 | ## Add a Read-Only Repo 30 | 31 | If you just want to validate a project as it is upstream, without any of your 32 | own changes, you can clone it directly into the Docker directory. This example 33 | clones and builds phosphor-hwmon directly. The upstream CI will try building 34 | everything and this includes running `make check` if available. It will also run 35 | `format-code.sh` and check if the code is formatted properly if there is a 36 | `.clang-format` file present in the target repository, or if there is a script 37 | in the repo named `format-code.sh`. 38 | 39 | ```shell 40 | cd /path/to/ci_test_area 41 | git clone https://github.com/openbmc/phosphor-hwmon 42 | WORKSPACE=$(pwd) UNIT_TEST_PKG=phosphor-hwmon \ 43 | ./openbmc-build-scripts/run-unit-test-docker.sh 44 | ``` 45 | 46 | NOTE: When running 'run-unit-test-docker.sh' make sure you do not have any 47 | uncommitted changes. The script runs git diff after 'format-code.sh' and 48 | therefore any uncommitted changes show up as output and it then fails assuming 49 | the code was improperly formatted. 50 | 51 | NOTE: This technique is okay if you have only a quick change on a project you 52 | don't work on very often, but is more difficult to use if you would rather use 53 | an active development branch. If you plan to develop regularly on a repo, use 54 | the next technique instead. 55 | 56 | ## Run CI on local changed Repo 57 | 58 | If you have local changes in the repo, and you do not want to commit yet, it's 59 | possible to run local CI as well by setting `NO_FORMAT_CODE=1` before running 60 | the script. 61 | 62 | E.g. 63 | 64 | ```shell 65 | WORKSPACE=$(pwd) UNIT_TEST_PKG=phosphor-hwmon NO_FORMAT_CODE=1 \ 66 | ./openbmc-build-scripts/run-unit-test-docker.sh 67 | ``` 68 | 69 | `NO_FORMAT_CODE=1` tells the script to skip the `format-code.sh` so that it will 70 | not format the code and thus your repo could contain un-committed changes. 71 | 72 | ## Run CI for testing purposes only 73 | 74 | To only invoke the test suite and not get caught up the various analysis passes 75 | that might be run otherwise, set `TEST_ONLY=1`. 76 | 77 | E.g. 78 | 79 | ```shell 80 | WORKSPACE=$(pwd) UNIT_TEST_PKG=phosphor-hwmon TEST_ONLY=1 \ 81 | ./openbmc-build-scripts/run-unit-test-docker.sh 82 | ``` 83 | 84 | ## Reference an Existing Repo with `git worktree` 85 | 86 | If you're actively developing on a local copy of a repo already, or you want to 87 | start doing so, you should use `git worktree` instead so that the Docker 88 | container can reference a specific branch of your existing local repo. Learn 89 | more about worktree by running `git help worktree` if you're curious. 90 | 91 | This example demonstrates how to make a worktree of `phosphor-host-ipmid` in 92 | your Docker container. 93 | 94 | ```shell 95 | cd /my/dir/for/phosphor-host-ipmid 96 | git worktree add /path/to/ci_test_area/phosphor-host-ipmid 97 | ``` 98 | 99 | Now, if you `cd /path/to/ci_test_area`, you should see a directory 100 | `phosphor-host-ipmid/`, and if you enter it and run `git status` you will see 101 | that you're likely on a new branch named `phosphor-host-ipmid`. This is just for 102 | convenience, since you can't check out a branch in your worktree that's already 103 | checked out somewhere else; you can safely ignore or delete that branch later. 104 | 105 | However, Git won't be able to figure out how to get to your main worktree 106 | (`/my/dir/for/phosphor-host-ipmid`), so we'll need to mount it when we run. Open 107 | up `/path/to/ci_test_area/openbmc-build-scripts/run-unit-test-docker.sh` and 108 | find where we call `docker run`, way down at the bottom. Add an additional 109 | argument, remembering to escape the newline ('\'): 110 | 111 | ```bash 112 | PHOSPHOR_IPMI_HOST_PATH="/my/dir/for/phosphor-host-ipmid" 113 | 114 | docker run --blah-blah-existing-flags \ 115 | -v ${PHOSPHOR_IPMI_HOST_PATH}:${PHOSPHOR_IPMI_HOST_PATH} \ 116 | -other \ 117 | -args 118 | ``` 119 | 120 | Then commit this, so you can make sure not to lose it if you update the scripts 121 | repo: 122 | 123 | ```shell 124 | cd openbmc-build-scripts 125 | git add run-unit-test-docker.sh 126 | git commit -m "mount phosphor-host-ipmid" 127 | ``` 128 | 129 | The easiest workflow in this situation now looks something like this: 130 | 131 | ```shell 132 | # Hack in the main worktree. 133 | cd /my/dir/for/phosphor-host-ipmid 134 | git checkout -b add-foo 135 | # Make a change. 136 | touch foo 137 | # Make sure to commit it. 138 | git add foo 139 | git commit -sm "change foo" 140 | # Update the Docker worktree to agree with it. 141 | cd /path/to/ci_test_area/phosphor-host-ipmid 142 | git checkout --detach add-foo 143 | # Now run the Docker container normally 144 | ``` 145 | 146 | ### Interactive Docker Session 147 | 148 | To use an interactive session, you can pass the flag `INTERACTIVE=true` to 149 | `run-unit-test-docker.sh` which will drop you into a bash shell with a default 150 | D-Bus instance. This is handy if you need to run gdb on a core dump or run a 151 | daemon on your workstation. 152 | -------------------------------------------------------------------------------- /designs/ncsi-coredump.md: -------------------------------------------------------------------------------- 1 | # NC-SI core dump 2 | 3 | Author: DelphineCCChiu () 4 | 5 | Created: 03/12/2024 6 | 7 | ## Problem Description 8 | 9 | NIC core-dump is essential for NIC issue debugging, and it could be retrieved 10 | via both in-band and out of band method. The design here is providing the 11 | solution for NIC out of band dumping from BMC over NC-SI protocol. 12 | 13 | ## Background and References 14 | 15 | NC-SI command for dump retrieval: Reference: NC-SI spec v1.2: section: 8.4.114 16 | 17 | 18 | NC-SI over MCTP: 19 | 20 | 21 | ## Requirements 22 | 23 | This feature requires Linux kernel to support transferring new NC-SI command 24 | (0x4D) in net/ncsi module 25 | 26 | 27 | ## Proposed Design 28 | 29 | ### Interface 30 | 31 | This design will reuse existing phosphor-debug-collector module: 32 | and extend the dump 33 | creation interface with a new "NC-SICoreDump" dump type. 34 | 35 | The D-Bus interface for dump creation will be:"xyz.openbmc_project.Dump.Manager 36 | /xyz/openbmc_project/dump/bmc xyz.openbmc_project.Dump.Create" 37 | 38 | To indicate which NC-SI link to target, The CreateDump method need one 39 | additional input parameter: "NICTarget". An EID or network interface, such as 40 | eth0 could be a valid value. 41 | 42 | ### Dump Retrieval 43 | 44 | Using standard NC-SI command: Retrieve Data From NC(0x4D) to get the dumps by 45 | NC-SI over RBT or NC-SI over MCTP protocol. All NC-SI dump procedure will be 46 | implemented in ncsi-netlink and ncsi-mctp utility in phosphor-networkd: 47 | 48 | 49 | ### Integrate with phosphor-debug-collector 50 | 51 | Since phosphor-debug-collector using shell scripts for data collection, a new 52 | collector script named "ncsicoredump" will be added. This script will help to 53 | call ncsi-netlink or ncsi-mctp by different NICTarget and generate dump file 54 | under specific folder. 55 | 56 | The following block diagram illustrate entire dump procedure and relationship 57 | between modules: 58 | 59 | ```text 60 | 61 | +----------------+ +-----------+ 62 | | | | | 63 | -------------> Dump manager +-----------> DumpEntry | 64 | CreateDump | | | | 65 | +--------+-------+ +-----------+ 66 | | 67 | | 68 | | 69 | +--------v-------+ 70 | | | 71 | | Dreport | 72 | | | 73 | +--------+-------+ 74 | | 75 | | 76 | | 77 | +--------v-------+ 78 | | | 79 | | Plugin: +------------------+ 80 | | ncsicoredump | | 81 | | | | 82 | +--------+-------+ | 83 | | | 84 | | | 85 | | | 86 | | | 87 | +------------+ +--------v-------+ +-------v------+ +------------+ 88 | | | | | | | | | 89 | | DumpFile <-------+ NCSI-NetLink | | NCSI-MCTP +--------> DumpFile | 90 | | | | | | | | | 91 | +------------+ +--------^-------+ +-------^------+ +------------+ 92 | | | 93 | --------------------------------+--------------------------+----------------------------- 94 | Kernel |Netlink |MCTP 95 | +--------v-------+ +--------v-------+ 96 | | | | | 97 | |Net/NC-SI module| | I2C driver | 98 | | | | | 99 | +--------^-------+ +--------^-------+ 100 | | | 101 | |NC-SI |SMBUS 102 | | | 103 | +--------v--------------------------v-------+ 104 | | | 105 | | NIC | 106 | | | 107 | +-------------------------------------------+ 108 | 109 | ``` 110 | 111 | ## Alternatives Considered 112 | 113 | We shall block duplicated dump procedure by the reception ordering of NC-SI 114 | command(0x4d) shall be maintained. Since the core dump will contain up to 2 115 | crash dump inside, we only support core dump now by it's sufficient for current 116 | usage. 117 | 118 | ## Impacts 119 | 120 | None. 121 | 122 | ## Testing 123 | 124 | Co-work with NIC vendor(Broadcom) for dump process/file validation. 125 | -------------------------------------------------------------------------------- /development/web-ui.md: -------------------------------------------------------------------------------- 1 | # OpenBMC Web User Interface Development 2 | 3 | **Document Purpose:** How to customize, build, and run the OpenBMC Web UI 4 | 5 | **Audience:** Developer familiar with HTML, CSS and JS 6 | 7 | **Prerequisites:** Current Linux, Mac, or Windows system 8 | 9 | ## Webui-vue 10 | 11 | The [webui-vue](https://github.com/openbmc/webui-vue) repository will replace 12 | phosphor-webui once it is deprecated. Webui-vue uses the 13 | [Vue.js](https://vuejs.org/) framework to interact with the BMC via the Redfish 14 | API. 15 | 16 | Visit [README.md](https://github.com/openbmc/webui-vue/blob/master/README.md) to 17 | learn more about why the Vue.js application was created, features needed to 18 | reach parity and why it is replacing the Angular.JS application. 19 | 20 | Visit 21 | [CONTRIBUTING.md](https://github.com/openbmc/webui-vue/blob/master/CONTRIBUTING.md) 22 | to find information on project set-up, design information, and contributing 23 | processes. 24 | 25 | Visit the [OpenBMC Web UI Style Guide](https://openbmc.github.io/webui-vue/) to 26 | find information on: 27 | 28 | - Coding Standards 29 | - Guidelines 30 | - Unit Testing 31 | - Components Usage 32 | - Quick Start References 33 | 34 | Visit the 35 | [OpenBMC Web UI Themes Guide - How to customize](https://openbmc.github.io/webui-vue/customization/theme.html) 36 | to learn how to create custom builds to meet your branding and customization 37 | needs for: 38 | 39 | - Routing 40 | - Navigation 41 | - State Store 42 | - Theming 43 | 44 | ### Load Web UI against QEMU 45 | 46 | Connect to Web UI in QEMU 47 | 48 | 1. You will need the QEMU session running per instructions in the "Download and 49 | Start QEMU Session" section of 50 | [dev-environment](https://github.com/openbmc/docs/blob/master/development/dev-environment.md). 51 | 52 | 2. Assuming you used the default of 2443 for the HTTPS port in your QEMU 53 | session, you will point your web browser to . 54 | 55 | 3. Login with default username and password and verify basic Web UI features are 56 | working as expected. 57 | 58 | **Note** You will need to approve the security exception in your browser to 59 | connect. OpenBMC is running with a self-signed SSL certificate. 60 | 61 | ## Phosphor-webui 62 | 63 | The [phosphor-webui](https://github.com/openbmc/phosphor-webui) repository 64 | provides a web-based interface for an OpenBMC. It uses the 65 | [AngularJS](https://angularjs.org/) framework to interact with the BMC via REST 66 | API calls. It allows users to view hardware information, update firmware, set 67 | network settings, and much more. 68 | 69 | See directions below to learn 70 | [how to customize phosphor-webui](#customize-phosphor-webui). 71 | 72 | Phosphor-webui was built on AngularJS and AngularJS goes End of Life June 73 | 30, 2021. 74 | 75 | ### Customize Phosphor-webui 76 | 77 | 1. Clone the repository 78 | 79 | ```bash 80 | git clone https://github.com/openbmc/phosphor-webui.git 81 | ``` 82 | 83 | 2. Install appropriate packages and start web UI 84 | 85 | Follow the directions in the phosphor-webui 86 | [README](https://github.com/openbmc/phosphor-webui/blob/master/README.md) to 87 | install the required packages and start the web UI. You can use the 88 | development environment created in 89 | [dev-environment](https://github.com/openbmc/docs/blob/master/development/dev-environment.md) 90 | or your own system assuming you install the required packages noted in the 91 | README. 92 | 93 | 3. Customize the web UI login screen and verify 94 | 95 | Kill your npm run from the previous step using Ctrl^C. Grab a png that you 96 | will use to represent your customized version of OpenBMC. Feel free to use 97 | any .png you wish for this step. 98 | 99 | ```bash 100 | wget http://www.pngmart.com/files/3/Free-PNG-Transparent-Image.png 101 | ``` 102 | 103 | Copy your new .png into the appropriate directory 104 | 105 | ```bash 106 | cp Free-PNG-Transparent-Image.png app/assets/images/ 107 | ``` 108 | 109 | Point to that new image in the web UI HTML 110 | 111 | ```bash 112 | vi app/login/controllers/login-controller.html 113 | # Replace the logo.svg near the top with Free-PNG-Transparent-Image.png 114 | 115 | ``` 116 | 117 | Start up the server with your change 118 | 119 | ```bash 120 | npm run-script server 121 | ``` 122 | 123 | Load web browser at and verify your new image is on 124 | the login screen. 125 | 126 | Kill your npm run using Ctrl^C. 127 | 128 | 4. Customize the header with the new image and verify The header is on every 129 | page in the web UI. It has a smaller version of the logo in it which we are 130 | changing with this step. 131 | 132 | Similar to the previous step, modify the appropriate HTML for the header: 133 | 134 | ```bash 135 | vi app/common/directives/app-header.html 136 | # Replace logo.svg with Free-PNG-Transparent-Image.png again 137 |
138 | ``` 139 | 140 | Start up the server with your change 141 | 142 | ```bash 143 | npm run-script server 144 | ``` 145 | 146 | Browse to `https://localhost:8080` and verify your new image is on the 147 | header. 148 | 149 | Note that you will need to log in to view the header. Point the web UI to 150 | your QEMU session by typing the QEMU session (e.g. localhost:2443) in the 151 | "BMC HOST OR BMC IP ADDRESS" field. 152 | 153 | Note that in the HTML where you're replacing the images, there is also the 154 | corresponding text that goes with the images. Changing the text to match with 155 | your logo is also something you can easily do to customize your creation of 156 | an OpenBMC system. 157 | 158 | And that's it! You've downloaded, customized, and run the OpenBMC phosphor-webui 159 | code! 160 | -------------------------------------------------------------------------------- /release/metrics/2020-03: -------------------------------------------------------------------------------- 1 | ampere 2 | 1000252 chuongtranle,0 3 | 1000249 hyche,0 4 | 1000245 TungVuX,0 5 | 1000248 hienvpham,0 6 | 1000267 thinhp,0 7 | March, 0 8 | 9 | facebook 10 | 1000212 amithash,0 11 | 1000546 HCL-BMC,0 12 | 1000000 williamspatrick,6 13 | 1000223 sdasari73,0 14 | 1000271 vijaykhemka,12 15 | 1000513 agnesamreetha,0 16 | 1000538 manikandan-e,0 17 | 1000544 thillaivasan,0 18 | March, 18 19 | 20 | google 21 | 1000539 alex310110,0 22 | 1000233 BenjaminFair,0 23 | 1000388 brandonkimbk,0 24 | 1000099 nasamuffin,0 25 | 1000520 Krellan,4 26 | 1000156 kunyi731,0 27 | 1000313 mgersh,0 28 | 1000052 yuennancy,0 29 | 1000265 osenft,0 30 | 1000100 pstrinkle,0 31 | 1000502 peterlundgren,0 32 | 1000500 quadpixels,0 33 | 1000188 wak-google,4 34 | 1000337 linyy1106,0 35 | 1000583 ztai-goog,0 36 | 1000442 oferye,0 37 | 1000582 xiangliu701,0 38 | March, 8 39 | 40 | hcl 41 | 1000513 agnesamreetha,0 42 | 1000538 manikandan-e,0 43 | March, 0 44 | 45 | ibm 46 | 1000453 sotaoverride,0 47 | 1000160 aditya0124,0 48 | 1000003 anoo1,2 49 | 1000177 agusrod28,0 50 | 1000353 Alpana07,0 51 | 1000446 alvintpwang,0 52 | 1000004 geissonator,192 53 | 1000009 amboar,46 54 | 1000075 antwil,0 55 | 1000358 adathatri,3 56 | 1000401 asmithakarun,0 57 | 1000085 bjwyman,10 58 | 1000364 nomuken007,0 59 | 1000002 bradbishop,14 60 | 1000355 bstegmiller,0 61 | 1000360 cnpalmer,0 62 | 1000193 camvanng,0 63 | 1000440 wangkair,3 64 | 1000058 charleshofer,0 65 | 1000001 causten,0 66 | 1000078 cbostic,0 67 | 1000040 legoater,0 68 | 1000056 dkodihal,8 69 | 1000281 derick-montague,11 70 | 1000084 dhruvibm,14 71 | 1000396 dixsie,3 72 | 1000025 eddiejames,4 73 | 1000171 vazpando,0 74 | 1000170 ernestrcmx,0 75 | 1000018 gkeishin,16 76 | 1000354 GiridhariKrishna,0 77 | 1000386 GiridhariKrishnan,0 78 | 1000020 gtmills,1 79 | 1000102 iftekharuli,0 80 | 1000086 ojayanth,4 81 | 1000207 jaypadath,0 82 | 1000441 jenkins-openbmc-ibm,0 83 | 1000016 jk-ozlabs,0 84 | 1000387 wrightjl1,0 85 | 1000348 jinuthomas,0 86 | 1000013 shenki,19 87 | 1000465 JolieKu,2 88 | 1000235 joseph-reynolds,0 89 | 1000202 onye1,0 90 | 1000110 thalerj,0 91 | 1000049 krtaylor,0 92 | 1000103 lkammath,1 93 | 1000044 mine260309,17 94 | 1000089 devenrao,5 95 | 1000206 manojkiraneda,0 96 | 1000152 garzam,0 97 | 1000008 spinler,40 98 | 1000029 msbarth,5 99 | 1000145 youhour,0 100 | 1000026 micwalsh,4 101 | 1000021 mdmillerii,0 102 | 1000141 ngorugan,0 103 | 1000435 NamanNH,0 104 | 1000370 Paul-Greenwood,0 105 | 1000577 Pavithra7,2 106 | 1000053 prkatti1,2 107 | 1000362 PriyangaRamasamy,1 108 | 1000028 rahulmah,4 109 | 1000427 RameshIyyar,0 110 | 1000022 ratagupt,1 111 | 1000350 raviteja-b,0 112 | 1000258 BeccaBroek,0 113 | 1000214 ryanarnell,0 114 | 1000181 sampmisr,1 115 | 1000346 sansomas,0 116 | 1000338 santoshpuranik,1 117 | 1000121 samahaba,0 118 | 1000148 Shakeebbk,0 119 | 1000331 smccarney,16 120 | 1000019 sivassrr,0 121 | 1000027 SrideviRamesh,4 122 | 1000042 swanman,0 123 | 1000129 ssombar,0 124 | 1000382 sunharis,1 125 | 1000522 SunnySrivastava1984,0 126 | 1000081 sjitindarsingh,0 127 | 1000423 susilsi7,2 128 | 1000073 swe12345,0 129 | 1000344 trajeswaran,0 130 | 1000005 tomjoseph83,2 131 | 1000393 vkaverap,0 132 | 1000014 vishwabmc,2 133 | 1000402 yoshiemuranaka,13 134 | 1000421 zaxxed,2 135 | 1000359 zane131,0 136 | 1000369 bentyner,2 137 | 1000162 navrathi,0 138 | March, 480 139 | 140 | inspur 141 | 1000549 lllllccccc,0 142 | 1000547 zhanghaodi,2 143 | 1000400 ChicagoDuan,0 144 | 1000397 lxwinspur,9 145 | 1000305 wangzqbj,0 146 | 1000444 XiaochaoMa,1 147 | March, 12 148 | 149 | intel 150 | 1000534 aambroze,0 151 | 1000588 awiatrow,1 152 | 1000569 anoopsx,0 153 | 1000269 apuli1,9 154 | 1000479 arun-pm,0 155 | 1000566 chalapathivenkataramashetty,0 156 | 1000376 ygangch,0 157 | 1000304 cyang29,1 158 | 1000419 sahudx,0 159 | 1000550 epcorona,0 160 | 1000412 Gade-RajasekharReddy,0 161 | 1000461 iklm,0 162 | 1000166 yoojae,0 163 | 1000164 feistjj,11 164 | 1000157 JamesMihm,0 165 | 1000478 jansow,0 166 | 1000276 jmbills,1 167 | 1000416 jayaprakashmutyala,9 168 | 1000300 hcleepinga,0 169 | 1000215 cjia4,0 170 | 1000278 Howitzer105mm,2 171 | 1000415 Joshi-Mansi,2 172 | 1000438 kamkowalski,0 173 | 1000557 skarthick85,0 174 | 1000509 kathy-intel,0 175 | 1000439 KlaudiaJ,0 176 | 1000218 kuiyingw,0 177 | 1000495 martamazur,0 178 | 1000413 nitin1sx,2 179 | 1000374 nipot,0 180 | 1000476 nilanintc,0 181 | 1000246 prapkiewicz,0 182 | 1000472 pmatuszc,0 183 | 1000565 PraveenPavithran,0 184 | 1000460 phawryle,2 185 | 1000298 radivojejovanovic,0 186 | 1000414 Rashmi-RV,0 187 | 1000424 yuren1x,0 188 | 1000168 rthomaiy,1 189 | 1000418 saravanan-palanisamy,0 190 | 1000208 sharadkhetan,0 191 | 1000411 Smriti-Ayushi,0 192 | 1000501 srkntmondalIntel,1 193 | 1000410 sumbhat90,1 194 | 1000295 htnakayrus,0 195 | 1000409 tsdunc,0 196 | 1000163 vmauery,7 197 | 1000498 vijayasshetty,1 198 | 1000312 vbodired,0 199 | 1000434 wgolgowski,0 200 | 1000330 qiangxu1,0 201 | 1000107 yongli3,5 202 | 1000371 yli-i,0 203 | 1000433 zkurzyns,3 204 | 1000483 zlukwins,0 205 | 1000559 ZhikuiRen,3 206 | 1000366 RodgerZhu,0 207 | 1000484 askibows,0 208 | 1000505 moleszki,0 209 | 1000482 mspica1,0 210 | March, 62 211 | 212 | inventec 213 | 1000228 YangBrianCW,0 214 | 1000104 KenChenIEC,0 215 | March, 0 216 | 217 | lenovo 218 | 1000527 ypinky,0 219 | March, 0 220 | 221 | nuvoton 222 | 1000273 maxdog988,0 223 | 1000343 medadyoung,0 224 | 1000289 oshalk,0 225 | 1000342 stanleychuys,1 226 | 1000294 timlee66,0 227 | 1000190 tmaimon,0 228 | 1000268 warp5tw,0 229 | March, 1 230 | 231 | quanta 232 | 1000384 dukedu83,0 233 | 1000325 Fran-Hsu,0 234 | 1000357 georgehung1210,0 235 | 1000391 hank93304,0 236 | 1000317 PKLee-Quanta,0 237 | 1000329 jiangchyishian,0 238 | 1000404 SpencerKu,1 239 | 1000335 tonylee79,7 240 | 1000322 YHLiang85,0 241 | March, 8 242 | 243 | rcs 244 | 1000037 madscientist159,0 245 | March, 0 246 | 247 | wistron 248 | 1000497 AndyYFWang,0 249 | 1000454 BenPai99,1 250 | 1000493 bobkingkkp,14 251 | March, 15 252 | 253 | yadro 254 | 1000192 AlexanderAmelkin,0 255 | 1000219 nest1ing,1 256 | 1000131 artemsen,1 257 | 1000182 fr0st61te,0 258 | 1000225 Ramkosh,0 259 | 1000422 alexeistepanov,0 260 | March, 2 261 | 262 | -------------------------------------------------------------------------------- /release/metrics/2020-01: -------------------------------------------------------------------------------- 1 | ampere 2 | 1000252 chuongtranle,0 3 | 1000249 hyche,0 4 | 1000245 TungVuX,0 5 | 1000248 hienvpham,0 6 | 1000267 thinhp,0 7 | January, 0 8 | 9 | facebook 10 | 1000212 amithash,0 11 | 1000546 HCL-BMC,2 12 | 1000000 williamspatrick,4 13 | 1000223 sdasari73,0 14 | 1000271 vijaykhemka,7 15 | 1000513 agnesamreetha,0 16 | 1000538 manikandan-e,0 17 | 1000544 thillaivasan,0 18 | January, 13 19 | 20 | google 21 | 1000539 alex310110,4 22 | 1000233 BenjaminFair,1 23 | 1000388 brandonkimbk,0 24 | 1000099 nasamuffin,0 25 | 1000520 Krellan,0 26 | 1000156 kunyi731,0 27 | 1000313 mgersh,0 28 | 1000052 yuennancy,0 29 | 1000265 osenft,0 30 | 1000100 pstrinkle,0 31 | 1000502 peterlundgren,1 32 | 1000500 quadpixels,0 33 | 1000188 wak-google,1 34 | 1000337 linyy1106,0 35 | 1000583 ztai-goog,0 36 | 1000442 oferye,0 37 | 1000582 xiangliu701,0 38 | January, 7 39 | 40 | hcl 41 | 1000513 agnesamreetha,0 42 | 1000538 manikandan-e,0 43 | January, 0 44 | 45 | ibm 46 | 1000453 sotaoverride,3 47 | 1000160 aditya0124,0 48 | 1000003 anoo1,0 49 | 1000177 agusrod28,0 50 | 1000353 Alpana07,0 51 | 1000446 alvintpwang,1 52 | 1000004 geissonator,18 53 | 1000009 amboar,17 54 | 1000075 antwil,0 55 | 1000358 adathatri,4 56 | 1000401 asmithakarun,0 57 | 1000085 bjwyman,4 58 | 1000364 nomuken007,0 59 | 1000002 bradbishop,130 60 | 1000355 bstegmiller,0 61 | 1000360 cnpalmer,0 62 | 1000193 camvanng,0 63 | 1000440 wangkair,0 64 | 1000058 charleshofer,0 65 | 1000001 causten,0 66 | 1000078 cbostic,0 67 | 1000040 legoater,0 68 | 1000056 dkodihal,7 69 | 1000281 derick-montague,32 70 | 1000084 dhruvibm,1 71 | 1000396 dixsie,0 72 | 1000025 eddiejames,0 73 | 1000171 vazpando,0 74 | 1000170 ernestrcmx,0 75 | 1000018 gkeishin,10 76 | 1000354 GiridhariKrishna,0 77 | 1000386 GiridhariKrishnan,0 78 | 1000020 gtmills,15 79 | 1000102 iftekharuli,0 80 | 1000086 ojayanth,1 81 | 1000207 jaypadath,0 82 | 1000441 jenkins-openbmc-ibm,0 83 | 1000016 jk-ozlabs,1 84 | 1000387 wrightjl1,0 85 | 1000348 jinuthomas,0 86 | 1000013 shenki,11 87 | 1000465 JolieKu,0 88 | 1000235 joseph-reynolds,1 89 | 1000202 onye1,0 90 | 1000110 thalerj,0 91 | 1000049 krtaylor,0 92 | 1000103 lkammath,0 93 | 1000044 mine260309,12 94 | 1000089 devenrao,1 95 | 1000206 manojkiraneda,0 96 | 1000152 garzam,0 97 | 1000008 spinler,35 98 | 1000029 msbarth,18 99 | 1000145 youhour,0 100 | 1000026 micwalsh,13 101 | 1000021 mdmillerii,0 102 | 1000141 ngorugan,1 103 | 1000435 NamanNH,0 104 | 1000370 Paul-Greenwood,0 105 | 1000577 Pavithra7,0 106 | 1000053 prkatti1,2 107 | 1000362 PriyangaRamasamy,0 108 | 1000028 rahulmah,1 109 | 1000427 RameshIyyar,0 110 | 1000022 ratagupt,18 111 | 1000350 raviteja-b,0 112 | 1000258 BeccaBroek,0 113 | 1000214 ryanarnell,0 114 | 1000181 sampmisr,1 115 | 1000346 sansomas,0 116 | 1000338 santoshpuranik,0 117 | 1000121 samahaba,0 118 | 1000148 Shakeebbk,0 119 | 1000331 smccarney,0 120 | 1000019 sivassrr,0 121 | 1000027 SrideviRamesh,4 122 | 1000042 swanman,0 123 | 1000129 ssombar,0 124 | 1000382 sunharis,0 125 | 1000522 SunnySrivastava1984,0 126 | 1000081 sjitindarsingh,0 127 | 1000423 susilsi7,4 128 | 1000073 swe12345,0 129 | 1000344 trajeswaran,0 130 | 1000005 tomjoseph83,5 131 | 1000393 vkaverap,0 132 | 1000014 vishwabmc,3 133 | 1000402 yoshiemuranaka,0 134 | 1000421 zaxxed,0 135 | 1000359 zane131,1 136 | 1000369 bentyner,3 137 | 1000162 navrathi,0 138 | January, 378 139 | 140 | inspur 141 | 1000549 lllllccccc,0 142 | 1000547 zhanghaodi,1 143 | 1000400 ChicagoDuan,0 144 | 1000397 lxwinspur,8 145 | 1000305 wangzqbj,6 146 | 1000444 XiaochaoMa,2 147 | January, 17 148 | 149 | intel 150 | 1000534 aambroze,1 151 | 1000588 awiatrow,0 152 | 1000569 anoopsx,0 153 | 1000269 apuli1,4 154 | 1000479 arun-pm,1 155 | 1000566 chalapathivenkataramashetty,0 156 | 1000376 ygangch,0 157 | 1000304 cyang29,4 158 | 1000419 sahudx,0 159 | 1000550 epcorona,0 160 | 1000412 Gade-RajasekharReddy,2 161 | 1000461 iklm,0 162 | 1000166 yoojae,1 163 | 1000164 feistjj,8 164 | 1000157 JamesMihm,0 165 | 1000478 jansow,3 166 | 1000276 jmbills,2 167 | 1000416 jayaprakashmutyala,4 168 | 1000300 hcleepinga,0 169 | 1000215 cjia4,0 170 | 1000278 Howitzer105mm,2 171 | 1000415 Joshi-Mansi,1 172 | 1000438 kamkowalski,1 173 | 1000557 skarthick85,3 174 | 1000509 kathy-intel,1 175 | 1000439 KlaudiaJ,0 176 | 1000218 kuiyingw,0 177 | 1000495 martamazur,0 178 | 1000413 nitin1sx,0 179 | 1000374 nipot,1 180 | 1000476 nilanintc,0 181 | 1000246 prapkiewicz,0 182 | 1000472 pmatuszc,0 183 | 1000565 PraveenPavithran,0 184 | 1000460 phawryle,3 185 | 1000298 radivojejovanovic,0 186 | 1000414 Rashmi-RV,1 187 | 1000424 yuren1x,0 188 | 1000168 rthomaiy,9 189 | 1000418 saravanan-palanisamy,0 190 | 1000208 sharadkhetan,0 191 | 1000411 Smriti-Ayushi,0 192 | 1000501 srkntmondalIntel,0 193 | 1000410 sumbhat90,0 194 | 1000295 htnakayrus,4 195 | 1000409 tsdunc,1 196 | 1000163 vmauery,1 197 | 1000498 vijayasshetty,0 198 | 1000312 vbodired,1 199 | 1000434 wgolgowski,0 200 | 1000330 qiangxu1,0 201 | 1000107 yongli3,9 202 | 1000371 yli-i,0 203 | 1000433 zkurzyns,0 204 | 1000483 zlukwins,4 205 | 1000559 ZhikuiRen,4 206 | 1000366 RodgerZhu,0 207 | 1000484 askibows,0 208 | 1000505 moleszki,0 209 | 1000482 mspica1,0 210 | January, 76 211 | 212 | inventec 213 | 1000228 YangBrianCW,0 214 | 1000104 KenChenIEC,0 215 | January, 0 216 | 217 | lenovo 218 | 1000527 ypinky,1 219 | January, 1 220 | 221 | nuvoton 222 | 1000273 maxdog988,0 223 | 1000343 medadyoung,0 224 | 1000289 oshalk,0 225 | 1000342 stanleychuys,0 226 | 1000294 timlee66,0 227 | 1000190 tmaimon,0 228 | 1000268 warp5tw,0 229 | January, 0 230 | 231 | quanta 232 | 1000384 dukedu83,0 233 | 1000325 Fran-Hsu,0 234 | 1000357 georgehung1210,0 235 | 1000391 hank93304,0 236 | 1000317 PKLee-Quanta,1 237 | 1000329 jiangchyishian,0 238 | 1000404 SpencerKu,0 239 | 1000335 tonylee79,10 240 | 1000322 YHLiang85,2 241 | January, 13 242 | 243 | rcs 244 | 1000037 madscientist159,0 245 | January, 0 246 | 247 | wistron 248 | 1000497 AndyYFWang,0 249 | 1000454 BenPai99,1 250 | 1000493 bobkingkkp,5 251 | January, 6 252 | 253 | yadro 254 | 1000192 AlexanderAmelkin,0 255 | 1000219 nest1ing,2 256 | 1000131 artemsen,0 257 | 1000182 fr0st61te,1 258 | 1000225 Ramkosh,0 259 | 1000422 alexeistepanov,0 260 | January, 3 261 | 262 | --------------------------------------------------------------------------------