Skip to content
Snippets Groups Projects
Normal view Permalink
NuttxUserGuide.html 120 KiB
Newer Older
patacongo's avatar
NuttX RTOS
patacongo committed
4001 4002 4003 4004 4005 4006 4007 4008 
<UL>
<LI><I>Exxx</I>.
</UL>
<B>Assumptions/Limitations:</B>
<P>
<B>POSIX Compatibility:</B> Comparable to the POSIX
interface of the same name.
patacongo's avatar
Add kill()  
patacongo committed
4009 
<H3><a name="pthreadcondsignal">2.8.40 pthread_cond_signal</A></H3>
patacongo's avatar
NuttX RTOS
patacongo committed
4010 4011 4012 4013 4014 4015 4016 4017 4018 4019 4020 4021 4022 4023 4024 4025 4026 4027 4028 4029 4030 4031 4032 4033 4034 4035 4036 4037 4038 4039 
<P>
<B>Function Prototype:</B>
<P>
<PRE>
    #include &lt;pthread.h&gt;
    int pthread_cond_signal(pthread_cond_t *dond);
</PRE>
<P>
<B>Description:</B>
<P>
<B>Input Parameters:</B>
<P>
<UL>
<LI><I>parm</I> 
</UL>
<P>
<B>Returned Values:</B>
<P>
If successful, the <I>xxx()</I> function will return
zero (<I>OK</I>).  Otherwise, an error number will be
returned to indicate the error:
<P>
<UL>
<LI><I>Exxx</I>.
</UL>
<B>Assumptions/Limitations:</B>
<P>
<B>POSIX Compatibility:</B> Comparable to the POSIX
interface of the same name.
patacongo's avatar
Add kill()  
patacongo committed
4040 
<H3><a name="pthreadcondwait">2.8.41 pthread_cond_wait</A></H3>
patacongo's avatar
NuttX RTOS
patacongo committed
4041 4042 4043 4044 4045 4046 4047 4048 4049 4050 4051 4052 4053 4054 4055 4056 4057 4058 4059 4060 4061 4062 4063 4064 4065 4066 4067 4068 4069 4070 
<P>
<B>Function Prototype:</B>
<P>
<PRE>
    #include &lt;pthread.h&gt;
    int pthread_cond_wait(pthread_cond_t *cond, pthread_mutex_t *mutex);
</PRE>
<P>
<B>Description:</B>
<P>
<B>Input Parameters:</B>
<P>
<UL>
<LI><I>parm</I> 
</UL>
<P>
<B>Returned Values:</B>
<P>
If successful, the <I>xxx()</I> function will return
zero (<I>OK</I>).  Otherwise, an error number will be
returned to indicate the error:
<P>
<UL>
<LI><I>Exxx</I>.
</UL>
<B>Assumptions/Limitations:</B>
<P>
<B>POSIX Compatibility:</B> Comparable to the POSIX
interface of the same name.
patacongo's avatar
Add kill()  
patacongo committed
4071 
<H3><a name="pthreadcondtimedwait">2.8.42 pthread_cond_timedwait</A></H3>
patacongo's avatar
NuttX RTOS
patacongo committed
4072 4073 4074 4075 4076 4077 4078 4079 4080 4081 4082 4083 4084 4085 4086 4087 4088 4089 4090 4091 4092 4093 4094 4095 4096 4097 4098 4099 4100 4101 4102 4103 4104 4105 4106 4107 
<P>
<B>Function Prototype:</B>
<P>
<PRE>
    #include &lt;pthread.h&gt;
    int pthread_cond_timedwait(pthread_cond_t *cond, pthread_mutex_t *mutex,
				  const struct timespec *abstime);
</PRE>
<P>
<B>Description:</B>
<P>
<B>Input Parameters:</B>
<P>
<UL>
<LI><I>parm</I> 
</UL>
<P>
<B>Returned Values:</B>
<P>
If successful, the <I>xxx()</I> function will return
zero (<I>OK</I>).  Otherwise, an error number will be
returned to indicate the error:
<P>
<UL>
<LI><I>Exxx</I>.
</UL>
<B>Assumptions/Limitations:</B>
<P>
<B>POSIX Compatibility:</B> Comparable to the POSIX
interface of the same name.

<P>
<HR>
<H1>3.0 <A NAME="Data_Structures">OS Data Structures</A></H1>
<H2>3.1 Scalar types</H2>
<P>
patacongo's avatar
task_create now accepts variable number of arguments; 8051 bringup changes  
patacongo committed
4108 
Many of the types used to communicate with NuttX are simple
patacongo's avatar
NuttX RTOS
patacongo committed
4109 
scalar types. These types are used to provide architecture independence
patacongo's avatar
task_create now accepts variable number of arguments; 8051 bringup changes  
patacongo committed
4110 
of the OS from the application. The scalar types used at the NuttX
patacongo's avatar
NuttX RTOS
patacongo committed
4111 4112 4113 4114 4115 4116 4117 4118 4119 4120 4121 
interface include:
<UL>
<LI>pid_t
<LI>size_t
<LI>sigset_t
<LI>STATUS
<LI>time_t
</UL>

<H2>3.2 Hidden Interface Structures</H2>
<P>
patacongo's avatar
task_create now accepts variable number of arguments; 8051 bringup changes  
patacongo committed
4122 
Several of the types used to interface with NuttX are
patacongo's avatar
NuttX RTOS
patacongo committed
4123 4124 4125 4126 4127 4128 4129 4130 4131 4132 4133 4134 4135 4136 4137 4138 4139 4140 4141 4142 4143 4144 4145 4146 4147 4148 4149 4150 4151 4152 4153 4154 4155 4156 4157 4158 4159 4160 4161 4162 4163 4164 4165 4166 4167 4168 4169 4170 4171 4172 4173 4174 4175 4176 4177 4178 
structures that are intended to be hidden from the application.
From the standpoint of the application, these structures (and
structure pointers) should be treated as simple handles to reference
OS resources. These hidden structures include:
<UL>
<LI>_TCB
<LI>mqd_t
<LI>sem_t
<LI>WDOG_ID
<LI>pthread_key_t
</UL>
<P>
In order to maintain portability, applications should not reference
specific elements within these hidden structures. These hidden
structures will not be described further in this user's manual.
<P>

<H2>3.3. Access to the <I>errno</I> Variable</H2>
<P>
A pointer to the thread-specific <I>errno</I>. value is available through a
function call:
<P>
<B>Function Prototype:</B>
<P>
<PRE>    int *get_errno_ptr( void )</PRE>
<P>
<B>Description</B>:  <I>osGetErrnorPtr()</I> returns a pointer to
the thread-specific <I>errno</I> value.
<P>
This differs somewhat from the use for errno in a multi-threaded process environment:
Each pthread will have its own private copy of errno and the errno will not be shared
between pthreads.
<P>
<B>Input Parameters</B>:  None
<P>
<B>Returned Values</B>:
<P>
<UL>
<LI>A pointer to the thread-specific <I>errno</I> value.
</UL>
<P>

<H2>3.4 User Interface Structures</H2>
<P>
<H3>3.4.1 main_t</H3>
<P>
main_t defines the type of a task entry point. main_t is declared
in sys/types.h as:
<PRE>
    typedef int (*main_t)(int argc, char *argv[]);
</PRE>

<H3>3.4.2 struct sched_param</H3>

<P>
This structure is used to pass scheduling priorities to and from
patacongo's avatar
task_create now accepts variable number of arguments; 8051 bringup changes  
patacongo committed
4179 
NuttX;
patacongo's avatar
NuttX RTOS
patacongo committed
4180 4181 4182 4183 4184 4185 4186 4187 4188 4189 4190 
<PRE>
    struct sched_param
    {
      int sched_priority;
    };
</PRE>

<H3>3.4.3 struct timespec</H3>

<P>
This structure is used to pass timing information between the
patacongo's avatar
task_create now accepts variable number of arguments; 8051 bringup changes  
patacongo committed
4191 
NuttX and a user application:
patacongo's avatar
NuttX RTOS
patacongo committed
4192 4193 4194 4195 4196 4197 4198 4199 4200 4201 4202 4203 
<PRE>
    struct timespec
    {
      time_t tv_sec;  /* Seconds */
      long   tv_nsec; /* Nanoseconds */
    };
</PRE>

<H3>3.4.4 struct mq_attr</H3>

<P>
This structure is used to communicate message queue attributes
patacongo's avatar
task_create now accepts variable number of arguments; 8051 bringup changes  
patacongo committed
4204 
between NuttX and a MoBY application:
patacongo's avatar
NuttX RTOS
patacongo committed
4205 4206 4207 4208 4209 4210 4211 4212 4213 4214 4215 4216 4217 4218 
<PRE>
    struct mq_attr {
      size_t       mq_maxmsg;   /* Max number of messages in queue */
      size_t       mq_msgsize;  /* Max message size */
      unsigned     mq_flags;    /* Queue flags */
      size_t       mq_curmsgs;  /* Number of messages currently in queue */
    };
</PRE>

<H3>3.4.5 struct sigaction</H3>

<P>
The following structure defines the action to take for given signal:
<PRE>
patacongo's avatar
Eliminating SDCC compilation errors  
patacongo committed
4219 4220 4221 4222 4223 4224 
    struct sigaction
    {
      union
      {
        void (*_sa_handler)(int);
        void (*_sa_sigaction)(int, siginfo_t *, void *);
patacongo's avatar
NuttX RTOS
patacongo committed
4225 4226 4227 4228 4229 4230 4231 4232 4233 4234 4235 4236 4237 4238 4239 4240 4241 4242 4243 4244 4245 4246 4247 4248 4249 4250 4251 4252 4253 4254 4255 4256 4257 4258 4259 4260 4261 4262 4263 4264 4265 4266 4267 4268 4269 4270 4271 4272 
      } sa_u;
      sigset_t           sa_mask;
      int                sa_flags;
    };
    #define sa_handler   sa_u._sa_handler
    #define sa_sigaction sa_u._sa_sigaction
</PRE>

<H3>3.4.6 struct siginfo/siginfo_t</H3>

<P>
The following types is used to pass parameters to/from signal
handlers:
<PRE>
    typedef struct siginfo
    {
      int          si_signo;
      int          si_code;
      union sigval si_value;
   } siginfo_t;
</PRE>

<H3>3.4.7 union sigval</H3>

<P>
This defines the type of the struct siginfo si_value field and
is used to pass parameters with signals.
<PRE>
    union sigval
    {
      int   sival_int;
      void *sival_ptr;
    };
</PRE>

<H3>3.4.8 struct sigevent</H3>

<P>
The following is used to attach a signal to a message queue to
notify a task when a message is available on a queue.
<PRE>
    struct sigevent
    {
      int          sigev_signo;
      union sigval sigev_value;
      int          sigev_notify;
    };
</PRE>
patacongo's avatar
Progress toward clean SDCC compilation  
patacongo committed
4273 4274 4275 4276 4277 4278 4279 4280 4281 4282 4283 4284 4285 4286 4287 4288 4289 4290 4291 4292 4293 4294 4295 4296 4297 4298 4299 4300 4301 4302 4303 4304 4305 

<H3>3.4.9 Watchdog Data Types</H3>

<p>
  When a watchdog expires, the callback function with this
  type is called:
</p>
<pre>
    typedef void (*wdentry_t)(int argc, ...);
</pre>
<p>
  Where argc is the number of uint32 type arguments that follow.
</p>
  The arguments are passed as uint32 values.
  For systems where the sizeof(pointer) &lt; sizeof(uint32), the
  following union defines the alignment of the pointer within the
  uint32.  For example, the SDCC MCS51 general pointer is
  24-bits, but uint32 is 32-bits (of course).
</p>
<pre>
    union wdparm_u
    {
      void   *pvarg;
      uint32 *dwarg;
    };
    typedef union wdparm_u wdparm_t;
</pre>
<p>
  For most 32-bit systems, pointers and uint32 are the same size
  For systems where sizeof(pointer) > sizeof(uint32), we will
  have to do some redesign.
</p>
patacongo's avatar
Add kill()  
patacongo committed
4306 4307 4308 4309 4310 4311 4312 4313 4314 4315 4316 4317 4318 4319 4320 4321 4322 4323 4324 4325 4326 4327 4328 4329 4330 4331 4332 4333 4334 4335 4336 4337 4338 4339 4340 4341 4342 4343 4344 4345 4346 4347 4348 4349 4350 4351 4352 4353 4354 4355 4356 4357 4358 4359 4360 4361 4362 4363 4364 4365 4366 4367 4368 4369 4370 4371 4372 4373 4374 4375 4376 4377 4378 4379 4380 4381 4382 4383 4384 4385 4386 4387 4388 4389 4390 4391 4392 4393 4394 4395 4396 4397 4398 4399 4400 4401 4402 4403 4404 4405 4406 4407 4408 4409 4410 4411 4412 4413 4414 4415 
<h1><a name="index">Index</a></h1>
<ul>
  <li><a href="#Data_Structures">Data structures</a>
  <li><a href="#exit">exit</a></li>
  <li><a href="#getpid">getpid</a></li>
  <li><a href="#Introduction">Introduction</a>
  <li><a href="#kill">kill</a></li>
  <li><a href="#Message_Queue">Named Message Queue Interfaces</a>
  <li><a href="#mqclose">mq_close</a></li>
  <li><a href="#mqgetattr">mq_getattr</a></li>
  <li><a href="#mqnotify">mq_notify</a></li>
  <li><a href="#mqopen">mq_open</a></li>
  <li><a href="#mqreceive">mq_receive</a></li>
  <li><a href="#mqsend">mq_send</a></li>
  <li><a href="#mqsetattr">mq_setattr</a></li>
  <li><a href="#mqunlink">mq_unlink</a></li>
  <li><a href="#OS_Interfaces">OS Interfaces</a>
  <li><a href="#pthreadattrdestroy">pthread_attr_destroy</a></li>
  <li><a href="#pthreadattrgetinheritsched">pthread_attr_getinheritsched</a></li>
  <li><a href="#pthreadattrgetschedparam">pthread_attr_getschedparam</a></li>
  <li><a href="#pthreadattrgetschedpolicy">pthread_attr_getschedpolicy</a></li>
  <li><a href="#pthreadattrgetstacksize">0 pthread_attr_getstacksize</a></li>
  <li><a href="#pthreadattrinit">pthread_attr_init</a></li>
  <li><a href="#pthreadattrsetinheritsched">pthread_attr_setinheritsched</a></li>
  <li><a href="#pthreadattrsetschedparam">pthread_attr_setschedparam</a></li>
  <li><a href="#pthreadattrsetschedpolity">pthread_attr_setschedpolicy</a></li>
  <li><a href="#pthreadattrsetstacksize">pthread_attr_setstacksize</a></li>
  <li><a href="#pthreadcancel">pthread_cancel</a></li>
  <li><a href="#pthreadconaddrinit">pthread_condattr_init</a></li>
  <li><a href="#pthreadcondbroadcast">pthread_cond_broadcast</a></li>
  <li><a href="#pthreadconddestroy">pthread_cond_destroy</a></li>
  <li><a href="#pthreadcondinit">pthread_cond_init</a></li>
  <li><a href="#pthreadcondsignal">pthread_cond_signal</a></li>
  <li><a href="#pthreadcondtimedwait">pthread_cond_timedwait</a></li>
  <li><a href="#pthreadcondwait">pthread_cond_wait</a></li>
  <li><a href="#pthreadcreate">pthread_create</a></li>
  <li><a href="#pthreaddetach">pthread_detach</a></li>
  <li><a href="#pthreadexit">pthread_exit</a></li>
  <li><a href="#pthreadgetschedparam">pthread_getschedparam</a></li>
  <li><a href="#pthreadgetspecific">pthread_getspecific</a></li>
  <li><a href="#Pthread"><i>pthreads</i></a> share some resources.
  <li><a href="#pthreadjoin">pthread_join</a></li>
  <li><a href="#pthreadkeycreate">pthread_key_create</a></li>
  <li><a href="#pthreadkeydelete">pthread_key_delete</a></li>
  <li><a href="#pthreadmutexattrdestroy">pthread_mutexattr_destroy</a></li>
  <li><a href="#pthreadmutexattrgetpshared">pthread_mutexattr_getpshared</a></li>
  <li><a href="#pthreadmutexattrinit">pthread_mutexattr_init</a></li>
  <li><a href="#pthreadmutexattrsetpshared">pthread_mutexattr_setpshared</a></li>
  <li><a href="#pthreadmutexdestrory">pthread_mutex_destroy</a></li>
  <li><a href="#pthreadmutexinit">pthread_mutex_init</a></li>
  <li><a href="#pthreadmutexlock">pthread_mutex_lock</a></li>
  <li><a href="#pthreadmutextrylock">pthread_mutex_trylock</a></li>
  <li><a href="#pthreadmutexunlock">pthread_mutex_unlock</a></li>
  <li><a href="#pthreadocndattrdestroy">pthread_condattr_destroy</a></li>
  <li><a href="#Pthread">Pthread Interfaces</a>
  <li><a href="#pthreadself">pthread_self</a></li>
  <li><a href="#pthreadsetcancelstate">pthread_setcancelstate</a></li>
  <li><a href="#pthreadsetschedparam">pthread_setschedparam</a></li>
  <li><a href="#pthreadsetspecific">pthread_setspecific</a></li>
  <li><a href="#pthreadtestcancelstate">pthread_testcancelstate</a></li>
  <li><a href="#pthreadyield">pthread_yield</a></li>
  <li><a href="#schedgetparam">sched_getparam</a></li>
  <li><a href="#schedgetprioritymax">sched_get_priority_max</a></li>
  <li><a href="#schedgetprioritymin">sched_get_priority_min</a></li>
  <li><a href="#schedgetrrinterval">sched_get_rr_interval</a></li>
  <li><a href="#schedlockcount">sched_lockcount</a></li>
  <li><a href="#schedlock">sched_lock</a></li>
  <li><a href="#schedsetparam">sched_setparam</a></li>
  <li><a href="#schedsetscheduler">sched_setscheduler</a></li>
  <li><a href="#schedunlock">sched_unlock</a></li>
  <li><a href="#sched_yield">sched_yield</a></li>
  <li><a href="#Semaphores">Counting Semaphore Interfaces</a>
  <li><a href="#semclose">sem_close</a></li>
  <li><a href="#semdestroy">sem_destroy</a></li>
  <li><a href="#semgetvalue">sem_getvalue</a></li>
  <li><a href="#seminit">sem_init</a></li>
  <li><a href="#semopen">sem_open</a></li>
  <li><a href="#sempost">sem_post</a></li>
  <li><a href="#semtrywait">sem_trywait</a></li>
  <li><a href="#semunlink">sem_unlink</a></li>
  <li><a href="#semwait">sem_wait</a></li>
  <li><a href="#setgetscheduler">sched_getscheduler</a></li>
  <li><a href="#sigaction">sigaction</a></li>
  <li><a href="#sigaddset">sigaddset</a></li>
  <li><a href="#sigdelset">sigdelset</a></li>
  <li><a href="#sigemptyset">sigemptyset</a></li>
  <li><a href="#sigfillset">sigfillset</a></li>
  <li><a href="#sigismember">sigismember</a></li>
  <li><a href="#Signals">Signal Interfaces</a>
  <li><a href="#sigpending">sigpending</a></li>
  <li><a href="#sigprocmask">sigprocmask</a></li>
  <li><a href="#sigqueue">sigqueue</a></li>
  <li><a href="#sigsuspend">sigsuspend</a></li>
  <li><a href="#sigtimedwait">sigtimedwait</a></li>
  <li><a href="#sigwaitinfo">sigwaitinfo</a></li>
  <li><a href="#taskactivate">task_activate</a></li>
  <li><a href="#Task_Control">Task Control Interfaces</a>
  <li><a href="#taskcreate">task_create</a></li>
  <li><a href="#taskdelete">task_delete</a></li>
  <li><a href="#taskinit">task_init</a></li>
  <li><a href="#taskrestart">task_restart</a></li>
  <li><a href="#Task_Schedule">Task Scheduling Interfaces</a>
  <li><a href="#Task_Switch">Task Switching Interfaces</a>
  <li><a href="#Watchdogs">Watchdog Timer Interfaces</a>
  <li><a href="#wdcancel">wd_cancel</a></li>
  <li><a href="#wdcreate">wd_create</a></li>
  <li><a href="#wddelete">wd_delete</a></li>
  <li><a href="#wdstart">wd_start</a></li>
</ul>
patacongo's avatar
NuttX RTOS
patacongo committed
4416 4417 
</BODY>
</HTML>
Show full blame