QNX Neutrino RTOS Getting Started with QNX Neutrino: A Guide for Realtime Programmers By Rob Krten; updated by QNX Software Systems © 2008, QNX Software Systems GmbH & Co. KG. © 1999–2008, QNX Software Systems GmbH & Co. KG. All rights reserved. Published under license by: QNX Software Systems International Corporation 175 Terence Matthews Crescent Kanata, Ontario K2M 1W8 Canada Voice: +1 613 591-0931 Fax: +1 613 591-3579 Email: [email protected] Web: http://www.qnx.com/ Electronic edition published 2008. QNX, Neutrino, Photon, Photon microGUI, Momentics, and Aviage are trademarks, registered in certain jurisdictions, of QNX Software Systems GmbH & Co. KG. and are used under license by QNX Software Systems International Corporation. All other trademarks belong to their respective owners. Contents About This Guide xi What you’ll find in this guide xiii Typographical conventions xiii Note to Windows users xiv Technical support xv Foreword to the First Edition by Peter van der Veen 1 Preface to the First Edition by Rob Krten 5 A little history 8 Who this book is for 8 What’s in this book? 8 Processes and Threads 9 Message Passing 9 Clocks, Timers, and Getting a Kick Every So Often 9 Interrupts 9 Resource Managers 9 QNX 4 to QNX Neutrino 9 Calling 911 10 Glossary 10 Index 10 Other references 10 About Rob Krten 10 Acknowledgments 10 1 Processes and Threads 13 Process and thread fundamentals 15 A process as a house 15 The occupants as threads 15 Back to processes and threads 15 Mutual exclusion 16 Priorities 17 Semaphores 17 A semaphore as a mutex 18 The kernel’s role 19 October 20, 2008 Contents iii © 2008, QNX Software Systems GmbH & Co. KG. Single CPU 19 Multiple CPU (SMP) 19 The kernel as arbiter 19 Kernel states 24 Threads and processes 26 Why processes? 26 Starting a process 27 Starting a thread 36 More on synchronization 57 Readers/writer locks 57 Sleepon locks 59 Condition variables 63 Additional Neutrino services 68 Pools of threads 69 Scheduling and the real world 76 Rescheduling — hardware interrupts 77 Rescheduling — kernel calls 77 Rescheduling — exceptions 77 Summary 78 2 Message Passing 79 Messaging fundamentals 81 A small microkernel and message passing 81 Message passing and client/server 82 Network-distributed message passing 85 What it means for you 85 The philosophy of Neutrino 86 Multiple threads 86 Server/subserver 87 Some examples 89 Using message passing 90 Architecture & structure 91 The client 91 The server 93 The send-hierarchy 97 Receive IDs, channels, and other parameters 97 Multipart messages 108 Pulses 113 Receiving a pulse message 114 The MsgDeliverEvent() function 117 Channel flags 118 iv Contents October 20, 2008 © 2008, QNX Software Systems GmbH & Co. KG. Message passing over a network 124 Networked message passing differences 126 Some notes on NDs 128 Priority inheritance 130 So what’s the trick? 132 Summary 133 3 Clocks, Timers, and Getting a Kick Every So Often 135 Clocks and timers 137 Operating periodically 137 Clock interrupt sources 139 Base timing resolution 140 Timing jitter 140 Types of timers 141 Notification schemes 142 Using timers 146 Creating a timer 146 Signal, pulse, or thread? 147 What kind of timer? 147 A server with periodic pulses 149 Timers delivering signals 157 Timers creating threads 157 Getting and setting the realtime clock and more 157 Advanced topics 159 Other clock sources 159 Kernel timeouts 163 Summary 165 4 Interrupts 167 Neutrino and interrupts 169 Interrupt service routine 170 Level-sensitivity versus edge-sensitivity 172 Writing interrupt handlers 175 Attaching an interrupt handler 175 Now that you’ve attached an interrupt 176 Detaching an interrupt handler 177 The flags parameter 178 The interrupt service routine 178 ISR functions 186 Summary 188 October 20, 2008 Contents v © 2008, QNX Software Systems GmbH & Co. KG. 5 Resource Managers 189 What is a resource manager? 191 Examples of resource managers 191 Characteristics of resource managers 192 The client’s view 192 Finding the server 193 Finding the process manager 194 Handling directories 195 Union’d filesystems 196 Client summary 198 The resource manager’s view 199 Registering a pathname 199 Handling messages 200 The resource manager library 200 The library really does what we just talked about 202 Behind the scenes at the library 203 Writing a resource manager 204 Data structures 205 Resource manager structure 210 POSIX layer data structures 219 Handler routines 226 General notes 226 Connect functions notes 228 Alphabetical listing of connect and I/O functions 230 io_chmod() 230 io_chown() 231 io_close_dup() 231 io_close_ocb() 232 io_devctl() 232 io_dup() 234 io_fdinfo() 235 io_link() 235 io_lock() 236 io_lock_ocb() 237 io_lseek() 237 io_mknod() 238 io_mmap() 239 io_mount() 240 io_msg() 240 io_notify() 241 io_open() 242 vi Contents October 20, 2008 © 2008, QNX Software Systems GmbH & Co. KG. io_openfd() 243 io_pathconf() 243 io_read() 244 io_readlink() 245 io_rename() 246 io_shutdown() 247 io_space() 247 io_stat() 248 io_sync() 248 io_unblock() [CONNECT] 249 io_unblock() [I/O] 249 io_unlink() 250 io_unlock_ocb() 251 io_utime() 251 io_write() 252 Examples 252 The basic skeleton of a resource manager 253 A simple io_read() example 255 A simple io_write() example 259 A simple io_devctl() example 263 An io_devctl() example that deals with data 266 Advanced topics 269 Extending the OCB 269 Extending the attributes structure 271 Blocking within the resource manager 272 Returning directory entries 273 Summary 283 A QNX 4 to Neutrino 285 QNX 4 and Neutrino 287 Similarities 287 Improvements 287 Porting philosophy 291 Message passing considerations 291 Interrupt service routines 301 Summary 302 B Calling 911 303 Seeking professional help 305 So you’ve got a problem. 305 Training 309 October 20, 2008 Contents vii © 2008, QNX Software Systems GmbH & Co. KG. C Sample Programs 311 atoz.c 313 time1.c 317 tp1.c 321 tt1.c 323 Glossary 325 Index 335 viii Contents October 20, 2008 List of Figures A process as a container of threads. 16 Three threads in two different processes. 21 Two threads on the READY queue, one blocked, one running. 22 Scheduling roadmap. 23 Memory protection. 27 Serialized, single CPU. 49 Multithreaded, single CPU. 50 Four threads, four CPUs. 51 Eight threads, four CPUs. 52 System 1: Multiple operations, multiple processes. 54 System 2: Multiple operations, shared memory between processes. 55 System 3: Multiple operations, multiple threads. 55 One-to-one mutex and condvar associations. 68 Many-to-one mutex and condvar associations. 68 Thread flow when using thread pools. 71 Neutrino’s modular architecture. 81 State transitions of server. 82 State transitions of clients. 83 Clients accessing threads in a server. 87 Server/subserver model. 88 One master, multiple workers. 90 Relationship between a server channel and a client connection. 94 Relationship of client and server message-passing functions. 94 Message data flow. 95 Transferring less data than expected. 96 The fs-qnx4 message example, showing contiguous data view. 106 Transferring several chunks with MsgWrite(). 107 How the kernel sees a multipart message. 110 Converting contiguous data to separate buffers. 111 Confusion in a multithreaded server. 122 Message passing over a network. Notice that Qnet is divided into two sections. 125 Three threads at different priorities. 131 Blocked threads. 131 October 20, 2008 List of Figures ix © 2008, QNX Software Systems GmbH & Co. KG. Boosting the server’s priority. 132 PC clock interrupt sources. 139 Clock jitter. 141 Level-sensitive interrupt assertion. 172 Edge-sensitive interrupt assertion. 173 Sharing interrupts — one at a time. 174 Sharing interrupts — several at once. 174 Control flow with InterruptAttach(). 183 Control flow with InterruptAttachEvent(). 183 Control flow with InterruptAttachEvent() and unnecessary rescheduling. 184 Control flow with InterruptAttach() with no thread rescheduling. 184 Neutrino’s namespace. 193 First stage of name resolution. 193 The _IO_CONNECT message. 194 Neutrino’s namespace. 195 Neutrino’s namespace. 196 Overlaid filesystems. 196 Architecture of a resource manager — the big picture. 205 A combine message. 217 The readblock() function’s combine message. 218 Data structures — the big picture. 219 x List of Figures October 20, 2008 About This Guide October 20, 2008 About This Guide xi © 2008, QNX Software Systems GmbH & Co. KG. Typographical conventions What you’ll find in this guide Getting Started with QNX Neutrino is intended to introduce realtime programmers to the QNX Neutrino RTOS and help them develop applications and resource managers for it. This book was originally written by Rob Krten in 1999 for QNX Neutrino 2. In 2005, QNX Software Systems bought the rights to the book; this edition has been updated by the staff at QNX Software Systems to reflect QNX Neutrino 6.4. The following table may help you find information quickly: To find out about: Go to: Peter van der Veen’s forward Foreword to the First Edition Rob Krten’s preface Preface to the First Edition Using processes and threads Processes and Threads Sending, receiving, and replying to messages Message Passing Working with times and timers Clocks, Timers, and Getting a Kick Every So Often Interrupts Interrupts Writing resource managers Resource Managers Migrating from QNX 4 to Neutrino QNX 4 to Neutrino Getting help Calling 911 Full source code for the examples Sample Programs Terms used in QNX docs Glossary Typographical conventions Throughout this manual, we use certain typographical conventions to distinguish technical