| .. include:: /substitutions.rst |
| .. _drivers: |
| |
| ======= |
| Drivers |
| ======= |
| |
| Some NuttX boards don't have full support for all the on-chip peripherals. If you need support for this hardware, |
| you will either need to port a driver from another chip, or write one yourself. This section discusses how to do that. |
| |
| .. _drivers-porting: |
| |
| Porting a Driver |
| ================ |
| |
| Often support for on-chip peripherals exists in a closely related chip, or even a different family or from a different |
| manufacturer. Many chips are made up of different Intellectual Property (IP) blocks that are licensed from vendors like |
| Cadence, Synopsys, and others. The IP blocks may be similar enough to use another chip's driver with little |
| modification. |
| |
| * Find a similar driver in NuttX source code: |
| |
| * Look at register names listed in the datasheet for the peripheral. |
| * Search the NuttX codebase for the register names (try several different ones). |
| * Note that you'll have to compare the datasheet to the header and code files to see if there are differences; there |
| will usually be some differences between architectures, and they can be significant. |
| |
| * Find a similar driver in U-Boot, Zephyr or BSD Unix (OpenBSD, FreeBSD, NetBSD) source code: |
| |
| * Only for inspiration, you can't copy code because of license incompatibility and Apache Foundation restrictions. |
| (Apache License 2.0 and BSD code can come in with a software grant agreement from the original authors; this can |
| sometimes be hard to get. Ask on the mailing list if you're unsure.) |
| * But you can debug to see how the driver works. |
| * `U-Boot <https://www.denx.de/wiki/U-Boot>`_ drivers are often easier to understand than BSD Unix drivers because |
| U-Boot is simpler. |
| |
| * Understanding how the driver works |
| |
| Here are a couple of techniques that helped me. |
| |
| * printf debugging |
| |
| * Sprinkle ``custinfo()`` logging statements through your code to see execution paths and look at variables |
| while the code is running. The reason to use ``custinfo()`` as opposed to the other logging shortcuts |
| (``mcinfo()``, etc.) is that you can turn on and off other other logging and still see your custom debug |
| logging. Sometimes it's useful to quiet the flood of logging that comes from a particular debug logging |
| shortcut. |
| * Note that printing info to the console will affect timing. |
| * Keep a file with just your debug settings in it, like this (``debugsettings``): |
| |
| .. code-block:: c |
| |
| CONFIG_DEBUG_CUSTOM_INFO=y |
| (etc..) |
| |
| * Add the settings to the end of your ``.config`` file after running ``make menuconfig`` (that will reorder |
| the file, making it harder to see and change the debug settings if you need to). |
| |
| .. code-block:: bash |
| |
| $ cat .config debugsettings > .config1 ; mv .config1 .config |
| |
| * If you are using interrupts and threads (many things in NuttX run in different threads as a response to interrupts), |
| you can use printf debugging to see overlapping execution. |
| |
| * Interrupts - here's how to inspect the C stack frame to see what execution environment is currently running: |
| |
| .. code-block:: c |
| |
| uint32_t frame = 0; /* MUST be the very first thing in the function */ |
| uint32_t p_frame; |
| frame++; /* make sure that frame doesn't get optimized out */ |
| p_frame = (uint32_t)(&frame); |
| custinfo("p_frame: %08x\n", p_frame); |
| |
| * Threads - here's how to get the thread identifier to see which thread is currently executing: |
| |
| .. code-block:: c |
| |
| pthread_t thread_id = pthread_self(); |
| custinfo("pthread_id: %08x\n", thread_id); |
| |
| * stack frame printf |
| * thread printf |
| |
| * `GDB — the GNU Debugger <https://www.gnu.org/software/gdb/>`_ |
| |
| GDB is a great tool. In this guide we've already used it to load our program and run it. But it can do a lot |
| more. You can single-step through code, examine variables and memory, set breakpoints, and more. I generally use |
| it from the commandline, but have also used it from an IDE like JetBrains' Clion, where it's easier to see the |
| code context. |
| |
| One add-on that I found to be essential is the ability to examine blocks of memory, like buffers that NuttX uses |
| for reading and writing to storage media or network adapters. This `Stack Overflow question on using GDB to |
| examine memory <https://stackoverflow.com/a/54784260/431222>`_ includes a GDB command that is very handy. Add |
| this to your ``.gdbinit`` file, and then use the ``xxd`` command to dump memory in an easy-to-read format: |
| |
| .. code-block:: |
| |
| define xxd |
| if $argc < 2 |
| set $size = sizeof(*$arg0) |
| else |
| set $size = $arg1 |
| end |
| dump binary memory dump.bin $arg0 ((void *)$arg0)+$size |
| eval "shell xxd -o %d dump.bin; rm dump.bin", ((void *)$arg0) |
| end |
| document xxd |
| Dump memory with xxd command (keep the address as offset) |
| |
| xxd addr [size] |
| addr -- expression resolvable as an address |
| size -- size (in byte) of memory to dump |
| sizeof(*addr) is used by default end |
| |
| Here's a short GDB session that shows what this looks like in practice. Note that the memory location being |
| examined (``0x200aa9eo`` here) is a buffer being passed to ``mmcsd_readsingle``: |
| |
| .. code-block:: |
| |
| Program received signal SIGTRAP, Trace/breakpoint trap. |
| 0x200166e8 in up_idle () at common/arm_idle.c:78 |
| 78 } |
| (gdb) b mmcsd_readsingle |
| Breakpoint 1 at 0x2006ea70: file mmcsd/mmcsd_sdio.c, line 1371. |
| (gdb) c |
| Continuing. |
| |
| Breakpoint 1, mmcsd_readsingle (priv=0x200aa8c0, buffer=0x200aa9e0 "WRTEST TXT \030", startblock=2432) at mmcsd/mmcsd_sdio.c:1371 |
| 1371 finfo("startblock=%d\n", startblock); |
| (gdb) xxd 0x200aa9e0 200 |
| 200aa9e0: 5752 5445 5354 2020 5458 5420 1800 0000 WRTEST TXT .... |
| 200aa9f0: 0000 0000 0000 0000 0000 5500 1100 0000 ..........U..... |
| 200aaa00: 5752 5445 5354 3520 5458 5420 1800 0000 WRTEST5 TXT .... |
| 200aaa10: 0000 0000 0000 0000 0000 5800 1500 0000 ..........X..... |
| 200aaa20: e552 5445 5854 3620 5458 5420 1800 0000 .RTEXT6 TXT .... |
| 200aaa30: 0000 0000 0000 0000 0000 5600 1200 0000 ..........V..... |
| 200aaa40: 5752 5445 5354 3620 5458 5420 1800 0000 WRTEST6 TXT .... |
| 200aaa50: 0000 0000 0000 0000 0000 5600 1200 0000 ..........V..... |
| 200aaa60: 0000 0000 0000 0000 0000 0000 0000 0000 ................ |
| 200aaa70: 0000 0000 0000 0000 0000 0000 0000 0000 ................ |
| 200aaa80: 0000 0000 0000 0000 0000 0000 0000 0000 ................ |
| 200aaa90: 0000 0000 0000 0000 0000 0000 0000 0000 ................ |
| 200aaaa0: 0000 0000 0000 0000 ........ |
| |
| NuttX Drivers as a Reference |
| ============================ |
| |
| If you're not porting a NuttX driver from another architecture, it still helps to look at other similar NuttX |
| drivers, if there are any. For instance, when implementing an Ethernet driver, look at other NuttX Ethernet drivers; |
| for an SD Card driver, look at other NuttX SD Card drivers. Even if the chip-specific code won't be the same, the |
| structure to interface with NuttX can be used. |
| |
| Using Chip Datasheets |
| ===================== |
| |
| To port or write a driver, you'll have to be familiar with the information in the chip datasheet. Definitely find |
| the datasheet for your chip, and read the sections relevant to the peripheral you're working with. Doing so ahead |
| of time will save a lot of time later. |
| |
| Another thing that's often helpful is to refer to sample code provided by the manufacturer, or driver code from |
| another operating system (like U-Boot, Zephyr, or FreeBSD) while referring to the datasheet — seeing how working |
| code implements the necessary algorithms often helps one understand how the driver needs to work. |
| |
| * How to use a datasheet |
| |
| Key pieces of information in System-on-a-Chip (SoC) datasheets are usually: |
| |
| * Chip Architecture Diagram — shows how the subsections of the chip (CPU, system bus, peripherals, I/O, etc.) connect |
| to each other. |
| * Memory Map — showing the location of peripheral registers in memory. This info usually goes into a header file. |
| * DMA Engine — if Direct Memory Access (DMA) is used, this may have info on how to use it. |
| * Peripheral — the datasheet usually has a section on how the peripheral works. Key parts of this include: |
| |
| * Registers List — name and offset from the base memory address of the peripheral. This needs to go into a header |
| file. |
| * Register Map — what is the size of each register, and what do the bits mean? You will need to create ``#defines`` |
| in a header file that your code will use to operate on the registers. Refer to other driver header files for |
| examples. |
| |
| Logic Analyzers |
| =============== |
| |
| For drivers that involve input and output (I/O), especially that involve complex protocols like SD Cards, SPI, I2C, |
| etc., actually seeing the waveform that goes in and out the chip's pins is extremely helpful. `Logic Analyzers <https://en.wikipedia.org/wiki/Logic_analyzer>`_ |
| can capture that information and display it graphically, allowing you to see if the driver is doing the right thing |
| on the wire. |
| |
| DMA Debugging |
| ============= |
| |
| * Dump registers before, during, and after transfer. Some NuttX drivers (``sam_sdmmc.c`` or ``imxrt_sdmmc.c`` for |
| example) have built-in code for debugging register states, and can sample registers before, during, and |
| immediately after a DMA transfer, as well as code that can dump the peripheral registers in a nicely-formatted |
| way onto the console device (which can be a serial console, a network console, or memory). Consider using something |
| like this to see what's happening inside the chip if you're trying to debug DMA transfer code. |
| * Compare register settings to expected settings determined from the datasheet or from dumping registers from working |
| code in another operating system (U-Boot, Zephyr, FreeBSD, etc.). |
| * Use the ``xxd`` GDB tool mentioned above to dump NuttX memory buffers before, during, and after a transfer to see if |
| data is being transferred correctly, if there are over- or under-runs, or to diagnose data being stored in incorrect |
| locations. |
| * printf debugging register states can also help here. |
| * Remember that logging can change the timing of any algorithms you might be using, so things may start or stop |
| working when logging is added or removed. Definitely test with logging disabled. |
| |
