Writing a Minidriver

This chapter includes:

• Timing requirements
• Data storage
• Handler function
• Customizing the startup program to include your minidriver
• Making the transition to a full driver
• Making a boot image that includes your minidriver

In order to write a minidriver, you must first decide on the following:

• the hardware platform you'll work with
• the timing requirements of your driver
• how much data storage (if any) the minidriver needs
• whether or not your minidriver needs to initialize the hardware
• whether or not your minidriver requires hardware access
• how the transition to the full driver is to be accomplished

The BSP associated with your hardware platform includes the source code to the board's startup program. You must link your minidriver to this program. For more information, see the BSP documentation, as well as Building Embedded Systems.

You'll need to modify these files:

• mdriver_max.c — defines the amount of data copied from flash to RAM between calls to your minidriver
• main.c — where you'll set up the minidriver's data area and register your handler
• my_mdriver.c — contains your handler function; choose an appropriate name for this file. You can have multiple C and header files as part of your minidriver.

Don't modify the following files unless you're directed to do so by QNX Software Systems, but make sure they're included in your startup code directory:

• cpu_mdriver.c
• mdriver.c

Timing requirements

Since the minidriver code is polled during the startup and kernel-initialization phases of the boot process, you need to know the timing of your device in order to verify if the poll rate is fast enough. Most of the time in startup is spent copying the boot image from flash to RAM, and the minidriver is polled during this time period. The sequence might look like this:

• Call the minidriver.
• Copy the next 16 KB.
• Call the minidriver.
• Copy the next 16 KB.
• ...

The startup library contains a global variable mdriver_max, which is the amount of data (in bytes) that's copied from flash to RAM between calls to your minidriver. This variable is defined in mdriver_max.c, and its default value is 16 KB.

You might have to experiment to determine the best value, based on the timing requirements of your device, processor speed, and the flash.

In order to change this value, you can:

• Copy mdriver_max.c to your specific board directory and then set the value. Be sure to recompile the libstartup.a library and relink your startup code with this new library.

  or:

• Set the value in your startup's main() before you register the minidriver handler.

Data storage

The minidriver program usually requires a space to store the received hardware data and any other information that the full driver will later need at process time. You need to determine the amount of data you require and allocate the memory.

As we'll see, you allocate the data area in the startup's main() function and provide the area's physical address when you register the handler function. When the handler is invoked, it's passed the area's virtual address.

---

This area of memory isn't internally managed by the system; it's your driver's responsibility to avoid overwriting system memory. If your handler function writes outside of its data area, a system failure could occur, and the operating system might not boot.

---

Handler function

The prototype of the minidriver handler function is:

int my_handler (int state, void *data);

The arguments are:

state

Indicates when the handler is being called. It can have one of the following values, defined in <sys/syspage.h>, and presented here in chronological order:

• MDRIVER_INIT: The driver is being initialized. The handler is called with this state only once, when you register the handler by calling mdriver_add().
• MDRIVER_STARTUP: The driver is being called from somewhere in startup.
• MDRIVER_STARTUP_PREPARE: Preparations must take place for minidriver operation outside the startup environment.
• MDRIVER_STARTUP_FINI: The last call to the driver from within the startup.
• MDRIVER_KERNEL: The driver is being called during kernel initialization.
• MDRIVER_PROCESS: The driver is being called during process manager/system initialization.
• MDRIVER_INTR_ATTACH: A process is calling InterruptAttach() or InterruptAttachEvent() with the same interrupt number as the minidriver is attached to. If you want the full driver to take over processing the interrupt, the minidriver handler should return 1 to indicate that it wants to exit.

data

The virtual address of the data area, converted from the physical address that you provided as the data_paddr parameter to mdriver_add().

---

If you're working with an ARM platform, your minidriver handler function must be written as Position Independent Code (PIC). This means that when your handler is in the MDRIVER_KERNEL, MDRIVER_PROCESS, or MDRIVER_INTR_ATTACH state, you must not use global or static variables.

---

The handler function should return:

• 0 if the handler function is still needed
• 1 to request that the kernel remove the minidriver

Don't assume that just because the handler has been called that the device actually needs servicing.

Hardware access

The minidriver program most likely requires hardware access, meaning it needs to read and write hardware registers. In order to help you access hardware registers, the startup library provides function calls to map and unmap physical memory. At different times in the boot process, some calls may or may not be available:

• When the minidriver handler is called with MDRIVER_INIT, these functions are available:
  • startup_io_map()
  • startup_io_unmap()
  • startup_memory_map()
  • startup_memory_unmap()
• After the minidriver handler is called with MDRIVER_STARTUP_PREPARE, the above functions are no longer available, and your driver must use these instead:
  • callout_io_map()
  • callout_memory_map()

For more information, see the Customizing Image Startup Programs chapter of Building Embedded Systems.

Here's a summary of what you need to do at each state if your minidriver needs to access hardware:

MDRIVER_INIT

• Initialize the hardware, if necessary.
• Call startup_io_map() or startup_memory_map() to gain hardware access.
• Store this pointer (which we'll call ptr1) in the minidriver data area and use it to access hardware.

MDRIVER_STARTUP

Use ptr1 to do all hardware access. No memory map calls are needed.

MDRIVER_STARTUP_PREPARE

At this point, The minidriver should call callout_io_map() or callout_memory_map(), Store the returned pointer (which we'll call ptr2) in the minidriver data area or in a static variable, separate from the previously stored value. Don't use ptr2 yet; continue to use ptr1 to do all hardware access.

MDRIVER_STARTUP_FINI

This is the last call to your handler from within startup, so it's the last state in which you'll use ptr1 to do all hardware access. After this state, you'll use ptr2 instead.

MDRIVER_KERNEL, MDRIVER_PROCESS, MDRIVER_INTR_ATTACH

In these states, use ptr2 to do all hardware access.

For an example, see the Hardware Interaction Within the Minidriver appendix.

Debugging from within the minidriver

Use the following techniques to debug your minidriver:

• If your startup code is able to print data to a serial port or other debug device, then you can use kprintf() to print any variable you wish to see. For example, in your minidriver code:

  kprintf("I am the minidriver!\n");
  kprintf("Global variable mcounts=%d\n", mcounts);
    

  For more information, see the Customizing Image Startup Programs chapter of Building Embedded Systems.

• Include any information that you wish to collect in the data area you allocated for your minidriver. After the kernel has booted, you can examine the data inside this area. See the mini-peeker.c program for an example of doing this.
• Depending on your hardware, you could use JTAG. If LEDs or other diagnostics are available, your minidriver could output values to hardware registers or ports to indicate certain conditions.

Customizing the startup program to include your minidriver

You need to modify the startup code in the BSP's main.c file in order to set up the minidriver's data area, register the handler function, and so on. Depending on what your minidriver needs to do, you might have to do the following:

• Declare the prototype for your minidriver's handler function. For example:

  extern int mini_data(int state, void *data);		
    

• Call init_raminfo(), to determine the location and size of available system RAM.
• Allocate the required system RAM for your data area by calling alloc_ram(). For example:

  /* Global variable: */
  paddr_t	mdriver_addr;
  
  /* Allocate 64 KB of memory for use by the minidriver */
  
  mdriver_addr = alloc_ram(~0L, 65536, 1);
    

• Call init_intrinfo() to add the interrupt information to the system page.
• Call mdriver_add() to register your minidriver handler. For example:

  /* Add a minidriver function called "mini-data" for IRQ 81. */
  
  mdriver_add("mini-data", 81, mini_data, mdrvr_addr, 65536);	
    

For more information about the startup library functions, see the Customizing Image Startup Programs chapter of Building Embedded Systems.

Making the transition to a full driver

Once the kernel is running and interrupts are enabled, the minidriver continues to be called when the interrupt that it's attached to is triggered. This action can continue for the lifetime of the system; in other words, the minidriver can behave like a tiny interrupt handler that's always active.

Usually the hardware needs more attention than the minidriver is set up to give it, so you'll want the minidriver to hand off to a full driver.

Here's the sequence of events for doing this:

• The full driver locates the minidriver's entry in the system page by using the SYSPAGE_ENTRY() macro. For an example, see the entry for mdriver_entry in this guide.
• The full driver maps the minidriver's data area into its memory space. For example:

  dptr = mmap_device_memory( 0, 65536,
            PROT_READ | PROT_WRITE | PROT_NOCACHE,
            0, SYSPAGE_ENTRY(mdriver)->data_paddr );
    

• The full driver can do post-processing of existing data.

  Since the minidriver is still running at this point, it continues to run whenever the interrupt is triggered. Depending on the design, it may be necessary to do some processing of the existing data that has been stored by the minidriver before the full driver takes control.

• The full driver attaches to the interrupt by calling InterruptAttach() or InterruptAttachEvent().

  For safety, the full driver should always disable the device interrupt before calling InterruptAttach() or InterruptAttachEvent(), and then enable the interrupt upon success.

• When the full driver attaches to the interrupt, the kernel calls the minidriver with a state of MDRIVER_INTR_ATTACH. The minidriver should do any cleanup necessary, disable the device interrupt, and then return a value of 1 to request that the kernel remove it.

  After this, the minidriver is no longer called, and only the full driver receives the interrupt.

• The full driver begins to handle the device and process any device data that was stored in the minidriver data area.

Making a boot image that includes your minidriver

At this point, you have a startup program (including your minidriver code) that's been compiled. Now include this startup program in the QNX Neutrino boot image and try out the minidriver.

There are some basic rules to follow when building a boot image that includes a minidriver:

• The boot image shouldn't be compressed. Decompression of the boot image affects the timings defined by the mdriver_max copy size. Your boot image should have an image type like the following:

  [virtual=armle-v7,binary] .bootstrap = {
    

  Note that the keyword +compress isn't included in this line. You should change the armle-v7 or binary entry to reflect your hardware and image format.

• After you compile your startup program that includes the minidriver, make sure to specify this startup program in your buildfile.

  For example, if you compile your startup program as startup-my_board, you should copy it to the appropriate directory (e.g., ${QNX_TARGET}/armle-v7/boot/sys/startup-my_board-mdriver), and then change your buildfile to include startup-my_board-mdriver.

  For more information and sample buildfiles, see the Sample Drivers for Instant Device Activation chapter of this guide.