Rust Programming Language Oxidize Global 2020, 25 Sep 2020

Previous Meeting Next Meeting

⏯

youtube image

►

From YouTube: Rusty USB Gadgets Make Barking BeagleBones

Description

Making a USB device speak is a pain–Rust with a BeagleBone can have your device barking sooner than expected. Rust users often chant “We can have nice things”–and USB device development with Rust is absolutely nicer.
Each embedded USB stack is unhappy in its own way–a BeagleBone with Rust is standard Linux and all the tools that go with it.

Failures in an embedded USB stack often take down the entire board–Linux USB gadgets run in user space and Rust makes even userspace crashes far less likely. Host software development is hampered by a lack of device hardware and firmware–Rust can make the BeagleBone look like the USB device the host software developers need immediately. Unfortunately, all of this goodness is buried underneath a pile of prerequisite tasks that are neither particularly Rusty nor that well documented.

This talk demonstrates how to cut through the prerequisites and then gets down to the task at hand-decoding and creating USB packets with Rust.

A

So we're happy to introduce uh andrew lenforski, who has actually pre-recorded his talk, so we're uh here to say hi and he'll be answering questions throughout the talk in the chat and uh yeah and then we'll come back together after his talk to answer any of the uh important questions from the chat. So without uh any further ado here is rusty. Usb gadgets make barking beaglebones off and running.

B

A

A

Oh flocky, we don't have any audio right now.

B

A

All right, well we're sorting out some of that audio, we'll be back shortly as soon as we uh as soon as we sort out the.

A

B

B

Greetings fellow oxidizers, and welcome to this session of oxidized global 20 20. future usb gadgets make barking beagle bones.

B

I'm your host andrew lenforski, saying hello, greetings, y'all, I'm actually coming at you from austin texas right now, so I actually get to use that particular contraction, and since this is my first time actually doing videos, I guess I need to do this. Yo yo yo youtube make sure you actually smack that button ring that bell and make and hit those likes and now, presumably, I actually have to give you youtube face.

B

Okay and now that we've got that out of the way we can actually get back to what's going on.

B

What are we actually going to be doing in this session? Well we're going to convert a beaglebone, which is the thing you see here on the left and we're going to convert it into a mouse. This seems like an awful waste of a lot of hardware, and it actually is, but it turns out that this is actually the first step whenever you want to create any form of usb usb hid device inside linux and actually make it work.

B

So who am I I'm? Currently, the vp of engineering for third wave, we're an iot company and we specialize in secured fda cleared systems.

B

I'm an expatriate full custom, vlsi designer now hides behind software, so when everybody says full stack, I laugh a little bit because my full stack goes down to a few orders of magnitude smaller than most people's. I first wrote c on an os9 system, so you know you can tell this beard's getting very gray at some point along the line, I actually became the oldest dude in the room instead of the youngest dude in the room and somehow I didn't seem to pass in between the two states. It just went from one to the other.

B

I guess it's a quantum thing, so I've written some other code which you can go dig through, but we've got a lot of stuff to cover. So I don't want to waste a lot of time on that. Why am I doing this or more particularly? Why would you want to do this? You want to make a usb device generally.

B

This is meant to interconnect some piece of hardware interface to windows and quite often building the usb device code, and linux is way easier than dealing with it in a microcontroller development kit, in particular, in this instance, we're actually building a hidden mouse, which is one of the simplest things, so there's a little bit more boilerplate than actually you would normally give, but in this particular relative to the um functional code, but this actually generally holds the biggest problem when doing this generally is documentation.

B

um The issue is that a lot of this stuff is scattered around in bits and pieces, not all of it presented into a coherent whole and not all of it presented into functions where you can actually work.

B

In this instance, I actually have committed the code to a code repository I put that on the entry slide and you all can dig that down. So if you want to follow along at home, you can. I suspect it's a bit early for most of the folks in in europe right now, so they probably will be following along later. But if you want to download it it's there.

B

In this instance, we have a hidden mouse driver, which is what I'm going to do in this talk, and I've actually got a hid. Generic driver, which does echo systems and that's not actually going to be covered in this talk, because I've only got 20 minutes.

B

So let me give a baseline here, what's actually a beaglebone, when I actually tried giving explaining the concept of this talk to some people. That was actually the first question that they gave me in particular. A bagel bone is a arm-based microcomputer with actual linux os on it. It's an arm. It's one gigahertz, it's got five full mega ram and it does micro, sd storage, a bagel bone black, which is the thing you saw here on. The left actually is about fifty dollars, and the thing on the right is called a pocket beagle.

B

It's actually about 25. Both of these are widely available and both of them have, roughly speaking the same uh the same interfaces. They all have standard you, computer interfaces, the beaglebone black is a little more, it's already pinned out. So, as you can see, it's got ethernet usb host, hdmi micro sd.

B

These things also have standard, embedded interfaces, usb devices, gpios spi and igc, uarts cans, lcds and a bunch of other useful stuff. They also have what are called prus. That's probably a talk for another time. These are a pair of 200 megahertz risk cores that just have some really useful weirdness to them.

B

One of them in particular, is that you can actually load 32 registers between the two pairs between the actual risk microcontrollers in one clock cycle that works really really well, when you want to actually move something from hard real time in the soft real time and then actually even the softer when you're actually moving it down to linux. But that's a talk for another day. We don't have time to go into that second baseline. What's actually a usb hid device, a usb hid device is nominally supposed to be a human interface device.

B

So these are things like keyboards mice, game controllers, foot, pedals stuff, like that. These kind of devices want to be guaranteed to be pulled regularly. So in the case of keyboards, they want to make sure that you pull something like once every millisecond or once every couple of milliseconds. They generally return small amounts of data. In this particular case, 64, bytes or less that's, actually limitation of full speed.

B

If you actually have a high speed device, they can return a lot more data, but we're not going to cover that, and these happen to comply with, what's called the device class definition for the human interface device. These particular mechanisms are actually defined by the usb consortium and actually are something that we actually normally comply with. Usb hid devices. These are standard devices, your everyday, ordinary, wired, keyboard, wired, mouse foot pedals are something people often forget about they're, actually hit device. We'll talk about that a little bit later as well.

B

They present some interesting problems and probably even your your usb keys, the things you use for authentication are a standard, our standard human interface device generally now, there's no particular reason: they're, not exchanging huge amounts of information, so they probably sit there, although some of them may be slightly different.

B

These also are usb hid devices. I know some of people will recognize these especially embedded. These are debug probes so, and this over here is actually an rf attenuator, and this is a usb to ieee 488 gpib converter system.

B

The interesting question here is: these are also human interface devices. So a bit about you're- probably scratching your head, a little bit as to why that these would be considered human interface devices well you're about to scratch your head more. These are also human interface devices. In fact, there's actually 96 of these. This is actually a fixture for accelerated testing that I worked on in the past. These are actually sold to people and actually are in fabrication lines and things like that. Every one of these devices is actually a human interface device.

B

In particular, these are 96, and this go. The entire system actually has a lot and is all driven off of one. In fact, it's probably one of the larger usb hid systems. You've seen it actually has 96 usb devices that presents some interesting problems in an undo itself.

B

Oh the interesting question you're probably asking now is what in the world are you talking about with human interface device and what does that have to do with? What's going on in this particular instance? It's a particular someone call it abuse of the hidden specification, but quite often there were actually very good engineering reasons for this.

B

Back in the old days, we tended to create hid devices for two for two primary reasons. The primary reason was that for many many many years, the only way to actually attach a usb device to windows without actually having to write or install a driver was actually to call it a human interface device. If you could get away with that, you could actually attach a thing directly to windows, and then you could start attaching it with via various windows.

B

Calls in particular, a lot of things were written in visual basic six, which is probably too old for some of you, maybe even a lot of you who are watching this talk, but because that's circa 1996, but that was the way it was back. Then a secondary reason was that um usb end points were minimized. When you were using hid devices, so you really only needed you.

B

You only needed two end points when you were doing this besides, normally your end point zero, and that was a minimum back when ram usage was a big deal that really mattered. So some of these usb devices were built usb full speed. I don't think I've ever seen anything below that, but these were running on devices that had maybe up to a couple kilobytes of ram and maybe 32k of flash. This obviously isn't a particular consideration now, but that does actually. That was why a lot of these were chosen and especially when they rolled forward.

B

So one of the questions you need to ask is: why would you want to implement a new hid device? um One of the things is, you might actually need an actual hid. Human interface device in one particular instance that I bumped into I needed multiple foot pedals. These foot pedals that you saw earlier, don't tend to cooperate very nicely whenever they're plugged into multiple systems, so if you can actually concentrate them into a usb into a usb hub and then use a hid device to actually pull all the things together, that's fine!

B

In addition, quite often if you want to use the foot pedal for something like a control, a control key or a modifier key, not all operating systems will actually allow you to do that directly where they can combine a modifier on one usb device and a key pressed on another device like a keyboard.

B

A second reason why you might want to implement a do a human interface device is, you may actually have new armor that just you want to get your software development team up and running immediately.

B

A lot of stuff can be faked on these particular mechanisms, and you know to be perfectly honest, you can actually implement a lot of stuff in a linux computer. You can also upgrade usb full speed to high speed. Most microcontrollers are still running at full speed. They haven't. There are a few that have made the jump to high speed. They tend to be more expensive, whereas most of the linux computers all run at least at high speed.

B

In addition, usbc is just not on the map for microcontrollers, whereas a lot of the unix linux systems are actually running. Usbc they're a little bit more expensive, but they're actually have usbc today, including all the bandwidth that goes along with that. You may also want to be adding features to a domain specific device that uses hid in my instance. That was the actual reason why I wanted to do this. In particular, I had some issues with debug probes.

B

We were using them in very high volume mechanisms as well as we wanted to do certain things like add encryption, keys and install install as well as check the device. At the same time, you may also have a legacy thing. One of the things that you saw earlier was the fact that we actually had a ieee 488 interface. That's called gpib.

B

That standard goes the way back to the 70s, but still a lot of lab equipment uses it especially things like spectrum, analyzers and vector network analyzers, which are fairly expensive pieces of rf equipment.

B

So the real question here is: how do we create a hit on linux in this particular instance? The first thing we need to do is we need to take over the gadget system, because we don't do that. What happened? You know the beaglebones actually make use of the gadget system themselves. So when you plug them directly into your usb device or your usb hub or your usb computer, they automatically come up as a ethernet device. In fact, they come with two different ethernet devices, one for linux, one for windows.

B

We can talk about that, that's something for much later, and so we need to take care of that. The next thing you do is you need to actually set up the usb gadget on linux, using the config fs. If you use the config fs, you actually have to do some fairly magical things, they're straightforward.

B

Not all of them are duplicate. Not all of them are documented. Sorry and several of them are gener generally when they are documented they're in pieces. So this actually gives you a full. I will give you a full script. It's in the code base where you get all the pieces you need in order to actually bring that descriptor up and running. Finally, you need to attach to the created character device, and then you read and write the usb reports in this particular instance.

B

We're going to be using rust, but you don't actually have to be using rust. That's not a requirement here. Linux takes over some of the heavy lifting, so it actually avoids having to be required to do it in fast real time. So you could even use c in python we're going to use rust. We have to use epoll, that's kind of annoying, but we're going to do that because it actually works, and you need to see what's going on a lot of the rust libraries wrap that and they swallow it and they do weird things.

B

So we need to use it directly, which means we're going to call it c and after that, it's alive. So let's see how we're going to do this. Let's start looking at what's going on here. So the first thing I said is that we need to grab a hold of actual.

B

We need to grab a hold of the usb device and we need to grab all the gadget system in order to actually do what we need to do here.

B

In this instance,.

B

This system actually.

B

What we're doing is we're actually taking down what's called the composite system.

B

And this is actually specific to the beaglebone black or it's actually specific to the beaglebone family is probably a better description of it. In this particular instance, a lot of what we're doing here certainly also can be used.

B

With a raspberry pi, there's nothing stopping you from doing this.

B

The gadget subsystem is the same, and now, let's reboot that beaglebone, while we're talking about that, so there's actually nothing which is which is stopping you from using this on a raspberry pi and it doesn't matter what linux system you're on the gadget system works the same way so I've already cloned my repository in here, so we've got a barking beaglebone system and we're going to go down into the hit generic, sorry, the hidden mouse, because that's what we're actually doing in this particular instance and we're going to take a quick look at the actual script that does this in order so that we can see what's going on in this particular instance, the script starts off with I go to the top, where we actually tell the linux kernel that we actually need to use a lib composite system, and this actually pulls in the requisite modules that go along with that.

B

We actually then go into the config fs space of the confirm of the kernel, which is where we're going to actually have to put our usb gadget.

B

um We make our own directory in here to actually hold what's going on, and then we see into it you, I there's no point in me being redundant about that we're going to define some variables. These variables are then going to get picked up by the gadget driver in order to actually fill out usb reports when it actually needs it.

B

This is a particularly interesting problem. In that what will happen is linux will intercept most of the calls, and so the only thing we have to do in re. The only thing we have to deal with are the actual reports. All the things like knacks stalls, um unplug events, replug events will be handled by linux. We're gonna. This tells us we're using the two usb 2.0 specification or later vendor is normally issued by. This is a code that will be issued by the usb consortium. If you actually need that this is a product id.

B

If we actually need that as to where we're going with that, we define that as well as the version in this instance again, some other strings. So when we actually these are these are generally by convention. They exist and we can actually create a a configuration descriptor. The most important piece here is actually how much power we request. If you request too much power, you can't request more than 500 milliamps, but if you request too much power, it may refuse to actually connect you when it doesn't.

B

After here, we actually start doing some things. These actually call into the linux driver, so be careful as you start making these, as you start creating uh directories and echoing commands, you actually start winding up, causing things to go on inside the linux kernel itself. The module's actually executing at that point. This calls alec instance, which starts allocating memory. This sets up the protocol in this particular instance. Protocol is defined by the usb consortium. This is a mouse subclass.

B

This is normally zero, but in this instance the mouse mice can be used during boots and they have a boot interface and, in this instance, we're claiming that our maximum report length is eight bytes. This enables us to use all very old, full speed or even slow speed usbs, because this minimizes the size, this magic block of hexadecimal numbers is, of course gobbledygook. You really can't understand it in this particular instance, it's actually copied directly from the usb consortium, because it's a mouse. They often provide you with these kinds of helpful things.

B

This actually is a full description of what your usb descriptor should look like of what your report looks like you're going to be sending this and this when you, your host, the computer will actually request this from you, and this is a description of hey. This is what I'm going to send you when you actually ask me to send you something you can unpack it, there's actually a very nice online tool for unpacking it, I'm not going to go into a lot of redundancy about that. You can look at it yourself in particular.

B

Things note about this is the fact that we have a report so, and we report count of three and a report size of one that's bits. So these are the buttons so we're sending three bits for buttons, and then we have a report kind of one of size. So those are five extra bits, that's packing, because now we actually have a full byte in the report, and it says we have usage for x and y of the mouse.

B

In this instance, it's assigned a bit number so we're actually telling it that it's actually minus 127 to 127. the report. Size is eight bits and we've got two of them, so we've got an x and we've got a y and that closes it. At this point, you've got the you've got. The configuration descriptor is in place when you actually link this up. It actually calls allocate in the kernel module which starts bringing the usb subsystem online, actually linking to the udis udc actually calls bind, and at that point dev hit. G0 now exists.

B

You can actually plug the cable into the into your usb host and it will actually recognize it as a mouse we're not doing anything yet because we haven't actually attached anything to catch, to drive and eat reports. But that's coming at this point. You can actually look at it, it's being pulled and it's sending back what are called maps so in this instance, I'm going to actually run this script and that's actually going to set us up.

B

Oh, oh, it would actually help if I, instead of trying to do that on my on my mechanism here, I actually did that on the device itself jingle bone. This is on the bagel bone mouse.

B

And that's actually now ready to go so at this point we switch over to the rust part of the world and.

B

We're now sitting inside visual studio code, which is actually running stuff on our on our mechanisms here. So one of the first things to do is that we go down in here. Everything is in a main rs I'll actually get down in here, so we can actually see that there is actually a hidden mouse rust and if we actually run this directly.

B

Our cursor actually starts jumping back and forth, so we'll get back to that, um but so, what's going on inside the rust, we actually steal a macro call directly from tokyo in this instance. This is very useful, because this allows us to go down into lib c and it actually wraps that the result of lib c, which is a little screw ball because of errors. It allows us to wrap this and return directly into the rust results for error, which is very useful rather than having to write this boiler plate every single time.

B

We need to hit lib c. We go down into main. This is some basic stuff for logging, so that we can actually enable that standard, open, open um idioms, uh where we actually have to chain back together in order to make everything work, um not not still not a big fan of this really would prefer that must finally get keyword, arguments to make life better.

B

um We can, in this particular instance we're switching that device into what's called non-blocking mode. So when we read or write to it, if something happens where it can't complete immediately, we want it to come back. We don't want to wait for forever. Well, you know we don't want to write something to the usb and have it sit there and wait for error, because we unplugged the device that doesn't that's just kind of silly.

B

um We set up our we're starting to set up our epoll infrastructure, we're calling epoll on linux, which is kind of annoying. This is the main main mechanism building block on linux. That allows you to actually say I'm waiting on a file descriptor and when something comes in on that file, descriptor, please wake me up. Otherwise, I'm going to stay asleep.

B

Yet more boilerplate. This we're actually saying what events we want to watch. We want to watch a poll in, and a poll out pull in is actually a read event. Pull out is a write event in this particular instance. Read events aren't what we're actually working against um we're only doing right events because we're a mouse we just send stuff if you're, actually doing more advanced hid mechanisms and more advanced hid. Drivers, like the echo driver that I have e-pull in now, matters in this instance we're adding it and say telling linux hey.

B

We really want you to pay attention to that file. Descriptor get ready for it with epoll.

B

We're actually keeping track of time in this particular instance, because we want to bounce our cursor back and forth, depending upon which second, you know whether we're on an even or an odd second, whether we want it to go up into the left or down into the right. In this particular instance, we've got an e pull, we'll empty it out, and then the first thing we do is we actually ask e paul, wait and say: hey?

B

Can you give us an event we're going to hang out for for, however, many timeout millies, which is 1000 milliseconds, so one second and we're going? We want you to get one event. If we don't get any events and it actually returns, we actually wound up with a timeout in this particular instance, and if we wound up with a timeout, then we can write through it and that mechanism says okay, we want to write a report in this instance. The report, again, as I said, is three bytes: that's our buttons.

B

We don't have any buttons to push. This is minus 16. This is minus 16, x, n, minus 16 y or depending upon. If it's an even it's no buttons to push positive 16 x, positive 16 y, so we bounce back and forth. We write the report. If the report goes through, it should always go through. If we actually are capable of running the port. We should always write three bytes of the report itself. If that fails, something went very wrong. We're going to just die in this instance.

B

The other thing that can happen is we can get an error. In this instance, woodblock becomes the error because we're unplugged. So when we try and write something to it, it just goes into goes into the ether. In this instance, we want to re we're name, re-enabling, a write event. Sorry about the pop-ups right analyzer can be a little annoying about that.

B

We're re-enabling the write system as we need that event we'll talk about why we need to re-enable it a little bit and then we actually tell the linux system that we've re-enabled it and please look for read and write in this particular instance. If we get an unknown error, we just kick it upstairs. If we can't write it all we're unplugged, all we can do is hang out if we do get an epoll event.

B

What's going on, we first check to see that the file descriptor is the same as we gave it, which means that we didn't get some weird screwball thing due to e-pull, which we won't discuss can happen, but as long as you're single-threaded, this shouldn't happen, and this is all single-threaded, um then we're actually looking for whether or not this was a right event, in which point we found the right event we can. That means somebody plugged us back in. We can actually start writing again and then we disable the right events coming back from ebol.

B

The reason for that is, we will keep getting spammed with right right events as long as we we can actually write to that file descriptor and that file descriptor is is pretty much empty all the time. In this instance, we can actually hit the e poll. We can return the event struct if we get a read somebody attempted to read from us and that just doesn't work very well.

B

So in that instance that covers all the bus code that we're doing so now, if I go back into the ubuntu, you can actually see that when I actually connect and run via that, my cursor starts jumping back and forth, so we've actually managed to create a fake mouse using a bigger bone using rust and using the linux usb subsystem, and we did it about 25 minutes.

B

So what I want to say is thanks a lot for attending. um I know that was sort of a that was sort of a whirlwind scene of how to do usb hid devices. I'll probably make a talk later at some point where I actually make this work for a much much uh larger hid device. Where I talk about how to do this with a debug pro anyway, thanks you all for attending, and I much appreciate your attention. Good luck and enjoy the rest of oxidized 20 20. have a good.

B