Alice's Datasheets

Introduction

This is a parody of Alice’s Restaurant by Arlo Guthrie, a satirical comedy protest song against the Vietnam War draft. In the 1980s, it became an Usenet meme, and many versions have been written to comment various events in tech. The most classic one was Rob Austein’s Alice’s PDP-10 on the tragic demise of the PDP-10 and MIT ITS. Others include Alice’s NNTP server on the discontent on Usenet news filtering.

My version was inspired by all of them, and is substantially based on Alice’s NNTP Server. It was written after my frustrating experience of working with some chips which their datasheets are secret.

If you’re confused, consider to check the original song (warning: occasional explicit languages and slurs) and its Wikipedia page (linked above), but only after you’ve finished reading this article - it’s really long.

Alice’s Datasheets

This song is called “Alice’s Datasheets” and it’s about Alice, and the datasheet, but “Alice’s Datasheets” is not the name of the datasheet, that’s just the name of the song, and that’s why I called this song “Alice’s Datasheets.”

🎡 You can get anything you want, in Alice’s datasheets.
🎡 You can get anything you want, in Alice’s datasheets.
🎡 Wget over, it’s a simple script,
🎡 And find the bitflags in the register map.
🎡 You can get anything you want in Alice’s datasheets!

You see, it all started about two generations of proprietary microcontrollers ago, on a Tuesday, when my about-to-graduate friend and I went up to read some datasheets at Alice’s lab. ‘cause the vendor didn’t give them to us, it sent them to Alice’s lab, with lots of chips, schematics, eval boards, and of course the datasheets themselves.

Anyways, it was a nice lab, and the University’s budget was big, and Alice had the equipment with sufficient bandwidth and she figured she didn’t have to worry about USB 3.1 or PCIe testing for a long time.

We got up there, found all the datasheets, and we figured it’d be a friendly gesture for us to take the datasheets and distribute ‘em around to other people at the University who work on the same free and open source project that also didn’t get the documentation, ‘cause that’s what datasheets were supposed to be all about in the first place, right?

So we took about several megabytes of documentation and stuck it on a spare directory which we were gonna push into our server, and we got ourselves educated on Git. We git init the repository and git add and git commit the changes. Well, when we tried to push the repository to the server there was a big message in our console saying “Repository creation closed for end-of-semester”. We’d never heard of a Git server that was closed at the end of the semester before, and with tears in our eyes we logged off into the sunset, looking to find another place to stash the docs.

We didn’t find one until we came to an old public FTP server, and off the side of the 6.111/projects/datasheets/ directory, we noticed there were datasheets from some old projects. And we figured that one big pile of datasheets is better than two little piles, and rather than creating a new account and a new directory for the project members, we decided to just put our several megabytes docs at here.

That’s what we did, and SSH’ed back to Alice’s, had an end-of-semester hackathon that couldn’t be beat, went to sleep and didn’t get up until next morning, when we got a phone call from the University Director of Computer Security. Said “Kid, someone found your username on a file related to an unauthorized information disclosure incident, on an FTP server that wasn’t logged into by anybody the night before, and I just wanted to know if you had any information ‘bout it…”

Who knew those datasheets were under NDA? I had to say “Yes sir, Mister Director, I cannot tell a lie, I used chown on that file on the FTP…”

After speaking to the Director for about forty-five minutes on the telephone we finally came to the truth of the matter and he said that we had to go down and remove the datasheets, and also had to go down and speak to him at the Undergraduate Office, and bring all our wget(1), rsync(1), ssh(1), FTP client, PDF reader, and other “hacking tools” involved with us, and so we did.

Now friends, there was only one or two things the University Director of Computer Security coulda’ done at the Undergraduate Office and the first was he could have given us a medal for being so brave and honest on the telephone, which wasn’t very likely, and we didn’t expect it, and the other thing he could have done was bawled us out and told us never to be seen sharing files and uploading ‘em to the server in his vicinity again, which is what we expected, but when we got to the Undergraduate Office there was a third possibility that we hadn’t counted upon, and we was both immediately arrested and handcuffed, and I said “Hey, Director, I don’t think I can rm the datasheets with these handcuffs on”, and he said “Shaddap kid, and follow me”.

And that’s what we did, walked right behind him and walked to the quote “Scene-of-the-Crime” unquote. I want to tell you about this machine room of University where all computing is happening. They got a 40 Gb/s Ethernet line here, so there’s no throttling on the network, but they got one System Administrator, and of course, the Director of Computer Security, but when we got to the “Scene-of-the-Crime” there was the System Administrator, five Special Interest Group Representatives with five lawyers each, and three TAs acting as Assistant System Administrators, this being the biggest incident of the last five years, and everybody wanted to get in the school report on it because it had something to do with a Chinese foreign student and disclosure of information of American tech companies and everyone outside the EE/CS department knew that all they had to do was to spell “cyber” and “hacker” correctly in order to get a cushy job writing trade war columns for the local news.

And they was makin’ the System Administrator use up all kinds of audit tools they had hanging around the machine rooms. They was greppin’ files, following FTP and wtmp logs, tracing NetFlow data, and mirroring the disk, and they eventually came up with a .pcap file, and they exported it to a 27-page PDF, and put circles and arrows and highlights on ‘em and annotations on the bottom of each page explaining what each one was to be used as evidence against us. They took archives of the approach, the getaway, the activity in our home directories and /var/log/wtmp, and the FTP directories, and I already mentioned the file grepping.

After the ordeal, we went back to our residences. The Director of Student Security said he was going to keep us under supervision and said “Kid, I’m going to take away your system access, but you can have your restricted account back if you’ll give me the username and password for it first”.

I said “Director, I can understand you wanting my username so’s you can create a restricted user for me, but why do you want my password?”

And he said “Kid, we don’t want you exploiting the public-key authentication system with a deliberately crafted X.509 ECC certificate and taking over the server via a buffer overflow or an invalid curve attack.”

And I said “Director, did you think I have so much knowledge on elliptic curve cryptography and was going to compromise the school server just to upload a datasheet?”

The Director said he was making sure, and friends, the Director was, ‘cause he disabled all my old Kerberos, X.509, SSH, Samba, and web credentials. and he even blocked my access to the system C compiler and bind-mounted my home directory with noexec, just in case.

The Director was making sure, and it was about four or five hours later that Alice (remember Alice? This is a song about Alice), Alice came by and with a few nasty words to the Director, bailed us out of our restricted accounts, had another session of hackathon that couldn’t be beat, and didn’t get up until the next morning, when we all had to go to the Student Disciplinary Tribunal.

We walked in, sat down, and the Director of Computer Security came in with the 27-page PCAP log with the circles and arrows and some annotations on the bottom of each page, sat down. Man came in said “all rise”. We stood up, and the Director stood up with the 27-page PCAP log and the judge walked in, sat down in front of a laptop with SPICE and HFSS running in the background, and he sat down, and we sat down.

The Director looked at the laptop with SPICE and HFSS running in the background… and then at the 27-page PCAP log with circles and arrows and some annotations on the bottom of each page… and looked at the laptop with SPICE and HFSS running in the background… and then at the 27-page PCAP log with circles and arrows and some annotations on the bottom of each page… and began to cry.

‘Cause the Director had come to the realization that the judge made a career on analog RF amplifier design and there wasn’t nothing he could do about it, and the judge wasn’t going to look at or understand the 27-page PCAP log with the circles and arrows and some annotations on the bottom of each one explaining what each one was to be used as evidence against us.

And we were given a few lines on our transcripts and had to delete all copies of datasheets outside the lab the next morning, but that’s not what I came to tell you about.


Came to talk about Non-Disclosure Agreement (NDA).

We got a company up here, which I won’t name publicly, and among other things, one of the things they do is take the full documentation and select it, inspect it, detect it, neglect it, reject it, and then inject a few selected pages to the company website, call it “Summary Datasheet” for independent developers to read. I went down and got my job application papers, and I walked in wearing a suit-and-tie so I looked and felt my best when I went in that morning.

‘Cause I wanted to look like the company-loyal kid from university, man I wanted to feel like the company-loyal kid from university, man I wanted to BE the company-loyal kid from university, and I walked in and I was hung down, brung down, hung up, and all kinds of mean nasty ugly things. And I walked in and sat down and they gave me a piece of paper, said “Kid, do the oral personality profile test with the counseling psychologist in Room 101”.

I went up there, I said, “Shrink, I want to work. I want to work! I don’t mind the 996 working hour system ‘cause it’ll all help me to WORK!” And I started jumpin’ up and down, yellin’ “WORK! WORK!” and he started Jumpin’ up and down with me, and we was both jumpin’ up and down, yellin’ “Work! Work! Work! Work!” and the sergeant came over, pinned a medal on me, sent me down the hall, said “You’re our boy”.

Didn’t feel too good about it.

Proceeded on down the hall gettin’ all sorts of technical and political injections, inspections, detections, neglections and all kinds of stuff that they was doin’ to me at the thing there, and I was interviewed two hours, three hours, four hours. I was there for a long time going through all kinds of mean nasty ugly things and I was just having a tough time there and they was inspecting and injecting every single part of my mindset to see whether I’m going to be loyal enough to the company, and they was leaving no part untouched. Proceeded through. And when I finally came to see the last man, the Head of Intellectual Property. I walked in, sat down, and said “what do you want?”

“Kid, we only got one question. Have you ever violated any Intellectual Property policies?”

And I proceeded to tell him the story of the Alice’s Datasheet NDA violation incident, with full orchestration and five-part harmony and stuff like that and suddenly he stopped me right there and said “Kid, did you ever have that written up on your transcript?”

I proceeded to tell him the story of the 27-page archived PCAP log with the circles and arrows and annotations on the bottom of each page, and he stopped me right there and said “Kid, I want you to go and sit down on that bench that says group H… NOW, KID!”

And I walked over to the bench there, and there’s group H, which is where they put you if you may not be moral enough to join the company after committing your special violation of company policies, and there was all kinds of mean nasty ugly-looking people on the bench there.

Web scrapers. Software crackers. Linux kernel hackers. Sci-Hub users. Chip decappers! OpenBSD driver subsystem maintainer! OpenBSD driver subsystem maintainer sitting right there on the bench next to me! And there was other mean and nasty and ugly and horrible hacker-type guys sitting on the bench next to me.

And the meanest, ugliest, nastiest one, the meanest software crackers of them all was comin' over to me, and he was mean and ugly and nasty and horrible and all kinds of things, and he sat down next to me, said “Kid, what’d ya get?”

I said “I didn’t get nothing, they put a line on my transcript and made me delete the unauthorized files.” He said “What were you busted for?”, and I said “file sharing.” And they all moved away from me on the bench there, and a hairy eyeball and all kinds of mean nasty things.

Until I said “to disclose and distribute datasheets under multiple NDAs to developers working on a free and open source firmware project.” They all came back, shook my hand, and we had a great time on the bench talking about hacking, static binary analysis, fault injection, Mask ROM reading under a microscope, all kinds of groovy things that we was talking about on the bench. And everything was fine, we were sharing undocumented silicon bugs and all kinds of things, until the Head of Intellectual Property came over, had some paper in his hand, and said…

“Kids, this-survey-got-47-words-37-sentences-58-lines-we-wanna-know-details-of-the-hack-time-of-the-hack-all-the-things-you-gotta-say-things-about-the-hack-what-datasheet-you-was-reading-at-the-time-the-serial-number-of-the-datasheet-and-your-social-media-account-github-profile-and-ID-card-and-all-the-things-you-gotta-say”,

and talked for forty-five minutes and nobody understood a word that he said, but we had fun filling out the form and playing the dinosaur game in the Chrome web browser there, and I filled out the details of the Alice’s Datasheet NDA with the four part harmony, wrote it down there, just like it was, and I pressed ENTER, and the screen cleared, and I saw the rest of the form.

In the middle of the screen…

Away from everything else on the screen…

In parentheses…

Capital letters…

Quotated…

Read the following words.

“HAVE YOU REHABILITATED YOURSELF (Y/n)?”

I went over to the manager, said “Manager, you got a lotta damn gall to ask me if I’ve rehabilitated myself, I mean, I mean, I’m just sittin' here, sittin' on the group H bench ‘cause you want to know if I’m moral enough to join a Company that first classified crucial datasheets behind NDAs, and after made the hardware unusable for free and open source projects, started sending Cease-and-Desist letters to hackers who work on reverse enginnering in order to write free firmware and kernel drivers, which is explicitly allowed by the U.S. copyright laws?!” He looked at me, said β€œKid, we don’t like your kind, and we’re gonna send a copy of your social media profile, your GitHub profile and your ID card down to company HQ archive…”

And friends, somewhere in the Company HQ, enshrined in some little directory, is a deep-learning dataset in ones and zeroes of my profiles. And the only reason I’m singin’ you this song is ‘cause you may know somebody in a similar situation, or YOU may be in a similar situation, and if you’re in a situation like that, there’s only one thing you can do and that’s seeing a sales representative of the chip company in question on phone or Zoom, and sing, “You can get anything you want in Alice’s Datasheets.” And hang up.

Or at least send an E-mail to their tech support and CC the marketing department.

You know, if one person, just one person does it, they may think it’s just a spam and won’t take it. And if two people, two people do it, in harmony, they may think they’re both OpenBSD hackers and they won’t touch either of them. And if three people do it! Can you imagine three people mailing or calling up, singin’ a bar of “Alice’s Datasheets” and hanging up? They may think it’s the hacker known as 4Chan!

And can you imagine fifty people a day? I said FIFTY people a day loggin' in, mailing or singin' a bar of “Alice’s Datasheets” and loggin' out? Friends, they may think it’s a Movement, and that’s what it is! The Alice’s Datasheet Anti-NDA Movement! And all you gotta do to join is to sing it the next time it comes around on the guitar.

With feeling.

So we’ll wait for it to come around on the guitar, here and sing it when it does.

Here it comes.

🎡 You can get anything you want, in Alice’s datasheets.
🎡 You can get anything you want, in Alice’s datasheets.
🎡 Wget over, it’s a simple script,
🎡 and find the bitflags in the register map.
🎡 You can get anything you want in Alice’s datasheets!

That was horrible. If you want to end datasheet NDA and stuff you got to sing loud…

I’ve been writin' this song now for twenty-five minutes and over three hundred and twenty lines of text. I could write it for another twenty-five minutes and another three hundred and twenty lines – I’m not proud…

…or tired.

So we’ll wait till it comes around again, and this time with four part harmony and feeling. We’re just waitin' for it to come around is what we’re doing.

All right now…

🎡 You can get anything you want in Alice’s datasheets.
🎡 (Excepting Alice~)
🎡 You can get anything you want in Alice’s datasheets.
🎡 (So~) wget over, it’s a simple script,
🎡 And find the bitflags in the register map.
🎡 You can get anything you want in Alice’s datasheets!

🎡 Da Da Da Da Da Da Da Da,
🎡 in Alice’s Datasheets!

END.

Postscript

For a more serious summary of the datasheet situation, The OpenBSD project has something to say. It was written in 2005, although the specific details are outdated, such as the chipsets and companies involved, nevertheless, the general datasheet situation in the hardware industry as described in the quote below is still accurate.

OpenBSD also criticized some Linux vendors for writing GPL’d device drivers only, without (or intentionally not) demanding the vendor to release the datasheets. Since a working device driver usually contains inadequate information for understanding how the hardware really works, OpenBSD is unable to reimplement the driver under the ISC license. OpenBSD believes a device driver developed under NDA also “gives you privileged information which your fellow developers cannot access. This makes effective peer review of your code impossible and breaks our community’s process.”

A personal example: with the help of a datasheet, I was able to successfully fix several crucial bugs in a 2D video driver and merge my patches into the Linux kernel in spite of the fact that it’s 20-year-old 2D video card that nobody uses. In an alternative timeline without that datasheet, such a task is simply impossible. The driver merely stores all the register values in an array and initializes the hardware in a for loop, there’s no information about the functions or purposes of these registers. By reading the source code, you cannot even learn the name of a register.

I’m convinced that it’s in the crucial interest of free and open source developers and users to demand full datasheets regardless of the license of the device driver. A device driver under a free license for hardware without public documentation is only free from a copyright perspective, but it’s still technically encumbered, and it’s harmful to digital freedom.

OpenBSD says:

For an operating system to get anywhere in “the market” it must have good device support.

Ethernet was our first concern. Many vendors refused to supply programmers with programming documentation for these chipsets. Donald Becker (Linux) and Bill Paul (FreeBSD) changed the rules of the game here: They wrote drivers for the chipsets that they could get documentation for, and as they succeeded in writing more and more drivers, eventually closed vendors slowly opened up until most ethernet chipset documentation was available. Today, some vendors still resist releasing ethernet chipset documentation (ie. Broadcom, Intel, Marvell/SysKonnect, NVIDIA) but the driver problem is mostly solved in the ethernet market.

Similar problems have happened in the SCSI, IDE, and RAID markets. Again, the problem was solved by writing drivers for documented devices first. If the free software user communities use those drivers preferentially, it is a market loss for the secretive vendors. Another approach that has worked is to publish email addresses and phone numbers for the marketing department managers in these companies. These email campaigns have worked almost every time.

The new frontier: 802.11 wireless chipsets.

Over the last six months, this came to a head in the OpenBSD project. We asked our users to help us petition numerous vendors so that we could get chipset documentation or redistributable firmware. Certainly, we did not succeed for some vendors. But we did influence some vendors, in particular the Taiwanese (Ralink and Realtek), who have given us everything we need. We also reverse engineered the Atheros chipsets.

Want to help us? Avoid Intel Centrino, Broadcom, TI, or Connexant PrismGT chipsets. Heck, avoid buying even regular old pre-G Prism products, to send a message. If you can, buy 802.11 products using chips by Realtek, Ralink, Atmel, ADMTek, Atheros. Our manual pages attempt to explain which vendors (ie. D-Link) box which chipsets into which product.

Send a message that open support for hardware matters. A vendor in Redmond largely continues their practices because they get the chipset documentation years before everyone else does. What really upsets us the most is that some Linux vendors are signing Non-Disclosure Agreements with vendors, or contracts that let them distribute firmwares. Meanwhile both Linux and FSF head developers are not asking their communities to help us in our efforts to free development information for all, but are even going further and telling their development communities to not work with us at pressuring vendors. It is ridiculous.