Last week I’ve been trying to get to grips with two techniques of making apps go faster on Apple’s new M1 chips: using parallel processing from assembly language, and with features in Apple’s rich and extensive Accelerate libraries. Neither has been straightforward, largely because of documentation.

Arm provides copious documentation on features of its processor designs which include detailed accounts of their instruction sets and architecture, often running to thousands of pages in PDFs of 50 MB and more. The big snag with these, other than their sheer volume, is that they are generic across each processor architecture, and none is specific to the cores which Apple has built into its M1 chip.

So finding out exactly what works and what doesn’t is a journey of exploration. Fascinating though it is, it also takes time, a great deal of browsing of PDFs, and experimentation. If you don’t believe me, then read Apple’s terse article and please tell me exactly which of Arm’s reference manuals apply to the cores in the M1. Even Apple shies away from that, providing a link to the top level of Arm’s developer site.

For the vast majority of developers, trying to access the M1 directly is a non-starter, so they look to Apple to facilitate that; in the case of many numeric and related features, those are included in the Accelerate and related libraries. In recent years, Apple has been going out of its way to explain these extensive collections, largely engineered by its Vector & Numerics team.

Members of that team spoke at WWDC in 2018, saying: “Accelerate is easy to use. Most of the time it’s just one function call and the job is done.” The following year they had additional good news: “Accelerate’s libraries are immensely powerful but up until now, their interfaces weren’t that friendly to Swift developers. We’ve looked at four libraries and created new Swift-friendly APIs to make using Accelerate in Swift projects really easy. Please visit our site where we have samples, articles, and extensive reference material that covers the entire Accelerate framework.” They appeared again this year, although their shorter presentation was primarily aimed this time at those using C++.

So I first set off to explore the documentation, as anyone would. From some excellent introductory articles, which whetted my appetite, I decided to look in more detail at several functions, including one which calculates the dot-product of two short vectors. Before you throw your hands up in horror and click on to something more understandable, let me explain that this is little more than basic arithmetic.

For example, if you have two vectors of length 4, containing single-precision floating-point numbers, to calculate their dot-product all you do is multiply the four corresponding pairs of numbers, one from each vector, and add those products together to a total. This may seem dull stuff, but it’s a commonplace requirement, and is highly amenable to processing in parallel.

I therefore opened Xcode’s documentation, found the simd section, and selected the data type I was interested in, Single-Precision Floating-Point Vectors, and this is what I saw.

I’m pleased to report that the current beta version of Xcode does expand on this with an overview, although that is more confusing still as it states that many functions are provided in three variants, the default, a precise variant, and a fast variant. Then it stops dead without listing or detailing any functions at all.

Maybe, as sometimes happens, the function listing was elsewhere in the documentation. So I searched for the dot-vector call which at least appears in an example. But Xcode’s documentation reported No Results.

At this stage, one approach is to type in some code and use Xcode’s autocomplete feature with the letters of the alphabet in order to discover which functions that knows about. It’s tedious, but has got me out of a hole on many occasions now. Instead, I turned to that excellent third-party product Dash, which Apple amazingly kicked out of its App Store a couple of years ago, presumably because it was far too useful.

Dash was no different, and its search also drew a blank. So I really was imagining all this after all.

It was then that I went back and re-read the words of one of those engineers, when he referred to “Please visit our site where we have samples” … I found this site here, and that introductory article, which led me to Apple’s real documentation.

Overlooking the obvious, that what Apple thinks passes for documentation is so minimal as to be embarrassing, why has none of this been incorporated into Xcode? If it’s too expansive to store locally, why doesn’t Xcode link to these online pages?

Having devoted three sessions in recent WWDCs to Accelerate and its relatives like simd, and promised “extensive reference material”, why is Apple not just hiding this light under a bushel, but hiding the bushel too?