diff options
Diffstat (limited to 'nuttx/Documentation/NuttxUserGuide.html')
-rw-r--r-- | nuttx/Documentation/NuttxUserGuide.html | 112 |
1 files changed, 56 insertions, 56 deletions
diff --git a/nuttx/Documentation/NuttxUserGuide.html b/nuttx/Documentation/NuttxUserGuide.html index de3e370b8..63a54e715 100644 --- a/nuttx/Documentation/NuttxUserGuide.html +++ b/nuttx/Documentation/NuttxUserGuide.html @@ -13,7 +13,7 @@ <h1><big><font color="#3c34ec"><i>NuttX Operating System<p>User's Manual</i></font></big></h1> <p><small>by</small></p> <p>Gregory Nutt<p> - <p>Last Updated: March 13, 2009</p> + <p>Last Updated: May 9, 2009</p> </td> </tr> </table> @@ -184,7 +184,7 @@ paragraphs. were started from the same parent thread. </p> <p> - The following task control interfaces are provided by Nuttx: + The following task control interfaces are provided by NuttX: </p> <ul> <li><a href="#taskcreate">2.1.1 task_create</a></li> @@ -231,7 +231,7 @@ paragraphs. The newly created task does not inherit scheduler characteristics from the parent task: The new task is started at the default system priority and with the SCHED_FIFO scheduling - policy. These characteristcs may be modified after the new + policy. These characteristics may be modified after the new task has been started. </p> <p> @@ -281,7 +281,7 @@ VxWorks provides the following similar interface: <ul> <li>Interface name <li>Various differences in types of arguments -<li>There is no options arguement. +<li>There is no options argument. <li>A variable number of parameters can be passed to a task (VxWorks supports ten). </ul> @@ -472,7 +472,7 @@ VxWorks provides the following similar interface: <p> <b>Description:</b> This function causes the calling task to cease to exist -- its stack and TCB will be deallocated. exit differs from -_exit in that it flushs streams, closes file descriptors and will +_exit in that it flushes streams, closes file descriptors and will execute any function registered with atexit(). <p> <b>Input Parameters:</b> @@ -491,7 +491,7 @@ execute any function registered with atexit(). <pre> void exit( int code ); </pre> -And the unix interface: +And the UNIX interface: <pre> void _exit( int code ); </pre> @@ -1065,7 +1065,7 @@ on this thread of execution. </table> <p> - NuttX supports POSIX named message queues for intertask communication. + NuttX supports POSIX named message queues for inter-task communication. Any task may send or receive messages on named message queues. Interrupt handlers may send messages via named message queues. </p> @@ -1699,7 +1699,7 @@ interface of the same name. Proper use of semaphores avoids the issues of <code>sched_lock()</code>. However, consider the following example: <OL> - <li>Some low-priority task, <I>Task C</I>, acquires a semphore in order to + <li>Some low-priority task, <I>Task C</I>, acquires a semaphore in order to get exclusive access to a protected resource.</li> <li><I>Task C</I> is suspended to allow some high-priority task,</li> <I>Task A</I>, to execute.</li> @@ -1727,7 +1727,7 @@ interface of the same name. The designer may, as examples: </p> <ul> - <li>Implement all tasks that need the semphore-managed resources at the + <li>Implement all tasks that need the semaphore-managed resources at the same priority level,</li> <li>Boost the priority of the low-priority task before the semaphore is acquired, or</li> @@ -1760,7 +1760,7 @@ interface of the same name. The setting <code>CONFIG_SEM_PREALLOCHOLDERS</code> defines the maximum number of different threads (minus one per semaphore instance) that can take counts on a semaphore with priority inheritance support. - This setting defines the size of a single pool of preallocated structures. + This setting defines the size of a single pool of pre-allocated structures. It may be set to zero if priority inheritance is disabled OR if you are only using semaphores as mutexes (only one holder) OR if no more than two threads participate using a counting semaphore. @@ -1797,7 +1797,7 @@ interface of the same name. These various structures tie the semaphore implementation more tightly to the behavior of the implementation. For examples, if a thread executes while holding counts on a semaphore, or if a thread exits without call <code>sem_destroy()</code> - then. Or what if the thread with the boosted priority reprioritizes itself? + then. Or what if the thread with the boosted priority re-prioritizes itself? The NuttX implement of priority inheritance attempts to handle all of these types of corner cases, but it is very likely that some are missed. The worst case result is that memory could by stranded within the priority @@ -2022,7 +2022,7 @@ interface of the same name. <p> <b>Description:</b> This function will remove the semaphore named by the input name parameter. If one or more tasks have the semaphore named by -name oepn when sem_unlink() is called, destruction of the semaphore will +name open when sem_unlink() is called, destruction of the semaphore will be postponed until all references have been destroyed by calls to sem_close(). <p> @@ -2326,7 +2326,7 @@ VxWorks provides the following comparable interface: Differences from the VxWorks interface include: <ul> <li>Does not make any checks to see if the watchdog is being used -before de-allocating it (i.e., never returns ERROR). +before deallocating it (i.e., never returns ERROR). </ul> <H3><a name="wdstart">2.6.3 wd_start</a></H3> @@ -2779,7 +2779,7 @@ VxWorks provides the following comparable interface: </p> <ul> <li><code>timerid</code>. The pre-thread timer, previously created by the call to timer_create(), to be be set.</li> - <li><code>flags</code>. Specifie characteristics of the timer (see above)</li> + <li><code>flags</code>. Specify characteristics of the timer (see above)</li> <li><code>value</code>. Specifies the timer value to set</li> <li><code>ovalue</code>. A location in which to return the time remaining from the previous timer setting (ignored).</li> </ul> @@ -3145,7 +3145,7 @@ action to be associated with the specified signal. If the argument oact is not NULL, the action previously associated with the signal is stored in the location pointed to by the argument oact. If the argument act is NULL, signal handling is unchanged by this function call; thus, the call -can be used to enquire about the current handling of a given signal. +can be used to inquire about the current handling of a given signal. <p> When a signal is caught by a signal-catching function installed by the sigaction() function, a new signal mask is calculated and installed for @@ -3384,7 +3384,7 @@ for si_code are defined in signal.h: <li><I>SI_USER</I>. Signal sent from kill, raise, or abort <li><I>SI_QUEUE</I>. Signal sent from sigqueue <li><I>SI_TIMER</I>. Signal is result of timer expiration - <li><I>SI_ASYNCIO</I>. Signal is the result of asynch IO completion + <li><I>SI_ASYNCIO</I>. Signal is the result of asynchronous IO completion <li><I>SI_MESGQ</I>. Signal generated by arrival of a message on an empty message queue. </ul> @@ -4121,7 +4121,7 @@ Identifies the thread to be canceled.</li> <p> <b>Returned Values:</b> <p> -If successful, the <I>ptnread_cancel()</I> function will return zero (<I>OK</I>). +If successful, the <I>pthread_cancel()</I> function will return zero (<I>OK</I>). Otherwise, an error number will be returned to indicate the error: <p> <ul> @@ -4136,8 +4136,8 @@ interface of the same name. Except:</p> <li>The thread-specific data destructor functions shall be called for thread. However, these destructors are not currently supported.</li> <li>Cancellation types are not supported. The thread will be canceled -at the time that pthread_cancel() is called or, if cancelation is disabled, at -the time when cancelation is re-enabled.</li> +at the time that pthread_cancel() is called or, if cancellation is disabled, at +the time when cancellation is re-enabled.</li> <li><tt>pthread_testcancel()</tt> is not supported.</li> <li>Thread cancellation at <i>cancellation points</i> is not supported.</li> </ul> @@ -4158,16 +4158,16 @@ state and returns the previous cancelability state at the location referenced by oldstate. Legal values for state are PTHREAD_CANCEL_ENABLE and PTHREAD_CANCEL_DISABLE.<.li> -<p>Any pending thread cancelation may occur at the time that the -cancelation state is set to PTHREAD_CANCEL_ENABLE.</p> +<p>Any pending thread cancellation may occur at the time that the +cancellation state is set to PTHREAD_CANCEL_ENABLE.</p> <b>Input Parameters:</b> <p> <ul> <li><I>state</I> -New cancelation state. One of PTHREAD_CANCEL_ENABLE or PTHREAD_CANCEL_DISABLE.<.li> +New cancellation state. One of PTHREAD_CANCEL_ENABLE or PTHREAD_CANCEL_DISABLE.<.li> <li><I>oldstate</I>. -Location to return the previous cancelation state. +Location to return the previous cancellation state. </ul> <p> <b>Returned Values:</b> @@ -4682,7 +4682,7 @@ interface of the same name. <H3><a name="pthreadmutexattrdestroy">2.9.27 pthread_mutexattr_destroy</a></H3> <p> -<b>Function Protoype:</b> +<b>Function Prototype:</b> <p> <pre> #include <pthread.h> @@ -4830,15 +4830,15 @@ returned to indicate the error: <li><code>type</code>. The mutex type value to set. The following values are supported: <ul> <li><code>PTHREAD_MUTEX_NORMAL</code>. This type of mutex does not detect deadlock. A thread - attempting to relock this mutex without first unlocking it will deadlock. + attempting to re-lock this mutex without first unlocking it will deadlock. Attempting to unlock a mutex locked by a different thread results in undefined behavior. Attempting to unlock an unlocked mutex results in undefined behavior. </li> <li><code>PTHREAD_MUTEX_ERRORCHECK</code>. This type of mutex provides error checking. - A thread attempting to relock this mutex without first unlocking it will return with an error. + A thread attempting to re-lock this mutex without first unlocking it will return with an error. A thread attempting to unlock a mutex which another thread has locked will return with an error. A thread attempting to unlock an unlocked mutex will return with an error.</li> - <li><code>PTHREAD_MUTEX_RECURSIVE</code>. A thread attempting to relock this mutex without first - unlocking it will succeed in locking the mutex. The relocking deadlock which can occur with mutexes + <li><code>PTHREAD_MUTEX_RECURSIVE</code>. A thread attempting to re-lock this mutex without first + unlocking it will succeed in locking the mutex. The re-locking deadlock which can occur with mutexes of type PTHREAD_MUTEX_NORMAL cannot occur with this type of mutex. Multiple locks of this mutex require the same number of unlocks to release the mutex before another thread can acquire the mutex. A thread attempting to unlock a mutex which another thread has locked will return with an error. @@ -4944,7 +4944,7 @@ interface of the same name. </p> <p> If the mutex type is <code>PTHREAD_MUTEX_NORMAL</code>, deadlock detection is not provided. - Attempting to relock the mutex causes deadlock. If a thread attempts to unlock + Attempting to re-lock the mutex causes deadlock. If a thread attempts to unlock a mutex that it has not locked or a mutex which is unlocked, undefined behavior results. </p> @@ -4954,14 +4954,14 @@ interface of the same name. </p> <p> If the mutex type is <code>PTHREAD_MUTEX_ERRORCHECK</code>, then error checking is provided. - If a thread attempts to relock a mutex that it has already locked, an error + If a thread attempts to re-lock a mutex that it has already locked, an error will be returned. If a thread attempts to unlock a mutex that it has not locked or a mutex which is unlocked, an error will be returned. </p> <p> If the mutex type is <code>PTHREAD_MUTEX_RECURSIVE</code>, then the mutex maintains the concept of a lock count. When a thread successfully acquires a mutex for the first time, - the lock count is set to one. Every time a thread relocks this mutex, the lock count + the lock count is set to one. Every time a thread re-locks this mutex, the lock count is incremented by one. Each time the thread unlocks the mutex, the lock count is decremented by one. When the lock count reaches zero, the mutex becomes available for other threads to acquire. If a thread attempts to unlock a mutex that it has @@ -5592,7 +5592,7 @@ interface of the same name. </pre> <p> <b>Description:</b> - The <code>pthread_barrier_wait()</code> function synchronizse participating + The <code>pthread_barrier_wait()</code> function synchronizes participating threads at the barrier referenced by <code>barrier</code>. The calling thread is blocked until the required number of threads have called <code>pthread_barrier_wait()</code> specifying the same <code>barrier</code>. @@ -5665,7 +5665,7 @@ interface of the same name. <li> <code>once_control</code>. Determines if <code>init_routine()</code> should be called. - <code>once_control</code> should be declared and intialized as follows: + <code>once_control</code> should be declared and initialized as follows: <ul><pre>pthread_once_t once_control = PTHREAD_ONCE_INIT; </pre></ul> <code>PTHREAD_ONCE_INIT</code> is defined in <code>pthread.h</code>. @@ -5795,7 +5795,7 @@ interface of the same name. <b>Returned Values:</b> </p> <p> - 0 (OK) on succes or EINVAL if <code>how</code> is invalid. + 0 (OK) on success or EINVAL if <code>how</code> is invalid. </p> <p> <b>Assumptions/Limitations:</b> @@ -5815,7 +5815,7 @@ interface of the same name. <p><b>Overview</b>. NuttX supports environment variables that can be used to control the behavior of programs. In the spirit of NuttX the environment variable behavior attempts to emulate the behavior of - environment variables in the mulit-processing OS: + environment variables in the multi-processing OS: </p> <ul> <li><b>Task environments</b>. @@ -5828,10 +5828,10 @@ interface of the same name. </li> <li><b>Thread environments</b>. When a pthread is created using <a href="#pthreadcreate">pthread_create</a>, the child - thread also inherits that envirnment of the parent. - However, the child does not recieve a copy of the environment but, rather, shares the same + thread also inherits that environment of the parent. + However, the child does not receive a copy of the environment but, rather, shares the same environment. - Changes to the environment are visiable to all threads with the same parentage. + Changes to the environment are visible to all threads with the same parentage. </li> </ul> <p><b>Programming Interfaces</b>. @@ -5875,7 +5875,7 @@ interface of the same name. </ul> <p> <b>Returned Values:</b> - The value of the valiable (read-only) or NULL on failure. + The value of the variable (read-only) or NULL on failure. </p> <h3><a name="putenv">2.10.2 <code>putenv</code></a></h3> @@ -5906,7 +5906,7 @@ interface of the same name. </ul> <p> <b>Returned Values:</b> - Zero on sucess. + Zero on success. </p> <h3><a name="clearenv">2.10.3 <code>clearenv</code></a></h3> @@ -6018,27 +6018,27 @@ interface of the same name. <p><b>Overview</b>. NuttX includes an optional, scalable file system. - This file-system may be omitted altogther; NuttX does not depend on the presence + This file-system may be omitted altogether; NuttX does not depend on the presence of any file system. </p> <p><b>Pseudo Root File System</b>. - Or, a simple <i>in-memory</i>, <i>psuedo</i> file system can be enabled. + Or, a simple <i>in-memory</i>, <i>pseudo</i> file system can be enabled. This simple file system can be enabled setting the CONFIG_NFILE_DESCRIPTORS option to a non-zero value. This is an <i>in-memory</i> file system because it does not require any storage medium or block driver support. Rather, file system contents are generated on-the-fly as referenced via standard file system operations (open, close, read, write, etc.). - In this sense, the file system is <i>psuedo</i> file system (in the + In this sense, the file system is <i>pseudo</i> file system (in the same sense that the Linux <code>/proc</code> file system is also - referred to as a psuedo file system). + referred to as a pseudo file system). </p> <p> - Any user supplied data or logic can be accessed via the psuedo-file system. + Any user supplied data or logic can be accessed via the pseudo-file system. Built in support is provided for character and block drivers in the - <code>/dev</code> psuedo file system directory. + <code>/dev</code> pseudo file system directory. </p> <p><b>Mounted File Systems</b> @@ -6046,7 +6046,7 @@ interface of the same name. devices that provide access to true file systems backed up via some mass storage device. NuttX supports the standard <code>mount()</code> command that allows - a block driver to be bound to a mountpoint within the psuedo file system + a block driver to be bound to a mount-point within the pseudo file system and to a a file system. At present, NuttX supports only the VFAT file system. </p> @@ -6055,10 +6055,10 @@ interface of the same name. From a programming perspective, the NuttX file system appears very similar to a Linux file system. However, there is a fundamental difference: - The NuttX root file system is a psuedo file system and true file systems may be - mounted in the psuedo file system. + The NuttX root file system is a pseudo file system and true file systems may be + mounted in the pseudo file system. In the typical Linux installation by comparison, the Linux root file system - is a true file system and psuedo file systems may be mounted in the true, + is a true file system and pseudo file systems may be mounted in the true, root file system. The approach selected by NuttX is intended to support greater scalability from the very tiny platform to the moderate platform. @@ -6165,7 +6165,7 @@ interface of the same name. <b>Returned Values:</b> </p> <p> - On success, the number of structures that have nonzero <cod>revents</code> fields. + On success, the number of structures that have nonzero <code>revents</code> fields. A value of 0 indicates that the call timed out and no file descriptors were ready. On error, -1 is returned, and <code>errno</code> is set appropriately: </p> @@ -6432,7 +6432,7 @@ struct fat_format_s bad FAT size in <code>fmt</code>, bad cluster size in <code>fmt</code> </li> <li><code>ENOENT</code> - - <code>pathname</code> does not refer to anything in the filesystem. + <code>pathname</code> does not refer to anything in the file-system. </li> <li><code>ENOTBLK</code> - <code>pathname</code> does not refer to a block driver @@ -6454,14 +6454,14 @@ struct fat_format_s access media under the following very restrictive conditions: <ol> <li> - The filesystem supports the <code>FIOC_MMAP</code> ioctl command. + The file-system supports the <code>FIOC_MMAP</code> ioctl command. Any file system that maps files contiguously on the media should support this <code>ioctl</code> command. By comparison, most file system scatter files over the media in non-contiguous sectors. As of this writing, ROMFS is the only file system that meets this requirement. </li> <li> - The underly block driver supports the <code>BIOC_XIPBASE</code> <code>ioctl</code> command + The underlying block driver supports the <code>BIOC_XIPBASE</code> <code>ioctl</code> command that maps the underlying media to a randomly accessible address. At present, only the RAM/ROM disk driver does this. </li> @@ -6588,7 +6588,7 @@ FAR void *mmap(FAR void *start, size_t length, int prot, int flags, int fd, off_ contained both of these values. </li> <li><code>ENODEV</code> - - The underlying filesystem of the specified file does not support memory mapping. + The underlying file-system of the specified file does not support memory mapping. </li> </ul> </p> @@ -7172,7 +7172,7 @@ Those socket APIs are discussed in the following paragraphs.</p> </pre> <p> <b>Description:</b> - <code>getsockopt()</code> retrieve thse value for the option specified by the + <code>getsockopt()</code> retrieve those value for the option specified by the <code>option</code> argument for the socket specified by the <code>sockfd</code> argument. If the size of the option value is greater than <code>value_len</code>, the value stored in the object pointed to by the <code>value</code> argument will be silently |