Linux/AM4378: Driver documentation

i guess it must be my inexperience in how drivers work in linux that is the root of my issue.

i did find the link you gave me within the SDK documents but with my lack of understanding of how drivers work i didn't really know what to do with it. i'm working on it.

so i guess my question becomes: you guys have to write the drivers for your hardware so the drivers do what you want to do and how you want them to do it. is there any documentation inside the drivers that will show how they are expected to be used? i know the linux community doesn't document much but you guys are in the business of selling products and getting people to develop on those products quickly, and it would be a lot quicker to read a HOW-TO document that somebody took an hour to write than to expect somebody to read the source code and glean some info from interpretation. i get that linux changes pretty frequently but i very much doubt that your GPIO or I2C drivers are fundamentally changing every 77 days.

cobsonchael said:

so i guess my question becomes: you guys have to write the drivers for your hardware so the drivers do what you want to do and how you want them to do it. is there any documentation inside the drivers that will show how they are expected to be used?

It's a bit more complex than this. We write drivers for our SoC where we integrate peripherals and busses. When we put this SoC on a board and connect it to other stuff, we often work with drivers that have been provided by the community or other vendors. For our boards, we validate that these interfaces work for specific use cases that we foresee people wanting to use. Sometimes we have to develop new drivers or make changes to these community drivers, but often we use them as is (i.e. we didn't write them and don't necessarily fully understand how they work with the hardware that they support). This is true of a lot of the ARM code that is provided by ARM and it's partners as well.

So, we have expertise in very specific areas of the Linux that we provide and are happy to try to help there.

I hear your feedback on how-to guides as well. The challenge we face comes back to H/W availability of a given feature like GPIO. You can't write a guide that says how to use a GPIO on TI Linux because you need a specific board that has a pin available, and then what do you connect it to? But, there are GPIOs used by drivers all throughout our offerings that can serve as examples.

In general, Linux goes by the mantra that you have the source, and the source is the documentation. That's how most drivers document, and that is pretty accepted by the community. There is some documentation in the Kernel docs directory that can be very useful as well. This will vary by driver and framework.

I would try to pick a simple interface on your SK and try to understand that from one end to the other. Use the DTS file compatibility field to find the driver code, understand how it is configured into the system by the config, etc.

I sincerely hope this helps. Linux is daunting at first, no doubt. It takes years to develop expertise. But it is also a very powerful and valuable tool.

i appreciate your thoughtful responses and patience. 

RonB said:

I hear your feedback on how-to guides as well. The challenge we face comes back to H/W availability of a given feature like GPIO. You can't write a guide that says how to use a GPIO on TI Linux because you need a specific board that has a pin available, and then what do you connect it to? But, there are GPIOs used by drivers all throughout our offerings that can serve as examples.

except you guys do this all the time with how to's about different EVM boards. there are all sorts of how-to's out in your wiki's about specific boards doing specific things on that board (RTOS documentation has this everywhere, it's pretty common to have to modify code meant for a DSP similar to yours so that you can use it). i do not see how this is any different. i understand it is a lot of work to cover driver how to's (i know you can't do one document for all devices, but maybe 1 example just to get a gist of how i might figure out the basics) and i don't expect the world but i feel like there is some huge gap in learning this stuff. it seems a lot of pages explain things from a basic level (what is a GPIO) and talk about how stuff works up (lines go high, lines go low) to discussing the existing driver/kernal module (the drivers are easy to use so you should be up and running in no time) but almost no information on how to use said driver. it's rare to find a page with concrete examples (and the ones that do tend to have examples from the shell, not in code). it's the same thing over and over again.

i do get the source code is considered the documentation but i don't even know where the source code lives for the drivers. i assume: 

but i didn't see any sitara or AMxxx so where do i look to find the source code for my device?

i would love to use examples given but like i said earlier, the example projects that come with the SDK are almost completely useless unless you are learning Qt. the GPIO examples use REGISTERS! how can you guys get away with that as an example project? there is no way you would suggest to go down to the register level if i asked how do i use GPIOs on the EVM. this is your toggle_led example:

#include <stdint.h>
#include <pru_cfg.h>

volatile register uint32_t __R30;

/*
 * main.c
 */
int main(void)
{
	volatile uint32_t gpo;

	/* GPI Mode 0, GPO Mode 0 */
	CT_CFG.GPCFG0 = 0;

	/* Clear GPO pins */
	gpo = 0x0000;

	while (1) {
		gpo = __R30;
		gpo ^= 0xF;
		__R30 = gpo;
		__delay_cycles(100000000); // half-second delay
	}
}

what am i supposed to do with this?

and after GPIO, i have to start all over again to learn I2C, SPI, NAND, and Audio which looks to be all different. luckily i found a good source to figure out how keyboard scanning works.

sorry if i'm venting too much. i'm just becoming frustrated with the process of constant google searches just to find examples and explanations on how any of this works. either my google-fu sucks or i'm missing some important information that makes this process a lot easier. maybe if i can figure out where source code lives i can make progress.

cobsonchael,

You found our PRU examples, which are designed to be run on the PRU cores as bare metal code. It is certainly not what we would expect you to use in Linux.

Since you have a AM437x SK, let's use that as an example. The main interface to drivers for platform data is called Device Tree. If you don't know about it, I highly recommend watching Device Tree for Dummies which can be found at several sights.

Then, take a look at arch/arm/boot/dts/am437x-sk-evm.dts, which is the Device Tree file (or DTS) for the board you are using. To pick an example, check out the "led" nodes. These are really just fancy GPIOs. Look at the compatible field which should be "gpio-leds". This should eventually lead you to the file drivers/leds/leds-gpios.c which is the driver for this module. That's the source. I usually start by looking at the probe functions which is the function called when the driver starts up.

Part of what the driver will do is create sysfs entries that can be used from user space to interact with the driver. If you have your board booted and a console open, you should be able to look at /sys/class/leds and find entries for the LEDs that you looked at in the DTS file above. You can use the sysfs entries to interact with these LEDs. You could use something similar in your system if you need User Space access, or you could build it into drivers. To find a driver that uses a GPIO, go back to your DTS file and just look around for gpio. You'll quickly find that the leds node uses GPIOs and is one of the simplest examples you could find. Another one can be found in the lcd node as it seems a GPIO is needed to enable the display. Then you could use the compatible field to find the display driver and go look at how it uses a GPIO.

I hope you find this useful.

that is helpful, thank you. i have additional questions:

some background: i started a post to try and get some help with my GPIO drivers which i am hoping i am doing right using sysfs entries:

i am trying to use gpio 16. it was the only gpio listed when i looked in the gpio directory in sys/class. it is supposed to be connected to LED5. when i look at the dts file neither gpio16 nor led5 is listed, neither is gpio5_12 which is the gpio it is connected to. perhaps i should be trying this on a gpio that actually exists in my dts file...so is that a fault with the dts file? if a pin is layed out on the board but not the dts file, does that mean it is automatically disabled until the dts file is fixed? in the datasheet the pin name is gpio5_12 so i think i am looking at the right pin name.

i also noticed that when i went to the "leds" directory in sys/class that it is empty. does that just mean i haven't tried to use it yet? when i use lsmod i do not see anything with gpios or leds. does that mean i have to load the module? EDIT: was looking at the wrong dts file (i think), the file i wanted was the gp_evm file, as that matches up my keyboard gpio pins and has no LEDs listed. however that one doesn't show GPIO16 which is in my sys/class/gpio dir. 

i really appreciate you answering my questions even though the thread is marked as resolved