Instant Device Activation User's Guide:
Contents
1. map in minidriver data area if dptr mmap device memory 0 65535 PROT READ PROT WRITE PROT NOCACHE 0 SYSPAGE ENTRY mdriver data paddr NULL fprintf stderr Unable to get data pointer n return 1 mdata struct mini_data dptr dptr dptr sizeof struct mini data dump mini driver data printrf MDRIVER DATA Mim s printf NtMDRIVER STARTUP calls d n mdata nstartup printf tMDRIVER_STARTUP_PREPARE calls d n mdata gt nstartupp printf NtMDRIVER STARTUP FINI calls d n mdata nstartupf printf NtMDRIVER KERNEL calls dln mdata nkernel printf NtMDRIVER PROCESS calls d n mdata nprocess printf NtData Length calls dln mdata data len count mdata data len if dump data printf State information Nn 2014 QNX Software Systems Limited 27 Sample Minidriver 28 for 30s 3 count LFE printf sdin dptr i printti n Na return EXIT SUCCESS 2014 QNX Software Systems Limited Transition from minidriver to full driver Transition from minidriver to full driver 2014 QNX Software Systems Limited Here s an example of the code in the full driver that arranges the transition from the minidriver xf if id InterruptAttachEvent intr event NTO INTR FLAGS TRK MSK 1 perror InterruptAttachEventNin return 1 dptr mma2. else if state MDRIVER_KERNEL mdata gt kernel_counter else if state MDRIVER_STARTUP_PREPARE Once we are out of startup use callout_io_map or callout_memory_map kprintf I am in STARTUP PREPARE x n mdata gt total_message_counter if mdata gt MYBUS_REGS_POSTKERNEL MYBUS regs t callout memory map 0x10 MBAR_BASE MYBUS_OFFSET PROT READ PROT WRITE PROT NOCACHE Something bad happened Disable the interrupt and turn off the minidriver mdata MYBUS REGS PREKERNEL control register CTRL INTERRUPT OFF return 1 At this point we use MYBUS REGS We could either be in startup in kernel loading or at process time Read the interrupt status register immediately upon entry to the handler StatusReg mdata MYBUS REGS interrupt status Increase the message counter mdata total message countertt switch StatusReg Read my data and add to my data area after data_len in MYBUS_data_t Make sure that you clear the source of interrupt before you return KA aue oe if state MDRIVER_STARTUP_FINI val mdata gt total_message_counter kprintf I am in state STARTUP FINI Total messages processed x n val Startup has finished now I switch over to use the POSTKERNEL mapping mdata MYBUS REGS mdata gt MYBUS_REGS_POSTKERNEL return 0 2014 QNX Software Systems Limited 39 Index A alloc
3. 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 nterruptAttach or InterruptAttachEventi 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 2014 QNX Software Systems Limited Making a boot image that includes your minidriver 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 GNK Neutr
4. e Copy the next 16 KB The startup library contains a global variable mdriver max p 36 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 e 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 e Setthe value in your startup s main before you register the minidriver handler 14 2014 QNX Software Systems Limited Data storage Data storage 2014 QNX Software Systems Limited The minidriver program usually reguires 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 reguire 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 A writes
5. in the system ay init_raminfo In a virtual system we need to initialize the page tables if shdr gt flagsl amp STARTUP_HDR_FLAGS1_VIRTUAL init mmu The following routines have hardware or system dependencies that may need to be changed init intrinfot Allocate a 64 KB data area mdrvr addr alloc ram OL 65535 1 Register the minidriver and its handler function mdriver add mini data 0 mini data mdrvr addr 65535 The name stored in the system page for our minidriver is mini data 26 O 2014 QNX Software Systems Limited Test application mini peeker c Test application mini peeker c Here s the source code for a test application called mini peeker c that maps in the minidriver data area and prints the contents estalabgh stdio h unistd h cstdint hs lt sys mman h gt lt sys neutrino h gt lt sys syspage h gt hw inout h lt inttypes h gt ude ude ude ude ude ude ude ude ude incl inol inel incl incl tnol ingi irinel inel struct mini data wine let nstartup uint16 t nstartupp uzntl6 t nstartupf uint16 t nkernel urntl6 t nprocess uint16 t data len hi int main int argc char argv int Ty Goune int dump_data 0 Winks t dpotrs struct mini data mdata if argv 1 dump data 1 ThreadCtl NTO TCTL IO 0
6. outside of its data area a system failure could occur and the operating system might not boot 15 Writing a Minidriver 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 e 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 p 32 MDRIVER STARTUP The driver is being called from somewhere in tartup 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 nterruptAttach 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 ph
7. the booting process The handler function is initially triggered from a timer polling Once CPU interrupts are enabled the handler function is triggered by the real hardware interrupt Note that the timers can also generate interrupts allowing for a polled approach to be used for hardware that doesn t generate interrupts You can use the data area to store any information that the handler function needs to keep and potentially share with the full driver 11 Using Minidrivers for Instant Device Activation How does the minidriver work Seamless transition A minidriver is a function that you link to the QNX Neutrino startup program so that it runs before the system becomes operational and the kernel is initialized A minidriver can access hardware and store data in a RAM buffer area where a full process time driver can then read this buffered information During system startup a minidriver handler function is periodically called or polled You can adapt this periodic polled interval to suit your device s timing requirements with minor changes to the startup program At some point in the system startup interrupts become available and this handler function becomes interrupt driven The handler is called with a state variable so the handler knows why it was called As soon as a full driver process is running in a fully operational system transition takes place from the minidriver to a full driver This transition is seamless an
8. the interrupt Write any values to the MYBUS REGS P as needed and then turn on the interrupt source MYBUS REGS P control register kprintf MYBUS is initialized n return MYBUS REGS P CTRL INTERRUPT ON JAKKAKAKKAKKKAKKKAKKKAKKKKKKAKKKAK KKK KKAKKKAKKKAKKKAKKKKKKAK int mini mybus handler void KAKKAKKKAKKKKAKKAKKKAKKAKKKAKKKAKKAKKKAKKKKKKAKKKKKKKKKKKKJ int mini mybus handler int state void data U8 dptr U8 StatusReg U8 notValid MYBUS data t mdata int val mdata MYBUS data t data dptr data sizeof MYBUS data t if state MDRIVER INTR ATTACH 38 2014 QNX Software Systems Limited kprintf Real driver is attaching minidriver was called d times n mdata total message counter Disable MYBUS interrupt mdata MYBUS REGS POSTKERNEL control register CTRL INTERRUPT OFF return 1 else if state MDRIVER INIT The first time called initialize the hardware and do data setup mdata MYBUS REGS PREKERNEL MYBUS Init if mdata MYBUS REGS PREKERNEL 0 return 1 Make our default register location reflect the fact that we are in PREKERNEL mdata gt MYBUS_REGS mdata gt MYBUS_REGS_PREKERNEL Initialize the counters of messages received mdata gt total_message_counter 0 mdata gt process_counter 0 mdata gt kernel_counter 0 else if state MDRIVER_PROCESS mdata gt process_counter
9. 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 p 27 program for an example of doing this e 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 18 2014 QNX Software Systems Limited Customizing the startup program to include your minidriver Customizing the startup program to include your minidriver 2014 QNX Software Systems Limited 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 a loc ram For examp
10. 0 P polling 14 Position Independent Code PIC required for ARM 16 R RAM transferring data from flash 14 36 S startup io map 17 startup io unmap 17 startup memory map 17 startup memory unmap 17 states 16 static variables avoiding 16 SYSPAGE ENTRY 20 34 system failures 15 system page entries for minidrivers 34 41 Index T Technical support 8 42 transition to full driver 12 20 Typographical conventions 6 2014 QNX Software Systems Limited
11. 13 Tires regulremeris s id deett tta eee TTET acct es 14 Data Storage cete etr e e e etel Pr UB EL Tet rur tme Dee Pn 15 Plan der TUM or Ons e IRL 16 Hardware ACCESS ted e e a dae debeo tated tons ME debit dee EE anna 17 Debugging from within the minidriver Loco Wan 18 Customizing the startup program to include your minidriver esses 19 Making the transition to a full driver o ooooooWooWoWoWo Woman 20 Making a boot image that includes your minidriver eese 21 Chapter 3 Sample Minidriver oooooco o o oo Wo Wo WWW Wo Wo mn 23 The minidriver handler function Woman 24 Adding your minidriver to the system oooo oWoWo WoWoWoWoW om WWW 26 Test application mini peekerQe iios ndie td eens kesh de shetit Nan Ria SOR e nde e eg Raus 27 Transition from minidriver to full driver oom nh 29 Chapter 4 APIs and Datatypes seen ion na an aan angan 31 mariver Add inn dimin te n oder EN NE NN IA NA NT NN 32 mariversentty c5 aov AA KA AB Rm en M i e inn a bada 34 adt auri XE 36 Appendix A Hardware Interaction Within the Minidriver Woo momo mmm 37 Table of Contents About This Guide 2014 QNX Software Systems Limited The Instant Device Activation User s Guide will help you set up a minidriver to start devices quickly when the system boots The following table may help you find information quickly in this guide For information on Go to An o
12. 32 t name int3a2 t internal Unta s spare ll When you call mdriver add p 32 it adds an entry for your minidriver to the system page The members of the mdriver entry structure include intr The interrupt that the minidriver is attached to handler A pointer to the minidriver handler function data data paddr The virtual and physical addresses of the minidriver s data area respectively data size The size of the minidriver s data area in bytes name The offset into the system page s strings section where the minidriver s name is stored In order for a full process time driver to find a minidriver and gain access to its data area it must access the entry in the system page by using the SYSPAGE ENTRY macro SYSPAGE ENTRY mdriver i data paddr O 2014 QNX Software Systems Limited Classification 2014 QNX Software Systems Limited mdriver entry where j is the index into the minidriver section You can use the narne field to locate a specific minidriver if there are multiple ones running in the system possibly attached to the same interrupt Here s some sample code that accesses this information int i num drivers 0 struct mdriver entry mdriver mdriver struct mdriver entry num drivers SYSPAGE ENTRY mdriver Syspage ptr mdriver entry size sizeof mdriver printf Number of Installed minidrivers d n n num drivers for i 0 i lt num drivers i
13. OS image size this time can be in the order of hundreds of milliseconds or even seconds To reduce this time a minidriver runs much earlier in the boot process to take care of the timing requirements for some bus protocols such as MOST or CAN Defined in the system s startup code a minidriver runs user code before the operating system has been booted This code could include responding to hardware power up messages in a quick timely fashion and ensuring that no message is lost when the OS boots up Once the OS has booted the minidriver may continue running or it may pass control to a full featured driver that can access any data the minidriver has buffered Vehicle bus A I O requests I O requests Data I area an I 1 1 is 1 Minidri I Minidriver A Ny Boot loader 5 initialized Full Boot loader Kernel driver A running initialized Initial power on code Copy OS image boot OS OS running handle I O requests i 0 lt 50 ms 200 500 ms Figure 1 Booting process using instant device activation 2014 QNX Software Systems Limited The minidriver architecture The minidriver architecture 2014 QNX Software Systems Limited A minidriver consists of these fundamental components e a handler function e an optional data area e startup code to create the data area and register the handler Once a minidriver is created its handler function is called throughout
14. QNX Software Development Platform 6 6 Instant Device Activation User s Guide s CAINDC 2006 2014 QNX Software Systems Limited a subsidiary of BlackBerry Limited All rights reserved QNX Software Systems Limited 1001 Farrar Road Ottawa Ontario K2K OB3 Canada Voice 1 613 591 0931 Fax 1 613 591 3579 Email info gnx com Web http www gnx com QNX QNX CAR Momentics Neutrino and Aviage are trademarks of BlackBerry Limited which are registered and or used in certain jurisdictions and used under license by QNX Software Systems Limited All other trademarks belong to their respective owners Electronic edition published Monday July 14 2014 Instant Device Activation User s Guide Table of Contents About This Guide ibn aan dedu AGAR a eng A anang Anang ata 5 Typographicall CONVENTIONS nisesh er ete eee SEN a eme tr ne MER RA 6 Technical SuppOrt sasasi ciet oo ct e ea de ei ved eget um dx ed ute bd e AREE So aa a a 8 Chapter 1 Using Minidrivers for Instant Device Activation seeesee eee nennen 9 Th eminidriver BASE educere xe adir aene dea dushe Dee ot san eme erudi ge Dee ak ame Rie i 10 The minidriver architecture aaa Woman 11 How does the minidriver work oo Woo 12 Seamless TANSILION siio retra ree nene ER EN SAE NN 12 Running multiple handler functions aa aaa nana aaa aaa nane aak Wcom nennen nennen nnn nne 12 Chapter 2 Writing a Minidriver oo Wo Wo Wo WWW JW mma
15. RIVER KERNEL mdata nkernel mdata gt nkernel 1 else if state MDRIVER_PROCESS mdata nprocess mdata nprocess t 1 else if state MDRIVER INTR ATTACH normally disable my interrupt return 1 put the state information in the data area after the structure if we have room if mdata data len lt 60000 dptr mdata data len uint8 t state mdata data len mdata data len 1 O 2014 QNX Software Systems Limited The minidriver handler function 2014 QNX Software Systems Limited return 0 A few things to note e The handler function stores call information so a structure has been created to allow easier access to the data area e When the state is MDRIVER INIT the handler initializes the data area The handler is called only once with this state e Before we store the state information we make sure that we re not about to write outside the data area lest we crash the startup e If the handler is called with MDRIVER INTR ATTACH it returns a value of 1 requesting that the kernel remove the minidriver However due to the asynchronous nature of the system there might be several more invocations of the handler after it has indicated that it wants to stop 25 Sample Minidriver Adding your minidriver to the system The main function of startup main c looks like this paddr t mdrvr addr Collect information on all free RAM
16. U16 data len Length of data portion stored in the data area MYBUS data t Physical memory locations and offsets 2014 QNX Software Systems Limited 37 Hardware Interaction Within the Minidriver define MBAR BASE Oxff000000 define GPIO OFFSET 0x0c00 define MYBUS OFFSET 0x2400 Control register settings define CTRL INTERRUPT ON 0x01 define CTRL_INTERRUPT_OFF 0x00 JAKKAKKAKKKKKKAKKKAK e e e e e e e e k e e e e e e e e e e e kake kak kakak kakak k k void MYBUS Init void Hardware initialization function for MYBUS This routine is called only once when the minidriver is started INPUTS None OUTPUTS None KAKKAKKKAKKKAKKKKKKAKKKAKAKKAKKKAKKKAKKKAKKKAKKKKKKKKKKAKKKKJ static MYBUS regs t MYBUS Init void GPIO_regs_t GPIO_REGS_P MYBUS_regs_t MYBUS_REGS_P U32 data_byte if GPIO REGS P GPIO regs t startup memory map 0x40 PROT READ PROT WRITE PROT NOCACHE MBAR BASE 4 GPIO OFFSET startup memory unmap unsigned GPIO REGS P return 0 Change GPIO as needed Data GPIO REGS P gpio0 Data Data amp OxFFFOFFFF GPIO REGS P gpio0 Data We are done with GPIO startup memory unmap void PORT REGS P if MYBUS REGS P MYBUS regs t startup memory map 0x10 MBAR BASE t MYBUS OFFSET PROT READ PROT WRITE PROT NOCACHE startup memory unmap unsigned MYBUS REGS P return 0 Initialize MYBUS and turn on
17. ction The virtual address of this block is passed to the handler function as its data argument data size The size of the block of memory denoted by data padar Library libc 32 2014 QNX Software Systems Limited Description Returns Classification 2014 QNX Software Systems Limited mdriver add This function registers the minidriver with the system as follows e Itchecks the interrupt number to make sure it s valid so you must call init intrinfo to add the interrupt information to the system page before you can register a minidriver For more information see the Customizing Image Startup Programs chapter of Building Embedded Systems If the interrupt number isn t valid mdriver_add crashes the system e tcalls the handler with a state of MDRIVER INIT and the virtual address that corresponds to the physical address given by data padar e t adds an entry of type mdriver entry p 34 to the mdriver section of the system page You call mdriver_add from main in your board s startup code The index into the mdriver section of the system page for the newly added minidriver or 1 if the minidriver wasn t added QNX Neutrino 33 APls and Datatypes 34 mdriver_entry Synopsis Description Minidriver system page entry struct mdriver entry int3s2 t intr tm handler int state void data void data paddr32 t data paddr j uint32 t data size uint
18. d causes no blackout times The full driver merely attaches to the device interrupt which causes the minidriver to be notified that another process is attaching to its interrupt The minidriver can then gracefully exit and the full driver continues to run The full driver has access to any buffered data that the minidriver chooses to store Running multiple handler functions 12 The minidriver can run multiple handler functions For devices that must do something every n milliseconds you could attach two handler functions e aminidriver for the actual device interrupt e aminidriver for the system timer tick Since the timer minidriver is intermittently polled i e not invoked at a constant interval during startup the driver needs to use something to measure the time between the calls to get the proper interval This architecture allows device drivers to start very early in the system startup and allows the device to continue to function during all boot phases If a full driver doesn t choose to take over device control the minidriver continues to run when the system is fully operational 2014 QNX Software Systems Limited Chapter 2 Writing a Minidriver 2014 QNX Software Systems Limited 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 mini
19. driver 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 13 Writing a Minidriver 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 e Copy the next 16 KB Call the minidriver
20. he 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 e Initialize the hardware if necessary e Call startup io map or startup memory map to gain hardware access e Store this pointer which we ll call ptr1 in the minidriver data area and use it to access hardware MDRIVER STARTUP Use ptri 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 2014 QNX Software Systems Limited 17 Writing a Minidriver 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 ptr 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 p 37 appendix Debugging from within the minidriver Use the following techniques to debug your minidriver e f your startup code is able to print data to a serial port or other debug device
21. ino boot image and try out the minidriver There are some basic rules to follow when building a boot image that includes a minidriver e 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 tcompress isn t included in this line You should change the armle v7 Or binary entry to reflect your hardware and image format e 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 ONX TARGET armle v7 boot sys startup my board mdriver and then change your buildfile to include startup my board mdriver 2014 QNX Software Systems Limited 21 Chapter 3 Sample Minidriver 2014 QNX Software Systems Limited The minidriver program in this example is a simple implementation that you can use for debugging purposes It counts the number of times it s called for each phase of the boot process and stores that information in its data area Once the system is booted a program can read the data area and retrieve this information No hardware access is reguired for this minidriver In this example the size of the data area is 64 KB If
22. le Global variable paddr t mdriver addr Allocate 64 KB of memory for use by the minidriver mdriver addr alloc ram OL 65536 1 Call init intrinfo to add the interrupt information to the system page Call mdriver add p 32 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 19 Writing a Minidriver 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 20 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 p 34 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
23. or undesirable side effects 2014 QNX Software Systems Limited 2014 QNX Software Systems Limited Typographical conventions Warnings tell you about commands or procedures that could be dangerous to your files your hardware or even yourself Note to Windows users In our documentation we typically use a forward slash as a delimiter in pathnames including those pointing to Windows files We also generally follow POSIX UNIX filesystem conventions About This Guide Technical support Technical assistance is available for all supported products To obtain technical support for any QNX product visit the Support area on our website www gnx com You ll find a wide range of support options including community forums 8 2014 QNX Software Systems Limited Chapter 1 Using Minidrivers for Instant Device Activation 2014 QNX Software Systems Limited Advanced CPUs are providing higher levels of hardware integration than ever before directly controlling such interfaces as CAN J1850 and MOST This approach saves on hardware costs by reducing the need for extra chips and circuitry but it also raises concerns for the software developer For instance a telematics control unit must be able to receive CAN messages within 30 to 100 milliseconds from the time that it s powered on The problem is that the complex software running on such a telematics device can easily take hundreds of milliseconds o
24. p device memory 0 data size PROT READ PROT WRITE PROT NOCACHE 0 SYSPAGE ENTRY mdriver data paddr NULL fprintf stderr Unable to get data pointer n return 1 Your minidriver should now be stopped and you should have access to the interrupt and the data area Enable device interrupt intr Once the full driver is attached to the interrupt it can process any buffered data and continue to provide hardware access 29 Chapter 4 APls and Datatypes This chapter describes the APls and datatypes for Instant Device Activation 2014 QNX Software Systems Limited 31 APls and Datatypes mdriver_add Register the minidriver with the system Synopsis int mdriver_add char name int interrupt int handler int state void data paddr32_t data_paddr unsigned data size Arguments name An arbitrary character string used for identification purposes interrupt The interrupt that you want to attach the handler to handler A pointer to the handler function for the minidriver For more information see Handler function p 16 in the Writing a Minidriver chapter data paddr The physical address of a block of memory that the minidriver can use to store any data It can be e a predetermined location e g one that you reserved beforehand by passing the r adar sizel flagl option to startup a block that you allocated by calling the a loc ram startup fun
25. r more to boot up As another example consider the critical milestones during the boot process for an in car telematics or infotainment unit that typically boots from a cold condition completely powered off or from CPU reboot condition returning from a state where SDRAM has been turned off The unit must be able to e receive CAN messages within 30 to 100 milliseconds after power is turned on e respond to these messages within 100 milliseconds of receiving them e read Class 2 messages from a vehicle bus and respond to wake events e initialize a MOST transceiver and respond to MOST requests animate a splash screen graphical display before the operating system has loaded In order to address such timing requirements many embedded system designs rely on a simple but expensive solution that uses an auxiliary communications processor or external power module This auxiliary hardware can be reduced in scope and sometimes even eliminated by using nstant Device Activation Also called minidriver technology the approach consists of small highly efficient device drivers that start executing before the OS kernel is initialized Using Minidrivers for Instant Device Activation 10 The minidriver basics During the normal GNK Neutrino boot process a driver process can t run until the OS image has been loaded into the RAM and the kernel has been initialized Depending on the particular hardware processor flash architecture and the
26. ram 19 ARM use Position Independent Code PIC for 16 boot failures 15 boot image creating 21 boot process 10 C callout io mapO 17 18 callout memory map 17 18 compression don t use for boot images 21 D data area 15 18 19 20 23 34 allocating 19 avoid writing beyond bounds 15 debugging 18 E examples 23 27 37 mini peeker 27 F flash transferring data to RAM 14 36 full driver transition to 12 20 G GIG 36 global variables avoiding 16 H handler function 12 16 19 24 25 32 adding 19 examples 24 exiting 25 multiple 12 registering 32 hardware access 17 37 init_intrinfo 19 init_raminfo 19 InterruptAttach InterruptAttachEvent 16 20 2014 QNX Software Systems Limited Instant Device Activation User s Guide interrupts disabling and enabling 20 K KILOO 36 kprintf 18 M mdriver_add 16 19 32 mdriver_entry 34 MDRIVER_INIT 16 17 25 MDRIVER_INTR_ATTACH 16 18 20 25 MDRIVER_KERNEL 16 18 mdriver_max 14 23 36 MDRIVER_PROCESS 16 18 MDRIVER_STARTUP 16 17 MDRIVER_STARTUP_FINI 16 18 37 MDRIVER_STARTUP_PREPARE 16 17 18 37 MEG 36 mini peeker test application 27 minidriver 9 11 12 13 15 16 17 18 20 23 34 architecture 11 considerations 13 data storage 15 debugging 18 defined 9 entries for in system page 34 examples 23 handler function 16 requesting removal of 17 states 16 transition to full driver 12 20 mmap_device_memory 2
27. s which will be read from and written to Remember that the mapping of hardware registers depends on where in the boot process that the minidriver is called This transition is handled in the T MDRIVER STARTUP PREPARE and MDRIVER STARTUP FINI stages include startup h This is included with the BSP for your board typedef unsigned char U8 typedef unsigned short U16 typedef unsigned int U32 BRK e ke ke e e ke ke e e k MYBUS Registers KAKKAKKKKKKKKKKKKKKKJ typedef struct MYBUS register set volatile U8 interrupt status volatile U8 data register volatile U8 control register volatile U8 extral volatile U8 extra2 volatile U8 extra3 volatile U8 extra4 volatile U8 extras5 MYBUS regs t JAKAKAKKKKKKKKK GPIO Registers KAKKAKKKKKKKKKKKKKKKJ typedef struct GPIO register set volatile U32 gpio0 volatile U32 gpiol GPIO regs t RR KKK KK kkk k k Minidriver data area KAKKKKKKKKKKJ typedef struct MYBUS_regs MYBUS_REGS This is the same as either PREKERNEL or POSTKERNEL MYBUS_regs MYBUS_REGS_PREKERNEL_START Register mappings to use before the kernel starts MYBUS_regs MYBUS_REGS_POSTKERNEL_START Register mappings to use after the kernel starts U16 total_message_counter Total times the minihandler is called U16 process_counter Times called after the kernel is running U16 kernel_counter Times called while the kernel is booting
28. tt printf Minidriver entry SA 3 printf Name oom s n SYSPAGE_ENTRY strings gt data mdriver i name printf Interrupt ndrin ev s dk 0x X n mdriver i intr printf Data SIZE 9 9 dWNn mdriverlil data size pruntf Nn QNX Neutrino 35 APls and Datatypes mdriver max Amount of data copied from flash to RAM between calls to the minidriver Synopsis unsigned mdriver max KILO 16 Description The mdriver max is a global variable defined in the file mdriver_max c in the startup code It defines the amount of data in bytes that s copied from flash to RAM between calls to your minidriver The default value is 16 KB but you might have to change it depending on the timing requirements of your device the processor speed and the flash see Timing requirements p 14 in the Writing a Minidriver chapter The KILO macro along with MEG and GIG is defined in lt startup h gt Classification QNX Neutrino 36 2014 QNX Software Systems Limited Appendix A Hardware Interaction Within the Minidriver The following example shows how to interact with hardware from within a minidriver It s for a fictional hardware device called MYBUS with the following characteristics e There s a series of 8 bit registers status and data at address OxFFOOOOOO MBAR BASE e Interrupt 56 is generated when a character arrives at the MYBUS port There are registers at this addres
29. verview of Instant Device Activation Using Minidrivers for Instant Device Activation p 9 How to write instant device activation Writing a Minidriver p 13 code An example of the code for a minidriver Sample Minidriver p 23 API and datatypes API and Datatypes p 31 An example of interacting with hardware Hardware Interaction Within the Minidriver p 37 About This Guide Typographical conventions Throughout this manual we use certain typographical conventions to distinguish technical terms In general the conventions we use conform to those found in IEEE POSIX publications The following table summarizes our conventions Reference Code examples Command options Commands Constants Data types Environment variables File and pathnames Function names Keyboard chords Keyboard input Keyboard keys Program output Variable names Parameters User interface components Window title Example if stream NULL 1R make NULL unsigned short PATH dev null exit Ctrl Alt Delete Username Enter login stdin parm1 Navigator Options We use an arrow in directions for accessing menu items like this You ll find the Other menu item under Perspective Show View We use notes cautions and warnings to highlight important messages o Notes point out something important or useful Cautions tell you about commands or procedures that may have unwanted
30. you decrease the value of mdriver max the amount of data that s copied from flash to RAM between calls of your minidriver from its default 16 KB then you may need to increase the size of the data area because the handler function will be called more times 23 Sample Minidriver The minidriver handler function For this sample driver the source code for the handler function looks like this struct mini data intl6 t aintl6 t uinti6 t uintil6 t inti6 t uinti t nstartup nstartupp nstartupf nkernel nprocess data len Counts the number of calls for each state and int mini_data int state void data Wines dptr struct mini_data mdata mdata struct mini_data data dptr uint8_t mdata 1 on MDRIVER_INIT set up the data area if state MDRIVER_INIT mdata nstartup 0 mdata nstartupf 0 mdata nstartupp 0 mdata nkernel 0 mdata nprocess 0 mdata gt data_len 0 Sample minidriver handler function for debug purposes fills the data area with the current handler state count the number of calls we get for each type if state MDRIVER_STARTUP mdata nstartup mdata gt nstartup 1 else if state MDRIVER_STARTUP_PREPARE mdata nstartupp mdata nstartupp 1 else if state MDRIVER STARTUP FINI mdata nstartupf mdata nstartupf t 1 else if state MD
31. ysical 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 9 be written as Position Independent Code PIC This means that when your handler is in the MDRIVER KERNEL MDRIVER PROCESS Of MDRIVER INTR ATTACH state you must not use global or static variables The handler function should return 16 2014 QNX Software Systems Limited Handler function e O if the handler function is still needed e 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 e When the minidriver handler is called with MDRIVER INIT these functions are available e startup io map e startup io unmap e startup memory map e startup memory unmap e After the minidriver handler is called with MDRIVER STARTUP PREPARE the above functions are no longer available and your driver must use these instead e callout io map e callout memory map For more information see t
Download Pdf Manuals
Related Search