Merge pull request #34 from williamspatrick/c++-style
Update style guide to include Python and C++
diff --git a/cheatsheet.md b/cheatsheet.md
index 4e2c8f5..8909da8 100644
--- a/cheatsheet.md
+++ b/cheatsheet.md
@@ -88,21 +88,71 @@
tree](https://github.com/openbmc/qemu) with patches on their way upstream or
temporary work-arounds that add to QEMU's capabilities where appropriate.
-QEMU's wiki has instructions for [building from
-source](http://wiki.qemu.org/Documentation/GettingStartedDevelopers).
-
-Assuming the CWD is the root of the openbmc tree, a palmetto-bmc machine can be
-invoked with:
+```
+qemu-system-arm -m 256 -M palmetto-bmc -nographic \
+-drive file=<path>/flash-palmetto,format=raw,if=mtd \
+-net nic \
+-net user,hostfwd=:127.0.0.1:2222-:22,hostfwd=:127.0.0.1:2443-:443,hostname=qemu \
+```
+If you get an error you likely need to build QEMU (see the section in this document). If no error and QEMU starts up just change the port when interacting with the BMC...
```
-qemu-system-arm \
- -M palmetto-bmc \
- -m 256 \
- -append "console=ttyS4" \
- -nographic \
- -kernel build/tmp/deploy/images/palmetto/cuImage-palmetto.bin \
- -dtb build/tmp/deploy/images/palmetto/cuImage-aspeed-bmc-opp-palmetto.dtb \
- -initrd build/tmp/deploy/images/palmetto/obmc-phosphor-image-palmetto.cpio.gz
+curl -c cjar -b cjar -k -H "Content-Type: application/json" \
+-X POST https://localhost:2443/login -d "{\"data\": [ \"root\", \"0penBmc\" ] }"
+```
+or
+
+```
+ssh -p 2222 root@localhost
```
To quit, type `Ctrl-a c` to switch to the QEMU monitor, and then `quit` to exit.
+
+## Building QEMU
+
+```
+git clone https://github.com/openbmc/qemu.git
+cd qemu
+git submodule update --init dtc
+mkdir build
+cd build
+../configure --target-list=arm-softmmu
+make
+```
+Built file will be located at: ```arm-softmmu/qemu-system-arm```
+
+### Use a bridge device
+Using a bridge device requires a bit of root access to set it up. The benefit
+is your qemu session runs in the bridges subnet so no port forwarding is needed.
+There are packages needed to yourself a virbr0 such as...
+
+```
+apt-get install libvirt libvirt-bin bridge-utils uml-utilities qemu-system-common
+
+qemu-system-arm -m 256 -M palmetto-bmc -nographic \
+-drive file=<path>/flash-palmetto,format=raw,if=mtd \
+-net nic,macaddr=C0:FF:EE:00:00:02,model=ftgmac100 \
+-net bridge,id=net0,helper=/usr/lib/qemu-bridge-helper,br=virbr0
+```
+
+There are some other useful parms like that can redirect the console to another
+window. This results in having an easily accessible qemu command session.
+```-monitor stdio -serial pty -nodefaults```
+
+
+## Booting the host
+
+Login:
+```
+curl -c cjar -k -X POST -H "Content-Type: application/json" -d '{"data": [ "root", "0penBmc" ] }' https://palm5-bmc/login
+```
+
+Connect to host console:
+```
+ssh -p 2200 root@bmc
+```
+
+Power on:
+```
+curl -c cjar -b cjar -k -H "Content-Type: application/json" -X POST -d '{"data": []}' https://palm5-bmc/org/openbmc/control/chassis0/action/powerOn
+```
diff --git a/code-update.md b/code-update.md
index da85f5e..b599474 100644
--- a/code-update.md
+++ b/code-update.md
@@ -29,17 +29,57 @@
The OpenBMC bootloader
+Preparing for BMC code Update
+-----------------------------
+
+The BMC normally runs with the read-write and read-only file systems
+mounted, which means these images may be read (and written, for the
+read-write filesystem) at any time. Because the updates are distributed
+as complete file system images, these filesystems have to be unmounted
+to replace them with new images. To unmount these file systems all
+applications must be stopped.
+
+By default an orderly `reboot` will stop all applications and unmount
+the root filesystem, and the images copied into the `/run/initramfs`
+directory will be applied at that point before restarting. This also
+applied to the `shutdown` and `halt` commands -- they will write the
+flash before stopping.
+
+As an alternative, the an option can be parsed by the `init` script in
+the initramfs to copy the required contents of these filesystems into
+RAM so the images can be applied while the rest of the application stack
+is running and progress can be monitored over the network. The
+`update` script can then be called to write the images while the
+system is operational and its progress output monitored.
+
Update from the OpenBMC shell
-----------------------------
-To update from the OpenBMC shell, copy one or more of these `image-*` files to
-the directory:
+To update from the OpenBMC shell, follow the steps in this section.
+
+It is recommended that the BMC be prepared for update:
+
+ fw_setenv openbmconce copy-files-to-ram copy-base-filesystem-to-ram
+ reboot
+
+Copy one or more of these `image-*` files to the directory:
/run/initramfs/
-(preserving the filename), then reboot. Before the system reboots, the new image
-will be copied to the appropriate flash partition.
+(preserving the filename), then run the `update` script to apply the images:
+ /run/initramfs/update
+
+then reboot to finish applying:
+
+ reboot
+
+During the reboot process the `update` script will be invoked after
+the file systems are unmounted to complete the update process.
+
+Some optional features are available, see the help for more details:
+
+ /run/initramfs/update --help
Update via REST
---------------
@@ -47,18 +87,33 @@
An OpenBMC system can download an update image from a TFTP server, and apply
updates, controlled via REST. The general procedure is:
- 1. Configure update settings
- 2. Initiate update
- 3. Check flash status
+ 1. Prepare system for update
+ 2. Configure update settings
+ 3. Initiate update
+ 4. Check flash status
+ 5. Reboot the BMC
+
+### Prepare system for update
+
+Perform a POST to invoke the `PrepareForUpdate` method of the `/flash/bmc` object:
+
+ curl -b cjar -k -H "Content-Type: application/json" -X POST \
+ -d '{"data": ["<TFTP server IP address>", "<filename>"]}' \
+ https://bmc/org/openbmc/control/flash/bmc/action/prepareForUpdate
+
+This will setup the u-boot environment and reboot the BMC. If no other
+images were pending the BMC should return in about 2 minutes.
+
### Configure update settings
There are a few settings available to control the update process:
- * `preserve_network_settings`: Preserve network settings, only needed if updating uboot
- * `restore_application_defaults`: update read-only file system
+ * `preserve_network_settings`: Preserve network settings, only needed if updating the whole flash
+ * `restore_application_defaults`: update (clear) the read-write file system
* `update_kernel_and_apps_only`: update kernel and initramfs
- * `clear_persistent_files`: Erase persistent files
+ * `clear_persistent_files`: ignore the persistent file list when resetting applications defaults
+ * `auto_apply`: Attempt to write the images by invoking the `Apply` method after the images are unpacked.
To configure the update settings, perform a REST PUT to
`/control/flash/bmc/attr/<setting>`. For example:
@@ -77,15 +132,44 @@
### Check flash status
-You can query the progress of the flash with a simple GET request:
+You can query the progress of the download and image verificaton with
+a simple GET request:
curl -b cjar -k https://bmc/org/openbmc/control/flash/bmc
+Or perform a POST to invoke the `GetUpdateProgress` method of the `/flash/bmc` object:
+
+ curl -b cjar -k -H "Content-Type: application/json" -X POST \
+ -d '{"data": []}' \
+ https://bmc/org/openbmc/control/flash/bmc/action/GetUpdateProgress
+
+
+Note: the status will not advance from `Writing images to flash` without
+calling the `GetUpdateProgress` method.
+
+If the status is `Image ready to apply.` then you can either initiate
+a reboot or call the Apply method to start the process of writing the
+flash.
+
+### Reboot the BMC
+
+To start using the new images, reboot the BMC using the warmReset method
+of the BMC control object:
+
+
+ curl -b cjar -k -H "Content-Type: application/json" -X POST \
+ -d '{"data": []}' \
+ https://bmc/org/openbmc/control/bmc0/action/warmReset
+
+
Host code update
================
-Using a similar method, we can update the host firmware (or "BIOS"), by
-performing a POST request to call the `updateViaTftp` method of
+The host firmware (or "BIOS") can be updated in a similar method. Because
+the BMC does not use the host firmware it is updated when the download is
+completed. This assumes the host is not accessing its firmware.
+
+Perform a POST request to call the `updateViaTftp` method of
`/control/flash/bios` (instead of `/control/flash/bmc` used above). To initiate
the update:
diff --git a/contributing.md b/contributing.md
index 070f63c..e97625b 100644
--- a/contributing.md
+++ b/contributing.md
@@ -121,6 +121,52 @@
Your contribution will generally need to be reviewed before being accepted.
+
+Submitting changes via Gerrit server
+------------------------------------
+
+The openbmc gerrit server supports Github credentials, its link is:
+
+ https://gerrit.openbmc-project.xyz/#/q/status:open
+
+_One time setup_: Login to the WebUI with your github credentials and verify on
+your account Settings that your SSH keys were imported:
+
+ https://gerrit.openbmc-project.xyz/#/settings/
+
+Most repositories are supported by the gerrit server, the current list can be
+found under Projects -> List:
+
+ https://gerrit.openbmc-project.xyz/#/admin/projects/
+
+If you're going to be working with gerrit often, it's useful to create an SSH
+host block in ~/.ssh/config. Ex:
+```
+Host openbmc.gerrit
+ Hostname gerrit.openbmc-project.xyz
+ Port 29418
+ User your_github_id
+```
+
+From your openbmc git repository, add a remote to the gerrit server, where
+'openbmc_repo' is the current git repository you're working on, such as
+phosphor-rest-server, and 'openbmc.gerrit' is the name of the Host previously added:
+
+ `git remote add gerrit ssh://openbmc.gerrit/openbmc/openbmc_repo`
+
+Obtain the git hook commit-msg to automatically add a Change-Id to the commit
+message, which is needed by gerrit:
+
+ `gitdir=$(git rev-parse --git-dir)`
+
+ `scp -p -P 29418 openbmc.gerrit:hooks/commit-msg ${gitdir}/hooks`
+
+To submit a change set, commit your changes, and push to the gerrit server,
+where 'gerrit' is the name of the remote added with the git remote add command:
+
+ `git push gerrit HEAD:refs/for/master`
+
+
Avoid references to non-public resources
----------------------------------------
@@ -147,7 +193,7 @@
Best practices for C
--------------------
-There are numerous resources avaialble elsewhere, but a few items that are
+There are numerous resources available elsewhere, but a few items that are
relevant to OpenBMC work:
* You almost never need to use `system(<some shell pipeline>)`. Reading and
@@ -165,7 +211,7 @@
C types
* Declare internal-only functions as `static`, declare read-only data
- as `const` where possble.
+ as `const` where possible.
* Ensure that your code compiles without warnings, especially for changes
to the kernel.
@@ -175,11 +221,11 @@
-------------------------------------
By making a contribution to this project, I certify that:
-
+
(a) The contribution was created in whole or in part by me and I
have the right to submit it under the open source license
indicated in the file; or
-
+
(b) The contribution is based upon previous work that, to the best
of my knowledge, is covered under an appropriate open source
license and I have the right under that license to submit that
@@ -187,11 +233,11 @@
by me, under the same open source license (unless I am
permitted to submit under a different license), as indicated
in the file; or
-
+
(c) The contribution was provided directly to me by some other
person who certified (a), (b) or (c) and I have not modified
it.
-
+
(d) I understand and agree that this project and the contribution
are public and that a record of the contribution (including all
personal information I submit with it, including my sign-off) is
diff --git a/dbus-interfaces.md b/dbus-interfaces.md
index 524bc3f..c207a0a 100644
--- a/dbus-interfaces.md
+++ b/dbus-interfaces.md
@@ -44,7 +44,7 @@
### signals
| name | signature | description |
| ------------- | --------- | ------------------------------------------------ |
-| `ReceivedMsg` | `yyyyay` | **An IPMI message was received from the host processor firmware.**|
+| `ReceivedMessage` | `yyyyay` | **An IPMI message was received from the host processor firmware.**|
| | `y` | IPMI seq. |
| | `y` | IPMI netfn. |
| | `y` | IPMI lun. |
@@ -306,11 +306,18 @@
The control.BmcFlash interface allows applications update the BMC firmware.
### methods
-| name | in signature | out signature | description |
-| --------------- | ------------ | ------------- | --------------------------- |
-| `updateViaTftp` | `ss` | `void` | **Perform a BMC firmware update using a TFTP server.**|
-| | `s` | | The ipv4 address of the TFTP server hosting the firmware image file.|
-| | `s` | | The name of the file containing the BMC firmware image.|
+| name | in signature | out signature | description |
+| ------------------- | ------------ | ------------- | --------------------------- |
+| `updateViaTftp` | `ss` | `void` | **Perform a BMC firmware update using a TFTP server.**|
+| | `s` | | The ipv4 address of the TFTP server hosting the firmware image file.|
+| | `s` | | The name of the file containing the BMC firmware image.|
+| `update` | `s` | `void` | **Perform a BMC firmware update with a file already on the BMC.**|
+| | `s` | | The name of the file containing the BMC firmware image.|
+| `PrepareForUpdate` | `void` | `void` | **Reboot BMC with Flash content cached in RAM.**|
+| `Abort` | `void` | `void` | **Abort any pending, broken, or in-progress flash update.**|
+| `Apply` | `void` | `void` | **Initiate writing image to flash.**|
+| `GetUpdateProgress` | `void` | `s` | **Display progress log `Apply` phase.**|
+| | | `s` | The `status` and log output from `Apply`|
### signals
| name | signature | description |
@@ -322,12 +329,13 @@
### properties
| name | signature | description |
| ------------------------------ | --------- | ------------------------------- |
-| `status` | `s` | **?** |
+| `status` | `s` | **Description of the phase of the update.** |
| `filename` | `s` | **The name of the file containing the BMC firmware image.**|
| `preserve_network_settings` | `b` | **Perform a factory reset.** |
-| `restore_application_defaults` | `b` | **Perform a factory reset.** |
-| `update_kernel_and_apps` | `b` | **Perform a factory reset.** |
-| `clear_persistent_files` | `b` | **Perform a factory reset.** |
+| `restore_application_defaults` | `b` | **Clear modified files in read-write filesystem.** |
+| `update_kernel_and_apps` | `b` | **Do not update bootloader (requires image pieces).** |
+| `clear_persistent_files` | `b` | **Also remove persistent files when updating read-write filesystem.** |
+| `auto_apply` | `b` | **Attempt to apply image after unpacking (cleared if image verification fails).** |
### namespace
| path | required | description |
@@ -466,8 +474,8 @@
| `PowerLost` | `void` | **The power is off.** |
### properties
-| name | signature | description |
-| ------------- | --------- | --------------- |
+| name | signature | description |
+| --------------- | --------- | --------------- |
| `pgood` | `i` | **?** |
| `state` | `i` | **?** |
| `pgood_timeout` | `i` | **?** |
@@ -686,6 +694,6 @@
| `WatchdogError` | `void` | *The watchdog was not pinged before the timer expired.**|
### namespace
-| path | required | description |
-| -------------------------------- | -------- | ---------------------------------------- |
+| path | required | description |
+| ---------------------------------- | -------- | ---------------------------------------- |
| `/org/openbmc/watchdog/<watchdog>` | No | Any watchdog instances must be instantiated in the watchdog namespace. |
diff --git a/host-management.md b/host-management.md
index d223850..e313468 100644
--- a/host-management.md
+++ b/host-management.md
@@ -140,3 +140,27 @@
value is displayed in a string format. For example, a boot flags parameter value
of `0x8014000000` would be stored as a `8014000000` string in the
`settings/host0/boot_flags` property.
+
+Host power control
+------------------
+
+The host can be controlled through the `chassis` object. It implements a number
+of actions including powerOn and powerOff. These correspond to the IPMI
+`chassis power on` and `chassis power off` commands.
+
+Assuming you have logged in, the following will issue a POST with an empty data
+payload that powers the host on:
+
+```
+curl -c cjar -b cjar -k -H "Content-Type: application/json" -X POST \
+ -d '{"data": []}' https://bmc/org/openbmc/control/chassis0/action/powerOn
+```
+
+Other actions available are:
+
+ * `setIdentify` / `clearIdentify`
+ * `powerOff`
+ * `softPowerOff`
+ * `reboot`
+ * `softReboot`
+ * `getPowerState`
diff --git a/rest-api.md b/rest-api.md
index 10b01e9..4fe2e02 100644
--- a/rest-api.md
+++ b/rest-api.md
@@ -178,7 +178,7 @@
DELETE operations are for removing instances. Only DBUS objects (instances) can
be removed. If the underlying DBUS object implements the
`org.openbmc.Object.Delete` interface the REST server will call it. If
-`org.openbmc.Object.Delet`e is not implemented, the REST server will return a
+`org.openbmc.Object.Delete` is not implemented, the REST server will return a
HTTP 403 (Forbidden) error.
For example, to delete the event record with ID 0: