opsi on the Surface 3 with eMMC

We recently had a customer with a Microsoft Surface 3 Tablet which he wanted to manage. However the bootimage didnt boot at all. The customer then send us the tablet so we could analyze the problem and work on a fix.

The bootimage showed strange behaviour on the device. The first boot simply showed a steady cursor instead of a login prompt followed by the bootimage interface. The device however didn't show any other reaction. It froze.

As the first check the created pxe named pipe was shortened. It usually tells the bootimage which product to install and which opsi-server shall be connected. This time it only booted the image itself and did not had any other parameters. The screen showed kernel messages and a systemd boot process, but froze again with the same symptoms.

Therefore the kernel was instructed to boot into the first runlevel, which means basic driver support. It worked, the bootimage came up and a login prompt appeared. Firstly the opsi.service file was checked. This also worked and provided a network connection on the surface. Additionally the service file starting the master.py also did its job. So our scripts were not the cause of the boot issue.

Starting the init process manually by executing /sbin/init 3 froze the device again. Therefore one could think the init proces itself causes the freeze. There seems to be a kind of race condition on the Surface 3 device itself. Adding a sleep into our own init process, which triggers the init ptocess in /sbin/ in addition with the debug kernel parameter fixed the problem. The device now booted up fine and started the usual opsi bootimage interface.

The Surface 3 does not use a standard hard drive or NVME storage. It uses eMMC storage memory. The same storage smartphones use. The bootimage didn't handle these types of storage and also didn't include the drivers. However adding the eMMC kernel driver was not enough. Even with integrated eMMC storage driver the bootimage wouldn't see the storage. We had to dig deeply in the hardware of the Surface to find out the eMMC memory is connected through GPIO. After adding GPIO drivers into the bootimage kernel the storage was recognized and available for use.

The last step of providing Surface 3 support remained in integrating the eMMC storage into the netboot products. Although the bootimage now knows the storage, the netboot install scripts have to use it. Within the netboot script we check for five different possibilities of storage.

def getPartitionDevicePath(diskDevice = "", partitionNumber = ""):
    # determine if disk.device file is like /dev/cciss/c0d0
    # if this device filename is detected, the partition numbers
    # has to extend with a p: /dev/cciss/c0d0p1
    unixDevicePath = re.compile("c\dd\d").search(disk.device)
    raidDevicePath = re.compile("md\d").search(disk.device)
    nvmeDevicePath = re.compile("nvme\dn\d").search(disk.device)
    mmcDevicePath = re.compile("mmcblk\d").search(disk.device)
    if unixDevicePath:
    # extending PartitionNumber with a starting p
        partitionDevicePath = "%sp%s" % (disk.device, partitionNumber)
    elif raidDevicePath:
    # extending PartitionNumber with a starting p
        partitionDevicePath = "%sp%s" % (disk.device, partitionNumber)
    elif nvmeDevicePath:
    # extending PartitionNumber with a starting p
        partitionDevicePath = "%sp%s" % (disk.device, partitionNumber)
    elif mmcDevicePath:
    # extending PartitionNumber with a starting p
        partitionDevicePath = "%sp%s" % (disk.device, partitionNumber)
    else:
        partitionDevicePath = "%s%s" % (disk.device, partitionNumber)
    return partitionDevicePath

The above function checks of the selected disk device matches four possible patterns. If one of those patterns matches the partition number need to have a p prefix instead of the device itself. Adding the seach for possible eMMC storage makes it possible to install an opsi netboot product on any supported device.

After implementing all of the fixes and building the packages tests were made to confirm a correct behaviour of all changed products. The tests workes successfully and the device is now supported by opsi, along with other eMMC devices.