README

# iPXE README File (as adapted to illumos systems)

To build:

    gmake install

ipxe, unlike virtually all other software, actually assumes and requires
GNU ld to build.  This is because of the presence of GNU linker scripts.
These could be converted to ld, but there's little need; since this does
not generate anything that actually runs under illumos, the GNU linker's
deficiencies aren't especially important.

If your system is not SmartOS, or is older than 20121213, your 'awk' is
most likely 'oawk', which will hang on a construct used by the
makefiles.  Use nawk or gawk instead.

The build system uses grep -E, supported by the XPG4 grep but not the
Sun one.  You can also use GNU grep if necessary.

You will need gcc and GNU binutils installed from pkgsrc or some similar
repository of packages, or to have built your own.  Version requirements
are very broad and almost anything should suffice.

You may need to obtain and install syslinux, which does build on illumos
systems.  This utility is used by util/genliso and util/gensdsk.  You
will need to determine whether your use case requires these utilities.

For any more detailed instructions, see <http://ipxe.org>

## Updating

Occasionally we'll want to sync with upstream, e.g., to pick up nic card
driver updates. This documents that process.

1. First you need an issue ID either in Jira or github for the sync up.
2. Add a remote for the upstream ipxe repo if you don't already have one.

        git remote add upstream https://github.com/ipxe/ipxe

3. Add a remote tracking branch for the upstream repo and fetch their
   changes.

        git checkout -b upstream upstream/master
        git fetch upstream

4. Create a branch for the issue and merge from upstream.

        git checkout -b <ISSUE_ID>
        git merge upstream

    Change the commit message to reflect the Triton commit message format.

5. Push the issue branch.

        git push -u origin HEAD:<branchname>

    Jenkins will automatically create a build for you and push the build
    artifacts to Manta and the experimental channel on
    updates.tritondatacenter.com.

6. Once the jenkins build is done you'll need to update sdc-booter, so
   cd to wherever you have a clone of that repo.

        cd <wherever you keep your repos>/sdc-booter

7. Again, create a branch for the issue.

        git checkout -b <ISSUE_ID>

8. Use the `update_ipxe` script. This will update `tftpboot/snponly.efi` and
   `tfptboot/undionly.kpxe`. Again, commit the changes and push the branch
   up.

        ./tools/update_ipxe <ISSUE_ID>
        git add tftpboot
        git commit
        git push -u origin HEAD:<branchname>

    And again, Jenkins will automatically create a build and push it to
    the experimental channel.

    Note: You need to have write permission to TritonDataCenter's repo(s) for
    this step. If you're an outside contributor push it to your own fork and
    open a pull request.

You're done. After testing, get code review, integration approval, then
update the merge commit message and commit.

**Note about merging:** Github does not allow fast-forward merges so do not
use the Github pull request's green button to bring in your upstream merge.
Github MUST add a merge commit on top of your merge-from-upstream merge
commit, never mind any post-merge adjustment commits you may need to make.
Regardless, once approved via github PR review, you should, in your
ipxe repo:

	git checkout master
	git merge <ISSUE_ID>

if it does NOT say "fast-forward", you will need to start over from the
updated master branch in our ipxe.  Here is what it should look like:

```
	smartos-build(~/ipxe)[0]% git merge TRITON-2354
	Updating 1522fe85..c7814698
	Fast-forward
	smartos-build(~/ipxe)[0]% 
```

Finally update the merge message with the ISSUE_ID, and a list of commits
from upstream.  To obtain list, first find the LAST upstream commit you
merged priot to this one.  Call it LAST_COMMIT.  Then:

```
git log --format=oneline $LAST_COMMIT.. | awk '{print "commit " $1 ; $1 = "" ; print "   " $0}' > /tmp/list
```

The output in /tmp/list should appear in the merge commit below the
issue. The above example looks a bit like this:

```
commit c7814698ae41c5247750b3a54e29c0c83601fc9d
Merge: 1522fe85 3fe683eb
Author: Dan McDonald <danmcd@mnx.io>
Date:   Wed Dec 7 10:59:10 2022 -0500

    TRITON-2354 Merge properly with ipxe/ipxe to restore merge-commit path.
    
    commit 3fe683ebab29afacf224e6b0921f6329bebcdca7
        [lan78xx] Always enable automatic speed and duplex detection
    commit 41a9a5c7b3674f0fac6d8fa3b633cde17c2df78f
        [efi] Do not attempt EFI_USB_IO_PROTOCOL transfers during shutdown
    <MORE COMMITS not shown here...
```

And the "3fe684eb..." commit will be used for LAST_COMMIT on your NEXT
upstream merge.

Once the message is updated, then you can use "git push" from the command
line.  Github WILL be smart enough to close your PR.

## Testing changes

**Warning:** If there's a problem with the boot files the compute node(s) may
not be able to boot at all. It is recomended to perform testing on hardware
that you can access physically, or can withstand being down for an extended
period of time in case something goes wrong.

You'll need to test this on as many different hardware platforms and as many
different configurations as you can, including virtualized hardware such as
VMware, Linux KVM, and BHYVE. In particular, the following configurations
need to be tested.

* Booting from the USB in EFI mode
* Booting from the USB in legacy mode
* PXE booting from the hardware NIC and chain loading ipxe over the network
  in EFI mode
* PXE booting from the hardware NIC and chain loading ipxe over the network
  in legacy mode
* VMware (using images from
  <https://github.com/TritonDataCenter/sdc-headnode/tree/master/vmware>)
  which will chain load iPXE from booter.

To install the new ipxe files on an existing Triton USB, download the ipxe
build either from Manta or updates.tritondatacenter.com. Extract the tar and
copy the contents of the extracted boot directory to the boot directory on the
USB, overwriting the existing files.