xref: /src/sys/arch/arm/xscale/ixp425-fw.README

$NetBSD: ixp425-fw.README,v 1.7 2023/06/18 19:08:18 gutteridge Exp $

IXP425 NPE Microcode
~~~~~~~~~~~~~~~~~~~~

The IXP425 contains up to three network co-processors called NPEs,
"Network Processing Engines". These control all the networking features
of the IXP425 and are usually supported by Access Library (AL) software
and NPE microcode obtained from Intel.

The AL source code and compiled object files are encumbered by a license
which precludes its distribution with NetBSD.

However, NetBSD includes source for a native driver for NPE Ethernet
written by Sam Leffler. The driver requires that Intel's microcode is
loaded onto the NPE, but since we cannot distribute the microcode, it
must be downloaded from Intel's website after agreeing to their click-
through license.

You must grab the NPE microcode from here:

 https://downloadcenter.intel.com/download/13757/IXP400-Software-NPE-Microcode-v3-0-without-crypto

SHA1 (IPL_ixp400NpeLibrary-3_0.zip) = dda6b27265e6db3dfec68361644197c0f311a07b

or the older version which is archived here:
 https://mirror2.openwrt.org/sources/IPL_ixp400NpeLibrary-2_4.zip

SHA1 (IPL_ixp400NpeLibrary-2_4.zip) = abf1562e750e16e6f9baf9892a59640f863a693e

Select the "Download (without Crypto)" link in the "NPE Microcode"
section. Note that there is no benefit in selecting the "with Crypto"
microcode at this time since NetBSD does not support it.

For reference, the "with Crypto" version is available here:
  https://downloads.openwrt.org/sources/IPL_ixp400NpeLibraryWithCrypto-2_4.zip

SHA1(IPL_ixp400NpeLibraryWithCrypto-2_4.zip)= 48beb80564fbbb7fb7861188cad26e896b5a5afc

Note: At the time of writing (February 2017), the NPE Microcode is at
version 3.0. However, the last known microcode version to work is 2.4.

After clicking the link, you will be directed to a click-through license
page. Assuming you agree to the terms of the license (and you are
*strongly* advised to print it out and read it carefully) you will then
be able to download a ZIP file containing the microcode.

Extract the microcode under any decent Unix-like system using the "unzip"
command provided with the OS, or with the version included in the pkgsrc
collection under archivers/unzip:

	$ unzip IPL_ixp400NpeLibrary-2_4.zip

Next, you must generate a microcode image suitable for inclusion in the
NetBSD kernel.

	$ cd ixp400_xscale_sw/src/npeDl

In this directory, create a file called IxNpeMicrocode.h, and populate
it with the following two #defines:

#define IX_NPEDL_NPEIMAGE_NPEB_ETH
#define IX_NPEDL_NPEIMAGE_NPEC_ETH

Note: If you know that you will only ever use Ethernet on NPE-B, you can
omit the second line, and vice-versa.

Now compile and run ixNpeDlImageConverter.c:

	$ cc ixNpeDlImageConverter.c -o foo
	$ ./foo

Congratulations! You should now have a file called "IxNpeMicrocode.dat"
in the current directory. Please take heed of the license you agreed to
when you downloaded the Microcode. The license contains clauses which
control the redistribution of this microcode object file.

Now copy "IxNpeMicrocode.dat" to the sys/arch/arm/xscale directory in
your NetBSD source tree. All you have to do now is run config(1) and
build your kernel.

If all went as planned, the Ethernet controller(s) will show up as npe0
and npe1. That's all there is to it!

It is planned that pkgsrc will, eventually, automate most of the above
procedure.