http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/aac53ed0/docs/os/core_os/memory_pool/os_memblock_put.md ---------------------------------------------------------------------- diff --git a/docs/os/core_os/memory_pool/os_memblock_put.md b/docs/os/core_os/memory_pool/os_memblock_put.md index 4aba497..2c834c8 100644 --- a/docs/os/core_os/memory_pool/os_memblock_put.md +++ b/docs/os/core_os/memory_pool/os_memblock_put.md @@ -11,14 +11,14 @@ Releases previously allocated element back to the pool. | Arguments | Description | |-----------|-------------| -| mp | Pointer to memory pool from which block was allocated | -| block_addr | Pointer to element getting freed | +| `mp` | Pointer to memory pool from which block was allocated | +| `block_addr` | Pointer to element getting freed | <br> #### Returned values -OS_OK: operation was a success: -OS_INVALID_PARAM: If either mp or block_addr were NULL, or the block being freed was outside the range of the memory buffer or not on a true block size boundary. +`OS_OK`: operation was a success: +`OS_INVALID_PARAM`: If either `mp` or `block_addr` were **NULL**, or the block being freed was outside the range of the memory buffer or not on a true block size boundary. <br> #### Example
http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/aac53ed0/docs/os/core_os/memory_pool/os_mempool_init.md ---------------------------------------------------------------------- diff --git a/docs/os/core_os/memory_pool/os_mempool_init.md b/docs/os/core_os/memory_pool/os_mempool_init.md index 809a067..b476b52 100644 --- a/docs/os/core_os/memory_pool/os_mempool_init.md +++ b/docs/os/core_os/memory_pool/os_mempool_init.md @@ -4,33 +4,33 @@ os_error_t os_mempool_init(struct os_mempool *mp, int blocks, int block_size, void *membuf, char *name) ``` -Initializes the memory pool. Memory pointed to by *membuf* is divided into *blocks* number of elements of size OS_ALIGN(*block_size*). The *name* is optional, and names the memory pool. +Initializes the memory pool. Memory pointed to by `membuf` is divided into `blocks` number of elements of size `OS_ALIGN(*block_size*)`. The `name` is optional, and names the memory pool. -It is assumed that the amount of memory pointed by *membuf* has at least *OS_MEMPOOL_BYTES(blocks, block_size)* number of bytes. +It is assumed that the amount of memory pointed by `membuf` has at least `OS_MEMPOOL_BYTES(blocks, block_size)` number of bytes. -*name* is not copied, so caller should make sure that the memory does not get reused. +`name` is not copied, so caller should make sure that the memory does not get reused. #### Arguments | Arguments | Description | |-----------|-------------| -| mp | Memory pool being initialized | -| blocks | Number of elements in the pool | -| block_size | Minimum size of an individual element in pool | -| membuf | Backing store for the memory pool elements | -| name | Name of the memory pool | +| `mp` | Memory pool being initialized | +| `blocks` | Number of elements in the pool | +| `block_size` | Minimum size of an individual element in pool | +| `membuf` | Backing store for the memory pool elements | +| `name` | Name of the memory pool | #### Returned values -OS_OK: operation was successful. -OS_INVALID_PARAM: invalid parameters. Block count or block size was negative, or membuf or mp was NULL. -OS_MEM_NOT_ALIGNED: membuf was not aligned on correct byte boundary. +`OS_OK`: operation was successful. +`OS_INVALID_PARAM`: invalid parameters. Block count or block size was negative, or `membuf` or `mp` was **NULL**. +`OS_MEM_NOT_ALIGNED`: `membuf` was not aligned on correct byte boundary. #### Notes -Note that os_mempool_init() does not allocate backing storage; *membuf* has to be allocated by the caller. +Note that `os_mempool_init()` does not allocate backing storage; `membuf` has to be allocated by the caller. -It's recommended that you use *OS_MEMPOOL_BYTES()* or *OS_MEMPOOL_SIZE()* to figure out how much memory to allocate for the pool. +It's recommended that you use `OS_MEMPOOL_BYTES()` or `OS_MEMPOOL_SIZE()` to figure out how much memory to allocate for the pool. #### Example http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/aac53ed0/docs/os/core_os/mqueue/mqueue.md ---------------------------------------------------------------------- diff --git a/docs/os/core_os/mqueue/mqueue.md b/docs/os/core_os/mqueue/mqueue.md index ac0de39..08a8e5f 100644 --- a/docs/os/core_os/mqueue/mqueue.md +++ b/docs/os/core_os/mqueue/mqueue.md @@ -1,14 +1,14 @@ # Mqueue -Mqueue (Mbuf event queue) is a set of API built on top of the mbuf and event queue code. A typical networking stack operation is to put a packet on a queue and post an event to the task handling that queue. Mqueue was designed to provide a common API so that individual packages would not each have to create similar code. +Mqueue (Mbuf event queue) is a set of APIs built on top of the mbuf and event queue code. A typical networking stack operation is to put a packet on a queue and post an event to the task handling that queue. Mqueue was designed to provide a common API so that individual packages would not each have to create similar code. -The mqueue data structure consists of a queue head pointer (a "stailq" queue; a singly linked list with head structure having a pointer to the start and end of the list) and an os event structure. Packets (packet header mbufs) are added to the queue using the *omp_next* pointer in the `os_mbuf_pkthdr` structure of the mbuf. The event is used to post to the task an event of type OS_EVENT_T_MQUEUE_DATA. +The mqueue data structure consists of a queue head pointer (a "stailq" queue; a singly linked list with head structure having a pointer to the start and end of the list) and an os event structure. Packets (packet header mbufs) are added to the queue using the `omp_next` pointer in the `os_mbuf_pkthdr` structure of the mbuf. The event is used to post to the task an event of type `OS_EVENT_T_MQUEUE_DATA`. <br> ### Using Mqueue -The following code sample will demonstrate how to use an mqueue. This is a simple example where packets are put on a "receive queue" and a task processes that "receive queue" by incrementing the total number of packet received and then freeing the packet. Not shown in the code example is a call my_task_rx_data_func. Presumably, some other code will call this API. +The following code sample will demonstrate how to use an mqueue. This is a simple example where packets are put on a "receive queue" and a task processes that "receive queue" by incrementing the total number of packet received and then freeing the packet. Not shown in the code example is a call `my_task_rx_data_func`. Presumably, some other code will call this API. <br> http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/aac53ed0/docs/os/core_os/mqueue/os_mqueue_get.md ---------------------------------------------------------------------- diff --git a/docs/os/core_os/mqueue/os_mqueue_get.md b/docs/os/core_os/mqueue/os_mqueue_get.md index 14bf963..e54ef8e 100644 --- a/docs/os/core_os/mqueue/os_mqueue_get.md +++ b/docs/os/core_os/mqueue/os_mqueue_get.md @@ -4,7 +4,7 @@ struct os_mbuf *os_mqueue_get(struct os_mqueue *mq) ``` -Retrieves a packet off an Mqueue. Returns a pointer to the mbuf at the head of the mbuf chain. NULL if no packets are on the queue. +Retrieves a packet off an Mqueue. Returns a pointer to the mbuf at the head of the mbuf chain. **NULL** if no packets are on the queue. <br> @@ -12,13 +12,13 @@ Retrieves a packet off an Mqueue. Returns a pointer to the mbuf at the head of t | Arguments | Description | |-----------|-------------| -| mq | Pointer to Mqueue structure | +| `mq` | Pointer to Mqueue structure | <br> #### Returned values -The packet at the head of the queue or NULL if no packets are on the queue. +The packet at the head of the queue or **NULL** if no packets are on the queue. <br> http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/aac53ed0/docs/os/core_os/mqueue/os_mqueue_init.md ---------------------------------------------------------------------- diff --git a/docs/os/core_os/mqueue/os_mqueue_init.md b/docs/os/core_os/mqueue/os_mqueue_init.md index 725c041..ff0b04f 100644 --- a/docs/os/core_os/mqueue/os_mqueue_init.md +++ b/docs/os/core_os/mqueue/os_mqueue_init.md @@ -3,7 +3,7 @@ ```c int os_mqueue_init(struct os_mqueue *mq, void *arg) ``` -Initializes an queue. Sets the event argument in the os event of the mqueue to *arg*. Sets type of event to OS_EVENT_T_MQUEUE_DATA. +Initializes an queue. Sets the event argument in the os event of the mqueue to `arg`. Sets type of event to `OS_EVENT_T_MQUEUE_DATA`. <br> @@ -11,8 +11,8 @@ Initializes an queue. Sets the event argument in the os event of the mqueue to * | Arguments | Description | |-----------|-------------| -| mq | Pointer to a mqueue structure | -| arg | Event argument | +| `mq` | Pointer to a mqueue structure | +| `arg` | Event argument | <br> http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/aac53ed0/docs/os/core_os/mqueue/os_mqueue_put.md ---------------------------------------------------------------------- diff --git a/docs/os/core_os/mqueue/os_mqueue_put.md b/docs/os/core_os/mqueue/os_mqueue_put.md index e2e9d54..d5f4b13 100644 --- a/docs/os/core_os/mqueue/os_mqueue_put.md +++ b/docs/os/core_os/mqueue/os_mqueue_put.md @@ -4,7 +4,7 @@ int os_mqueue_put(struct os_mqueue *mq, struct os_eventq *evq, struct os_mbuf *m) ``` -Adds a packet (i.e. packet header mbuf) to an mqueue. Post event to *evq*. +Adds a packet (i.e. packet header mbuf) to an mqueue. Post event to `evq`. <br> @@ -12,9 +12,9 @@ Adds a packet (i.e. packet header mbuf) to an mqueue. Post event to *evq*. | Arguments | Description | |-----------|-------------| -| mq | Pointer to mqueue | -| evq | Pointer to event queue where mqueue event should get posted | -| m | Pointer to packet header mbuf | +| `mq` | Pointer to mqueue | +| `evq` | Pointer to event queue where mqueue event should get posted | +| `m` | Pointer to packet header mbuf | <br> @@ -22,7 +22,7 @@ Adds a packet (i.e. packet header mbuf) to an mqueue. Post event to *evq*. 0: success -OS_EINVAL: the mbuf is not a packet header mbuf. +`OS_EINVAL`: the mbuf is not a packet header mbuf. <br> http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/aac53ed0/docs/os/core_os/msys/msys.md ---------------------------------------------------------------------- diff --git a/docs/os/core_os/msys/msys.md b/docs/os/core_os/msys/msys.md index 6c3b2ca..483fa2b 100644 --- a/docs/os/core_os/msys/msys.md +++ b/docs/os/core_os/msys/msys.md @@ -1,10 +1,10 @@ # Msys -Msys stands for "system mbufs" and is a set of API built on top of the mbuf code. The basic idea behind msys is the following. The developer can create different size mbuf pools and register them with msys. The application then allocates mbufs using the msys API (as opposed to the mbuf API). The msys code will choose the mbuf pool with the smallest mbufs that can accommodate the requested size. +Msys stands for "system mbufs" and is a set of APIs built on top of the mbuf code. The basic idea behind msys is the following. The developer can create different size mbuf pools and register them with msys. The application then allocates mbufs using the msys API (as opposed to the mbuf API). The msys code will choose the mbuf pool with the smallest mbufs that can accommodate the requested size. Let us walk through an example where the user registers three mbuf pools with msys: one with 32 byte mbufs, one with 256 and one with 2048. If the user requests an mbuf with 10 bytes, the 32-byte mbuf pool is used. If the request is for 33 bytes the 256 byte mbuf pool is used. If an mbuf data size is requested that is larger than any of the pools (say, 4000 bytes) the largest pool is used. While this behaviour may not be optimal in all cases that is the currently implemented behaviour. All this means is that the user is not guaranteed that a single mbuf can hold the requested data. -The msys code will not allocate an mbuf from a larger pool if the chosen mbuf pool is empty. Similarly, the msys code will not chain together a number of smaller mbufs to accommodate the requested size. While this behaviour may change in future implementations the current code will simply return NULL. Using the above example, say the user requests 250 bytes. The msys code chooses the appropriate pool (i.e. the 256 byte mbuf pool) and attempts to allocate an mbuf from that pool. If that pool is empty, NULL is returned even though the 32 and 2048 byte pools are not empty. +The msys code will not allocate an mbuf from a larger pool if the chosen mbuf pool is empty. Similarly, the msys code will not chain together a number of smaller mbufs to accommodate the requested size. While this behaviour may change in future implementations the current code will simply return **NULL**. Using the above example, say the user requests 250 bytes. The msys code chooses the appropriate pool (i.e. the 256 byte mbuf pool) and attempts to allocate an mbuf from that pool. If that pool is empty, **NULL** is returned even though the 32 and 2048 byte pools are not empty. Note that no added descriptions on how to use the msys API are presented here (other than in the API descriptions themselves) as the msys API is used in exactly the same manner as the mbuf API. The only difference is that mbuf pools are added to msys by calling `os_msys_register().` http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/aac53ed0/docs/os/core_os/msys/os_msys_get.md ---------------------------------------------------------------------- diff --git a/docs/os/core_os/msys/os_msys_get.md b/docs/os/core_os/msys/os_msys_get.md index b69c9a0..188071f 100644 --- a/docs/os/core_os/msys/os_msys_get.md +++ b/docs/os/core_os/msys/os_msys_get.md @@ -4,7 +4,7 @@ struct os_mbuf *os_msys_get(uint16_t dsize, uint16_t leadingspace) ``` -Retrieve an mbuf from the system mbuf pools with *leadingspace* bytes available in the mbuf. +Retrieve an mbuf from the system mbuf pools with `leadingspace` bytes available in the mbuf. <br> @@ -12,18 +12,18 @@ Retrieve an mbuf from the system mbuf pools with *leadingspace* bytes available | Arguments | Description | |-----------|-------------| -| dsize | Minimum requested size of mbuf. Actual mbuf allocated may not accommodate *dsize* | -| leadingspace | Number of bytes for leading space in mbuf (space at start of mbuf) | +| `dsize` | Minimum requested size of mbuf. Actual mbuf allocated may not accommodate *dsize* | +| `leadingspace` | Number of bytes for leading space in mbuf (space at start of mbuf) | <br> #### Returned values -Pointer to mbuf or NULL if no mbufs were available. +Pointer to mbuf or **NULL** if no mbufs were available. <br> #### Notes -As described in the overview section, `os_msys_get()` may return an mbuf that is smaller than dsize, meaning that the mbuf user data buffer does not have enough contiguous space to hold *dsize* bytes. +As described in the overview section, `os_msys_get()` may return an mbuf that is smaller than `dsize`, meaning that the mbuf user data buffer does not have enough contiguous space to hold `dsize` bytes. This API will not return an mbuf from a larger mbuf pool if the appropriate msys mbuf pool is empty. See the overview for more information. http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/aac53ed0/docs/os/core_os/msys/os_msys_get_pkthdr.md ---------------------------------------------------------------------- diff --git a/docs/os/core_os/msys/os_msys_get_pkthdr.md b/docs/os/core_os/msys/os_msys_get_pkthdr.md index 38a5302..cda7b8d 100644 --- a/docs/os/core_os/msys/os_msys_get_pkthdr.md +++ b/docs/os/core_os/msys/os_msys_get_pkthdr.md @@ -4,7 +4,7 @@ struct os_mbuf *os_msys_get_pkthdr(uint16_t dsize, uint16_t user_hdr_len) ``` -Retrieve a packet header mbuf from the system mbuf pools with *user_hdr_len* bytes available for the user header in the mbuf. +Retrieve a packet header mbuf from the system mbuf pools with `user_hdr_len` bytes available for the user header in the mbuf. <br> @@ -12,13 +12,13 @@ Retrieve a packet header mbuf from the system mbuf pools with *user_hdr_len* byt | Arguments | Description | |-----------|-------------| -| dsize | Minimum requested size of mbuf. Actual mbuf allocated may not accommodate *dsize* | -| user_hdr_len | Size, in of bytes, of user header in the mbuf | +| `dsize` | Minimum requested size of mbuf. Actual mbuf allocated may not accommodate *dsize* | +| `user_hdr_len` | Size, in of bytes, of user header in the mbuf | <br> #### Returned values -Pointer to mbuf or NULL if no mbufs were available. +Pointer to mbuf or **NULL** if no mbufs were available. <br> http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/aac53ed0/docs/os/core_os/msys/os_msys_register.md ---------------------------------------------------------------------- diff --git a/docs/os/core_os/msys/os_msys_register.md b/docs/os/core_os/msys/os_msys_register.md index 4125f22..7335772 100644 --- a/docs/os/core_os/msys/os_msys_register.md +++ b/docs/os/core_os/msys/os_msys_register.md @@ -12,7 +12,7 @@ Register an mbuf pool for use as a system mbuf pool. The pool should be initiali | Arguments | Description | |-----------|-------------| -| new_pool | Pointer to mbuf pool to add to system mbuf pools | +| `new_pool` | Pointer to mbuf pool to add to system mbuf pools | <br> http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/aac53ed0/docs/os/core_os/mutex/mutex.md ---------------------------------------------------------------------- diff --git a/docs/os/core_os/mutex/mutex.md b/docs/os/core_os/mutex/mutex.md index 961ebc5..b75f4e2 100644 --- a/docs/os/core_os/mutex/mutex.md +++ b/docs/os/core_os/mutex/mutex.md @@ -8,7 +8,7 @@ Mutex is short for "mutual exclusion"; a mutex provides mutually exclusive acces The first order of business when using a mutex is to declare the mutex globally. The mutex needs to be initialized before it is used (see the examples). It is generally a good idea to initialize the mutex before tasks start running in order to avoid a task possibly using the mutex before it is initialized. -When a task wants exclusive access to a shared resource it needs to obtain the mutex by calling *os_mutex_pend*. If the mutex is currently owned by a different task (a lower priority task), the requesting task will be put to sleep and the owners priority will be elevated to the priority of the requesting task. Note that multiple tasks can request ownership and the current owner is elevated to the highest priority of any task waitin on the mutex. When the task is done using the shared resource, it needs to release the mutex by called *os_mutex_release*. There needs to be one release per call to pend. Note that nested calls to *os_mutex_pend* are allowed but there needs to be one release per pend. +When a task wants exclusive access to a shared resource it needs to obtain the mutex by calling `os_mutex_pend`. If the mutex is currently owned by a different task (a lower priority task), the requesting task will be put to sleep and the owners priority will be elevated to the priority of the requesting task. Note that multiple tasks can request ownership and the current owner is elevated to the highest priority of any task waitin on the mutex. When the task is done using the shared resource, it needs to release the mutex by called `os_mutex_release`. There needs to be one release per call to pend. Note that nested calls to `os_mutex_pend` are allowed but there needs to be one release per pend. The following example will illustrate how priority inheritance works. In this example, the task number is the same as its priority. Remember that the lower the number, the higher the priority (i.e. priority 0 is higher priority than priority 1). Suppose that task 5 gets ownership of a mutex but is preempted by task 4. Task 4 attempts to gain ownership of the mutex but cannot as it is owned by task 5. Task 4 is put to sleep and task 5 is temporarily raised to priority 4. Before task 5 can release the mutex, task 3 runs and attempts to acquire the mutex. At this point, both task 3 and task 4 are waiting on the mutex (sleeping). Task 5 now runs at priority 3 (the highest priority of all the tasks waiting on the mutex). When task 5 finally releases the mutex it will be preempted as two higher priority tasks are waiting for it. http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/aac53ed0/docs/os/core_os/mutex/os_mutex_init.md ---------------------------------------------------------------------- diff --git a/docs/os/core_os/mutex/os_mutex_init.md b/docs/os/core_os/mutex/os_mutex_init.md index 284e225..37d9872 100644 --- a/docs/os/core_os/mutex/os_mutex_init.md +++ b/docs/os/core_os/mutex/os_mutex_init.md @@ -10,13 +10,13 @@ Initialize the mutex. Must be called before the mutex can be used. | Arguments | Description | |-----------|-------------| -| *mu| Pointer to mutex | +| `*mu`| Pointer to mutex | #### Returned values -OS_INVALID_PARM: returned when *mu is NULL on entry. +`OS_INVALID_PARM`: returned when `*mu` is **NULL** on entry. -OS_OK: mutex initialized successfully. +`OS_OK`: mutex initialized successfully. #### Notes http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/aac53ed0/docs/os/core_os/mutex/os_mutex_pend.md ---------------------------------------------------------------------- diff --git a/docs/os/core_os/mutex/os_mutex_pend.md b/docs/os/core_os/mutex/os_mutex_pend.md index 2b3af83..4e1b0f3 100644 --- a/docs/os/core_os/mutex/os_mutex_pend.md +++ b/docs/os/core_os/mutex/os_mutex_pend.md @@ -11,23 +11,23 @@ Acquire ownership of a mutex. | Arguments | Description | |-----------|-------------| -| *mu | Pointer to mutex | -| timeout | Timeout, in os ticks. A value of 0 means no timeout. A value of 0xFFFFFFFF means to wait forever. | +| `*mu` | Pointer to mutex | +| `timeout` | Timeout, in os ticks. A value of 0 means no timeout. A value of 0xFFFFFFFF means to wait forever. | #### Returned values -OS_INVALID_PARM: returned when *mu is NULL on entry. +`OS_INVALID_PARM`: returned when `*mu` is **NULL** on entry. -OS_OK: mutex was successfully acquired. +`OS_OK`: mutex was successfully acquired. -OS_TIMEOUT: the mutex was not available within the timeout specified. +`OS_TIMEOUT`: the mutex was not available within the timeout specified. -OS_NOT_STARTED: Attempt to release a mutex before the os has been started. +`OS_NOT_STARTED`: Attempt to release a mutex before the os has been started. #### Notes -If the mutex is owned by another task and the timeout is 0 the function returns immediately with the error code OS_TIMEOUT. The calling task *does not* own the mutex when this occurs. +If the mutex is owned by another task and the timeout is 0 the function returns immediately with the error code `OS_TIMEOUT`. The calling task *does not* own the mutex when this occurs. #### Example http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/aac53ed0/docs/os/core_os/mutex/os_mutex_release.md ---------------------------------------------------------------------- diff --git a/docs/os/core_os/mutex/os_mutex_release.md b/docs/os/core_os/mutex/os_mutex_release.md index 356ae49..ba5f294 100644 --- a/docs/os/core_os/mutex/os_mutex_release.md +++ b/docs/os/core_os/mutex/os_mutex_release.md @@ -11,16 +11,16 @@ Release ownership of a mutex | Arguments | Description | |-----------|-------------| -| *mu| Pointer to mutex | +| `*mu`| Pointer to mutex | #### Returned values -OS_INVALID_PARM: returned when *mu is NULL on entry. +`OS_INVALID_PARM`: returned when `*mu` is **NULL** on entry. -OS_OK: mutex initialized successfully. +`OS_OK`: mutex initialized successfully. -OS_BAD_MUTEX: The mutex was not owned by the task attempting to release it. +`OS_BAD_MUTEX`: The mutex was not owned by the task attempting to release it. -OS_NOT_STARTED: Attempt to release a mutex before the os has been started. +`OS_NOT_STARTED`: Attempt to release a mutex before the os has been started. #### Example http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/aac53ed0/docs/os/core_os/mynewt_os.md ---------------------------------------------------------------------- diff --git a/docs/os/core_os/mynewt_os.md b/docs/os/core_os/mynewt_os.md index 2f22abb..ecc695b 100644 --- a/docs/os/core_os/mynewt_os.md +++ b/docs/os/core_os/mynewt_os.md @@ -1,6 +1,6 @@ # Mynewt Core OS -The Mynewt Core OS is a multitasking, preemptive real-time operating system combining a scheduler with typical RTOS features such as mutexes, semaphores, memory pools, etc. The Mynewt Core OS also provides a number of useful utilities such as a task watchdog, networking stack memory buffers and time management API. Each of these features is described in detail in its own section of the manual. +The Mynewt Core OS is a multitasking, preemptive real-time operating system combining a scheduler with typical RTOS features such as mutexes, semaphores, memory pools, etc. The Mynewt Core OS also provides a number of useful utilities such as a task watchdog, networking stack, memory buffers and time management API. Each of these features is described in detail in its own section of the manual. A multitasking, preemptive operating system is one in which a number of different tasks can be instantiated and assigned a priority, with higher priority tasks running before lower priority tasks. Furthermore, if a lower priority task is running and a higher priority task wants to run, the lower priority task is halted and the higher priority task is allowed to run. In other words, the lower priority task is preempted by the higher priority task. @@ -41,9 +41,9 @@ Consider the sequence of events when the OS is started. The scheduler starts run One way to avoid initialization issues like the one described above is to perform task initializations prior to starting the OS. The code example shown below illustrates this concept. The application initializes the OS, calls an application specific "task initialization" function, and then starts the OS. The application task initialization function is responsible for initializing all the data objects that each task exposes to the other tasks. The tasks themselves are also initialized at this time (by calling `os_task_init()`). -In the example, each task works in a ping-pong like fashion: task 1 wakes up, adds a token to semaphore 1 and then waits for a token from semaphore 2. Task 2 waits for a token on semaphore 1 and once it gets it, adds a token to semaphore 2. Notice that the semaphores are initialized by the application specific task initialization functions and not inside the task handler functions. If task 2 (being lower in priority than task 1) had called os_sem_init() for task2_sem inside task2_handler(), task 1 would have called os_sem_pend() using task2_sem before task2_sem was initialized. - +In the example, each task works in a ping-pong like fashion: task 1 wakes up, adds a token to semaphore 1 and then waits for a token from semaphore 2. Task 2 waits for a token on semaphore 1 and once it gets it, adds a token to semaphore 2. Notice that the semaphores are initialized by the application specific task initialization functions and not inside the task handler functions. If task 2 (being lower in priority than task 1) had called `os_sem_init()` for task2_sem inside `task2_handler()`, task 1 would have called `os_sem_pend()` using task2_sem before task2_sem was initialized. +```c /* Task 1 handler function */ void task1_handler(void *arg) @@ -145,7 +145,7 @@ In the example, each task works in a ping-pong like fashion: task 1 wakes up, ad return rc; } - +``` ###OS Functions http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/aac53ed0/docs/os/core_os/os_init.md ---------------------------------------------------------------------- diff --git a/docs/os/core_os/os_init.md b/docs/os/core_os/os_init.md index eaad890..36a9430 100644 --- a/docs/os/core_os/os_init.md +++ b/docs/os/core_os/os_init.md @@ -1,10 +1,10 @@ ## <font color="#F2853F" style="font-size:24pt">os_init</font> -```no-highlight +```c void os_init(void) ``` -Initializes the OS. Must be called before the OS is started (i.e. os_start() is called). +Initializes the OS. Must be called before the OS is started (i.e. `os_start()` is called). <br> @@ -21,6 +21,6 @@ None #### Notes -The call to os_init performs architecture and bsp initializations and initializes the idle task. +The call to `os_init()` performs architecture and bsp initializations and initializes the idle task. This function does not start the OS, the OS time tick interrupt, or the scheduler. http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/aac53ed0/docs/os/core_os/os_start.md ---------------------------------------------------------------------- diff --git a/docs/os/core_os/os_start.md b/docs/os/core_os/os_start.md index cc6db5e..e1480b4 100644 --- a/docs/os/core_os/os_start.md +++ b/docs/os/core_os/os_start.md @@ -1,6 +1,6 @@ ## <font color="#F2853F" style="font-size:24pt">os_start</font> -```no-highlight +```c void os_start(void) ``` @@ -23,5 +23,5 @@ None (does not return). #### Notes -Once os_start has been called, context is switched to the highest priority task that was initialized prior to calling os_start. +Once `os_start()` has been called, context is switched to the highest priority task that was initialized prior to calling `os_start()`. http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/aac53ed0/docs/os/core_os/os_started.md ---------------------------------------------------------------------- diff --git a/docs/os/core_os/os_started.md b/docs/os/core_os/os_started.md index 5584782..d8d24ca 100644 --- a/docs/os/core_os/os_started.md +++ b/docs/os/core_os/os_started.md @@ -1,6 +1,6 @@ -## <font color="#F2853F" style="font-size:24pt">os_started</font> +##<font color="#F2853F" style="font-size:24pt">os_started</font> -```no-highlight +```c int os_started(void) ``` @@ -15,5 +15,5 @@ None <br> #### Returned values -Integer value with 0 meaning the OS has not been started and 1 indicating the OS has been started (i.e. os_start() has been called). +Integer value with 0 meaning the OS has not been started and 1 indicating the OS has been started (i.e. `os_start()` has been called). http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/aac53ed0/docs/os/core_os/porting/port_bsp.md ---------------------------------------------------------------------- diff --git a/docs/os/core_os/porting/port_bsp.md b/docs/os/core_os/porting/port_bsp.md index 1a34a9d..638ecb9 100644 --- a/docs/os/core_os/porting/port_bsp.md +++ b/docs/os/core_os/porting/port_bsp.md @@ -3,7 +3,10 @@ ###Introduction -If you are using a board or system not currently supported by Mynewt, you will need to create a BSP for the new target. If another similar BSP exists it is recommended to copy that BSP as a starting point. For example, if another BSP exists using the same MCU, start with a copy of that BSP. +If you are using a board or system not currently supported by Mynewt, you will need to +create a BSP for the new target. If another similar BSP exists it is recommended to +copy that BSP as a starting point. For example, if another BSP exists using the same MCU, +start with a copy of that BSP. Either way, this document describes the steps necessary to create a new BSP from scratch. @@ -18,32 +21,35 @@ To build a proper BSP, you will typically need the following: ###Name your BSP -Select a name for your BSP. For the remainder of this document, we'll assume the bsp is named `myboard`. In general its best to select a name that describes the board/system you are creating. +Select a name for your BSP. For the remainder of this document, we'll assume the bsp is named `myboard`. +In general its best to select a name that describes the board/system you are creating. ###Create a BSP directory Create a directory `hw/bsp/myboard` using the name chosen above. Within this BSP directory, create the following subdirectories: -Select a name for your BSP. For the remainder of this document, -well assume the bsp is named `myboard`. In general its best to select a -name that describes the board/system you are creating. - * `include` * `include/bsp` * `src` ###Create a Target using Mynewt -Create a newt target for your test project for the BSP. To learn how to create a target, see this **howto** [Tutorial](../../get_started/project_create). Once you are familiar with creating targets, move on below to create a target to use to test your BSP. +Create a newt target for your test project for the BSP. To learn how to create a target, +see this **howto** [Tutorial](../../get_started/project_create). Once you are familiar +with creating targets, move on below to create a target to use to test your BSP. -It is recommended that you use a simple `project` like `blinky` to minimize time to get a working Mynewt system. For this document, we will assume the `target` is called `myboard_blinky` and uses project `blinky`. +It is recommended that you use a simple project like [blinky](../tutorials/blinky_primo.md) to minimize the time +to get a working Mynewt system. For this document, we will assume the *target* is called *myboard_blinky* +and uses project *blinky*. -Set the `bsp` of the project to `/hw/bsp/myboard`. While creating your target, you will need to specify your `arch`and `compiler`. If your platform requires an architecture or compiler that are not defined in Mynewt, you will need to add them first. To add a CPU architecture see [CPU Porting](port_cpu.md). +Set the `bsp` of the project to `/hw/bsp/myboard`. While creating your target, you will need to +specify your `arch`and `compiler`. If your platform requires an architecture or compiler +that are not defined in Mynewt, you will need to add them first. To add a CPU architecture see [CPU Porting](port_cpu.md). -When you are complete, your `target` may look similar to this. +When this is complete, your *target* may look similar to this. ```c - $newt target show + $ newt target show myboard_blinky arch=cortex_m0 bsp=hw/bsp/myboard @@ -84,21 +90,23 @@ Edit the package file to describe your BSP. The package file must contain: -```c +```no-highlight pkg.name: "hw/bsp/myboard" pkg.linkerscript: "myboard.ld" ``` | **Attribute** | **Description** | |-----------|-------------| -| pkg.name | The name of your bsp package | -| pkg.linkerscript | The linker script that controls the memory placement of the compiled code sections from the Mynewt OS and your applications. | +| `pkg.name` | The name of your bsp package | +| `pkg.linkerscript` | The linker script that controls the memory placement of the compiled code sections from the Mynewt OS and your applications. | -The linker script is a key component of the BSP and specifies where each section of code and data are stored within your CPU which can vary with the BSP depending on your chosen memory layout. For a tutorial on writing linker scripts, see [Create or Copy Linker Script(s)](#create-or-copy-linker-script). +The linker script is a key component of the BSP and specifies where each section of code and data are +stored within your CPU which can vary with the BSP depending on your chosen memory layout. +For a tutorial on writing linker scripts, see [Create or Copy Linker Script(s)](#create-or-copy-linker-script). The package file typically contains: -```c +```no-highlight pkg.linkerscript.bootloader.OVERWRITE: "myboard_boot.ld" pkg.downloadscript: "myboard_download.sh" pkg.debugscript: "myboard_debug.sh" @@ -111,29 +119,33 @@ The following table describes additional attributes relevant to the BSP `pkg.yml | **Attribute** | **Description** | |-----------|-------------| -| pkg.linkerscript.bootloader.OVERWRITE | A special linker for creating a bootloader for Mynewt | -| pkg.downloadscript | A script that can download a flash image into your target platform | -| pkg.debugscript | A script that can run the GDB debugger on your board | -| pkg.deps | Any dependencies on your BSP | +| `pkg.linkerscript.bootloader.OVERWRITE` | A special linker for creating a bootloader for Mynewt | +| `pkg.downloadscript` | A script that can download a flash image into your target platform | +| `pkg.debugscript` | A script that can run the GDB debugger on your board | +| `pkg.deps` | Any dependencies on your BSP | -The BSP will invariably depend upon an MCU ( in this sample it's `hw/mcu/mymcu/variant`) since the Mynewt OS runs on an MCU within your target. If your MCU is not supported by Mynewt, see [MCU Porting](port_mcu.md) for details on how to create an MCU in Mynewt. +The BSP will invariably depend upon an MCU (in this sample it's `hw/mcu/mymcu/variant`) since the +Mynewt OS runs on an MCU within your target. If your MCU is not supported by Mynewt, +see [MCU Porting](port_mcu.md) for details on how to create a new MCU in Mynewt. The package file may also contain: -```c +```no-highlight pkg.cflags: -D__MY_SPECIAL_BSP_OPTIONS_ pkg.deps: - libs/cmsis-core ``` + | **Attribute** | **Description** | |-----------|-------------| -| pkg.cflags | Any specific compiler flags for your bsp | -| pkg.deps | Any other libraries that may be required. Some architectures (like ARM) have special libraries to make BSP creation easier. | +| `pkg.cflags` | Any specific compiler flags for your bsp | +| `pkg.deps` | Any other libraries that may be required. Some architectures (like ARM) have special libraries to make BSP creation easier. | ###Create or Copy Linker Script -It's probably best to start with a linker script from another BSP using the same MCU. If this is not available, consult your MCU documentation and library samples to find a linker script to start with. +It's probably best to start with a linker script from another BSP using the same MCU. If this is not available, +consult your MCU documentation and library samples to find a linker script to start with. Typically, a linker script has to specify the following sections for code: @@ -142,19 +154,22 @@ Typically, a linker script has to specify the following sections for code: * .bss -- the location and alignment of the memory section to store uninitialized data * .heap -- the location and alignment of the memory section to provide system memory -The linker script should specify the location and size of the different memory regions in your BSP and map the code sections described above into these regions. +The linker script should specify the location and size of the different memory regions +in your BSP and map the code sections described above into these regions. -The linker script should also include an ENTRY point. This is used by the debugger to know where to start the program counter when the target is debugged. +The linker script should also include an ENTRY point. This is used by the debugger +to know where to start the program counter when the target is debugged. -There may be additional requirements from the MCU or OS that you may find easiest to place in the linker script. Some specific variables that the OS and MCU depends on are : +There may be additional requirements from the MCU or OS that you may find easiest to +place in the linker script. Some specific variables that the OS and MCU depends on are : | **Variable** | **Description** | |-----------|-------------| -|\__bss_start__ | a variable located at the start of the BSS section | -|\__bss_end__ | a variable located at the end of the BSS section | -|\__isr_vector | Some CPUs map their interrupt vectors. They may need to be specified in the linker | -|\_user_heap_start | the start of the heap for unallocated memory | -|\_user_heap_end | the end of the heap for unallocated memory | +|`__bss_start__` | a variable located at the start of the BSS section | +|`__bss_end__` | a variable located at the end of the BSS section | +|`__isr_vector` | Some CPUs map their interrupt vectors. They may need to be specified in the linker | +|`_user_heap_start` | the start of the heap for unallocated memory | +|`_user_heap_end` | the end of the heap for unallocated memory | Create an alternate linker script for the bootloader since it is typically linked to use different addresses to boot the main image. @@ -166,24 +181,27 @@ You may run into complaints from the linker script that a few Mynewt specific fu | **Function** | **Description** | |-----------|-------------| -| os_bsp_init() | code to initialize the bsp | -| os_bsp_systick_init() | code to setup the system tick for the OS | +| `os_bsp_init()` | code to initialize the bsp | +| `os_bsp_systick_init()` | code to setup the system tick for the OS | -There are also several libc definitions that can be stubbed in your first BSP. Examples are `_write`, `_read`, etc. that can be found in `libc_stubs.c`. But you _must_ implement the following function to provide memory to the OS and system. +There are also several libc definitions that can be stubbed in your first BSP. Examples are `_write`, `_read`, +etc. that can be found in `libc_stubs.c`. But you _must_ implement the following function to provide memory to the OS and system. | **Function** | **Description** | |-----------|-------------| -| _sbrk | Returns memory from heap (used by malloc) | +| `_sbrk` | Returns memory from heap (used by malloc) | * Implement `_sbrk()` -`sbrk()` is required by libc to get memory from the heap for things like malloc. Although not strongly BSP dependent, this is currently in the BSP to allow flexibility in providing system memory. See other BSPs for providing `sbrk` functionality. +`sbrk()` is required by libc to get memory from the heap for things like malloc. Although not strongly BSP dependent, +this is currently in the BSP to allow flexibility in providing system memory. See other BSPs for providing `sbrk` functionality. * Implement `os_bsp_init()` -`os_bsp_init` should initialize anything required by the OS by the BSP. Typically this is a very small set. +`os_bsp_init` should initialize anything required in the OS by the BSP. Typically this is a very small set. -NOTE: Currently we are making calls to `_sbrk()` and `close(0)` from `os_bsp_init` to get around a linker issue where some of libc is not getting included. Please include this in your `os_bsp_init`. +**NOTE**: Currently we are making calls to `_sbrk()` and `close(0)` from `os_bsp_init` to get around a +linker issue where some of libc is not getting included. Please include this in your `os_bsp_init`. ```c /* @@ -200,20 +218,27 @@ There may be other unresolved defines or functions that are required by the spec | **Undefined Variable** | **Description** | |-----------|-------------| -| CONSOLE_UART_PORT | Which communications port on your target runs the console | -| LED_BLINK_PIN | which pin on your target runs the blinky LED | +| `CONSOLE_UART_PORT` | Which communications port on your target runs the console | +| `LED_BLINK_PIN` | which pin on your target runs the blinky LED | -The set of missing functionality depends upon the libraries and dependencies you have included in the project. That's why its best to keep your first project pretty simple then add incrementally. For example, if you include Newtron file system, you will need to define a file system map for your BSP. +The set of missing functionality depends upon the libraries and dependencies you have included in the project. +That's why its best to keep your first project pretty simple then add incrementally. +For example, if you include the Newtron file system, you will need to define a file system map for your BSP. Missing functionality may take the form of `#define` items required to compile, or they may take the form of missing functions. * `cmsis_nvic.h` -If you are using an ARM cortex architecture, you need to define the number of interrupts supported by your system. If you are not using ARM Cortex architecture this may not be required (but something else might be). +If you are using an ARM cortex architecture, you need to define the number of interrupts supported by your system. +If you are not using ARM Cortex architecture this may not be required (but something else might be). ###Add Debug Script -The debug script in the bsp directory allows the newt tool to automatically connect to the debugger, and create a debug session with the target. This requires knowledge of your target debug interface. Most of the Mynewt BSP targets use [openocd](http://openocd.org) to perform debugging. This script typically creates an openocd connection to the target and then connects a gdb instance to this openocd connection. There are several examples in existing BSPs to follow. +The debug script in the bsp directory allows the newt tool to automatically connect to the debugger +and create a debug session with the target. This requires knowledge of your target debug interface. +Most of the Mynewt BSP targets use [openocd](http://openocd.org) to perform debugging. +This script typically creates an openocd connection to the target and then connects a gdb instance +to this openocd connection. There are several examples in existing BSPs to follow. The script must take a single argument which is the name of the image file minus the '.elf' suffix. @@ -221,10 +246,13 @@ The BSP is complete without this file, but newt will be unable to establish a de ###Add Download Script -Similar to the debug script, the download script is a hook for newt to download the image to the target system. The download script also typically uses openocd interface to erase flash, and progam the code into the device. +Similar to the debug script, the download script is a hook for newt to download the image to the target system. +The download script also typically uses the openocd interface to erase flash and progam the code into the device. -NOTE: The download script needs to command openocd to program the image into the appropriate location, which is typically called `FLASH_OFFSET` in these scripts. This location has to match the linker script location of the image link address. For example, if your linker links the code to be run at `0xC000` your download script should download the image to the same -address in the correct flash. +**NOTE:** The download script needs to command openocd to program the image into the appropriate location +which is typically called `FLASH_OFFSET` in these scripts. This location has to match the linker script +location of the image link address. For example, if your linker links the code to be run at `0xC000` your +download script should download the image to the same address in the correct flash. ###Add License and Documentation http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/aac53ed0/docs/os/core_os/porting/port_cpu.md ---------------------------------------------------------------------- diff --git a/docs/os/core_os/porting/port_cpu.md b/docs/os/core_os/porting/port_cpu.md index fae2e82..873b42a 100644 --- a/docs/os/core_os/porting/port_cpu.md +++ b/docs/os/core_os/porting/port_cpu.md @@ -10,22 +10,26 @@ These are discussed below: ###Create A New Compiler -NOTE: Newt does not automatically install the compilers require to build all platforms. Its up to the user using their local machines package manager to install the compilers. The step described here just registers the compiler with newt. +NOTE: Newt does not automatically install the compilers require to build all platforms. +It's up to the user using their local machines package manager to install the compilers. +The steps described here just registers the compiler with newt. Create a new directory (named after the compiler you are adding). Copy the `pkg.yml` file from another compiler. -Edit the `pkg.yml` file and change the configuration attributes to match your compiler. Most are self-explanatory paths to different compiler and linker tools. There are a few configuration attributes worth noting. +Edit the `pkg.yml` file and change the configuration attributes to match your compiler. +Most are self-explanatory paths to different compiler and linker tools. There are a few configuration attributes worth noting. | **Configuration Attributes** | **Description** | |-----------|-------------| -| pkg.keywords | Specific keywords to help others search for this using newt | -| compiler.flags.default | default compiler flags for this architecture | -| compiler.flags.optimized | additional flags when the newt tool builds an optimized image | -| compiler.flags.debug | additional flags when the newt tool builds a debug image| +| `pkg.keywords` | Specific keywords to help others search for this using newt | +| `compiler.flags.default` | default compiler flags for this architecture | +| `compiler.flags.optimized` | additional flags when the newt tool builds an optimized image | +| `compiler.flags.debug` | additional flags when the newt tool builds a debug image| -###Implement architecture-specific OS code +###Implement Architecture-specific OS code -There are several architecture-specific code functions that are required when implementing a new architecture. You can find examples in the `sim` architecture within Mynewt. +There are several architecture-specific code functions that are required when implementing a +new architecture. You can find examples in the `sim` architecture within Mynewt. When porting to a new CPU architecture, use the existing architectures as samples when writing your implementation. http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/aac53ed0/docs/os/core_os/porting/port_mcu.md ---------------------------------------------------------------------- diff --git a/docs/os/core_os/porting/port_mcu.md b/docs/os/core_os/porting/port_mcu.md index 8fe5fbf..504baa3 100644 --- a/docs/os/core_os/porting/port_mcu.md +++ b/docs/os/core_os/porting/port_mcu.md @@ -6,9 +6,12 @@ The depth of work depends on the amount of HAL (Hardware Abstraction Layer) supp To get started: -* Create a `hw/mcu/mymcu` directory where `mymcu` is the MCU you are porting to. Replace the name `mymcu` with a description of the MCU you are using. -* Create a `hw/mcu/mymcu/variant` directory where the variant is the specific variant of the part you are usuing. Many MCU parts have variants with different capabilities (RAM, FLASH etc) or different pinouts. Replace `variant` with a description of the variant of the part you are using. -* Create a `hw/mcu/mymcu/variant/pkg.yml` file. Copy from another mcu and fill out the relevant information +* Create a `hw/mcu/mymcu` directory where `mymcu` is the MCU you are porting to. +Replace the name `mymcu` with a description of the MCU you are using. +* Create a `hw/mcu/mymcu/variant` directory where the variant is the specific +variant of the part you are usuing. Many MCU parts have variants with different capabilities +(RAM, FLASH etc) or different pinouts. Replace `variant` with a description of the variant of the part you are using. +* Create a `hw/mcu/mymcu/variant/pkg.yml` file. Copy from another mcu and fill out the relevant information * Create `hw/mcu/mymcu/variant/include`,`hw/mcu/mymcu/variant/include/mcu`, and `hw/mcu/mymcu/variant/src` directories to contain the code for your mcu. http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/aac53ed0/docs/os/core_os/porting/port_os.md ---------------------------------------------------------------------- diff --git a/docs/os/core_os/porting/port_os.md b/docs/os/core_os/porting/port_os.md index 0784fc4..2d3895a 100644 --- a/docs/os/core_os/porting/port_os.md +++ b/docs/os/core_os/porting/port_os.md @@ -22,9 +22,10 @@ SoC within your target platform * **BSP Dependencies** -- Specific code or configuration to accommodate the specific layout and functionality of your target platform -###BSP Dependency +###Board Support Package (BSP) Dependency -With all of the functionality provided by the core, MCU, and MCU HAL (Hardware Abstraction Layer), there are still some things that must be specified for your particular system. This +With all of the functionality provided by the core, MCU, and MCU HAL (Hardware Abstraction Layer), +there are still some things that must be specified for your particular system. This is provided in Mynewt to allow you the flexibility to design for the exact functionality, peripherals and features that you require in your product. @@ -51,25 +52,38 @@ However some MCUs have a pin multiplexor that allows the UART to be mapped to several different pins. For these MCUs, the BSP must specify if and where the UART pins should appear to match the hardware layout of your system. -* If your BSP is already supported my Mynewt, there is no additional BSP work involved in porting to your platform. You need only to set the `bsp` attribute in your Mynewt target using the [newt command tool](../../../newt/newt_intro). -* If your BSP is not yet supported by Mynewt, you can add support following the instructions on [how to add BSP support to Mynewt](port_bsp.md) +* If your BSP is already supported my Mynewt, there is no additional BSP work involved in porting to your platform. +You need only set the `bsp` attribute in your Mynewt target using the [newt command tool](../../../newt/newt_intro). +* If your BSP is not yet supported by Mynewt, you can add support by following the instructions on [how to add BSP support to Mynewt](port_bsp.md) ###MCU Dependency -Some OS code depends on the MCU or SoC that the system contains. For example, the MCU may specify the potential memory map of the system - where code and data can reside. +Some OS code depends on the MCU or SoC that the system contains. For example, the MCU may specify +the potential memory map of the system - where code and data can reside. -* If your MCU is already supported my Mynewt, there is no additional MCU work involved in porting to your platform. You need only to set the `arch` attribute in your Mynewt target using the [newt command tool](../../../newt/newt_intro). -* If your MCU is not yet supported by Mynewt, you can add support following the instructions on[how to add MCU support to Mynewt](port_mcu.md) +* If your MCU is already supported by Mynewt, there is no additional MCU work involved in +porting to your platform. You need only set the `arch` attribute in your Mynewt target +using the [newt command tool](../../../newt/newt_intro). +* If your MCU is not yet supported by Mynewt, you can add support by following the +instructions on [how to add MCU support to Mynewt](port_mcu.md) -### MCU HAL +### MCU Hardware Abstraction Layer (HAL) -Mynewt's architecture supports a hardware abstraction layer (HAL) for common on or off-chip MCU peripherals such as GPIO, UARTs, flash memory etc. Even if your MCU is supported for the core OS, you may find that you need to implement the HAL functionality for a new peripheral. For a description of the HAL abstraction and implementation information, +Mynewt's architecture supports a hardware abstraction layer (HAL) for common on or off-chip MCU peripherals +such as GPIO, UARTs, flash memory etc. Even if your MCU is supported for the core OS, +you may find that you need to implement the HAL functionality for a new peripheral. +For a description of the HAL abstraction and implementation information, see the [HAL API](../../modules/hal/hal.md) ###CPU Core Dependency -Some OS code depends on the CPU core that your system is using. For example, a given CPU core has a specific assembly language instruction set, and may require special cross compiler or compiler settings to use the appropriate instruction set. +Some OS code depends on the CPU core that your system is using. For example, a given CPU core +has a specific assembly language instruction set, and may require special cross compiler or +compiler settings to use the appropriate instruction set. -* If your CPU architecture is already supported my Mynewt, there is no CPU core work involved in porting to your platform. You need only to set the `arch` and `compiler` attributes in your Mynewt target using the [newt command tool](../../../newt/newt_intro). -* If your CPU architecture is not supported by Mynewt, you can add support following the instructions on [how to add CPU architecture support to Mynewt](port_cpu.md) +* If your CPU architecture is already supported by Mynewt, there is no CPU core work involved +in porting to your platform. You need only set the `arch` and `compiler` attributes in your +Mynewt target using the [newt command tool](../../../newt/newt_intro). +* If your CPU architecture is not supported by Mynewt, you can add support by following the +instructions on [how to add CPU architecture support to Mynewt](port_cpu.md) http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/aac53ed0/docs/os/core_os/sanity/sanity.md ---------------------------------------------------------------------- diff --git a/docs/os/core_os/sanity/sanity.md b/docs/os/core_os/sanity/sanity.md index 7091a33..ff9c5c9 100644 --- a/docs/os/core_os/sanity/sanity.md +++ b/docs/os/core_os/sanity/sanity.md @@ -148,7 +148,7 @@ err: In the above example, every time the custom sanity check `mymodule_perform_sanity_check` returns successfully (0), the sanity check is reset. In the `OS_SANITY_CHECK_SETFUNC` macro, -the sanity checkin interval is specified as 50 * SANITY_TASK_INTERVAL +the sanity checkin interval is specified as 50 * `SANITY_TASK_INTERVAL` (which is the interval at which the sanity task runs.) This means that the `mymodule_perform_sanity_check()` function needs to fail 50 times consecutively before the sanity task will crash the system. http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/aac53ed0/docs/os/core_os/semaphore/os_sem_init.md ---------------------------------------------------------------------- diff --git a/docs/os/core_os/semaphore/os_sem_init.md b/docs/os/core_os/semaphore/os_sem_init.md index 894caab..c588a19 100644 --- a/docs/os/core_os/semaphore/os_sem_init.md +++ b/docs/os/core_os/semaphore/os_sem_init.md @@ -11,14 +11,14 @@ Initialize a semaphore with a given number of tokens. Should be called before th | Arguments | Description | |-----------|-------------| -| *sem | Pointer to semaphore | -| tokens | Initial number of tokens allocated to semaphore | +| `*sem` | Pointer to semaphore | +| `tokens` | Initial number of tokens allocated to semaphore | #### Returned values -OS_INVALID_PARM: returned when *sem is NULL on entry. +`OS_INVALID_PARM`: returned when `*sem` is **NULL** on entry. -OS_OK: semaphore initialized successfully. +`OS_OK`: semaphore initialized successfully. #### Notes http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/aac53ed0/docs/os/core_os/semaphore/os_sem_pend.md ---------------------------------------------------------------------- diff --git a/docs/os/core_os/semaphore/os_sem_pend.md b/docs/os/core_os/semaphore/os_sem_pend.md index 9ccf8bd..c068595 100644 --- a/docs/os/core_os/semaphore/os_sem_pend.md +++ b/docs/os/core_os/semaphore/os_sem_pend.md @@ -10,22 +10,22 @@ Wait for a semaphore for a given amount of time. | Arguments | Description | |-----------|-------------| -| *sem | Pointer to semaphore | -| timeout | Amount of time, in os ticks, to wait for semaphore. A value of 0 means no wait. A value of 0xFFFFFFFF means wait forever. | +| `*sem` | Pointer to semaphore | +| `timeout` | Amount of time, in os ticks, to wait for semaphore. A value of 0 means no wait. A value of 0xFFFFFFFF means wait forever. | #### Returned values -OS_INVALID_PARM: returned when *sem is NULL on entry. +`OS_INVALID_PARM`: returned when `*sem` is **NULL** on entry. -OS_OK: semaphore acquired successfully. +`OS_OK`: semaphore acquired successfully. -OS_TIMEOUT: the semaphore was not available within the timeout specified. +`OS_TIMEOUT`: the semaphore was not available within the timeout specified. -OS_NOT_STARTED: Attempt to release a semaphore before os started. +`OS_NOT_STARTED:` Attempt to release a semaphore before os started. #### Notes -If a timeout of 0 is used and the function returns OS_TIMEOUT, the semaphore was not available and was not acquired. No release of the semaphore should occur and the calling task does not own the semaphore. +If a timeout of 0 is used and the function returns `OS_TIMEOUT`, the semaphore was not available and was not acquired. No release of the semaphore should occur and the calling task does not own the semaphore. #### Example http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/aac53ed0/docs/os/core_os/semaphore/os_sem_release.md ---------------------------------------------------------------------- diff --git a/docs/os/core_os/semaphore/os_sem_release.md b/docs/os/core_os/semaphore/os_sem_release.md index 3cb31f9..d55b992 100644 --- a/docs/os/core_os/semaphore/os_sem_release.md +++ b/docs/os/core_os/semaphore/os_sem_release.md @@ -11,15 +11,15 @@ Release a semaphore that you are holding. This adds a token to the semaphore. | Arguments | Description | |-----------|-------------| -| *sem | Pointer to semaphore | +| `*sem` | Pointer to semaphore | #### Returned values -OS_NOT_STARTED: Called before os has been started. +`OS_NOT_STARTED`: Called before os has been started. -OS_INVALID_PARM: returned when *sem is NULL on entry. +`OS_INVALID_PARM`: returned when `*sem` is **NULL** on entry. -OS_OK: semaphore released successfully. +`OS_OK`: semaphore released successfully. #### Notes http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/aac53ed0/docs/os/core_os/semaphore/semaphore.md ---------------------------------------------------------------------- diff --git a/docs/os/core_os/semaphore/semaphore.md b/docs/os/core_os/semaphore/semaphore.md index 9bcff62..a97643d 100644 --- a/docs/os/core_os/semaphore/semaphore.md +++ b/docs/os/core_os/semaphore/semaphore.md @@ -1,17 +1,17 @@ # Semaphore -A semaphore is a structure used for gaining exclusive access (much like a mutex), synchronizing task operations and/or use in a "producer/consumer" roles. Semaphores like the ones used by the myNewt OS are called "counting" semaphores as they are allowed to have more than one token (explained below). +A semaphore is a structure used for gaining exclusive access (much like a mutex), synchronizing task operations and/or use in a "producer/consumer" roles. Semaphores like the ones used by the Mynewt OS are called "counting" semaphores as they are allowed to have more than one token (explained below). ### Description A semaphore is a fairly simple construct consisting of a queue for waiting tasks and the number of tokens currently owned by the semaphore. A semaphore can be obtained as long as there are tokens in the semaphore. Any task can add tokens to the semaphore and any task can request the semaphore, thereby removing tokens. When creating the semaphore, the initial number of tokens can be set as well. -When used for exclusive access to a shared resource the semaphore only needs a single token. In this case, a single task "creates" the semaphore by calling *os_sem_init* with a value of one (1) for the token. When a task desires exclusive access to the shared resource it requests the semaphore by calling *os_sem_pend*. If there is a token the requesting task will acquire the semaphore and continue operation. If no tokens are available the task will be put to sleep until there is a token. A common "problem" with using a semaphore for exclusive access is called *priority inversion*. Consider the following scenario: a high and low priority task both share a resource which is locked using a semaphore. If the low priority task obtains the semaphore and then the high priority task requests the semaphore, the high priority task is now blocked until the low priority task releases the semaphore. Now suppose that there are tasks between the low priority task and the high priority task that wa nt to run. These tasks will preempt the low priority task which owns the semaphore. Thus, the high priority task is blocked waiting for the low priority task to finish using the semaphore but the low priority task cannot run since other tasks are running. Thus, the high priority tasks is "inverted" in priority; in effect running at a much lower priority as normally it would preempt the other (lower priority) tasks. If this is an issue a mutex should be used instead of a semaphore. +When used for exclusive access to a shared resource the semaphore only needs a single token. In this case, a single task "creates" the semaphore by calling `os_sem_init` with a value of one (1) for the token. When a task desires exclusive access to the shared resource it requests the semaphore by calling `os_sem_pend`. If there is a token the requesting task will acquire the semaphore and continue operation. If no tokens are available the task will be put to sleep until there is a token. A common problem with using a semaphore for exclusive access is called *priority inversion*. Consider the following scenario: a high and low priority task both share a resource which is locked using a semaphore. If the low priority task obtains the semaphore and then the high priority task requests the semaphore, the high priority task is now blocked until the low priority task releases the semaphore. Now suppose that there are tasks between the low priority task and the high priority task that want to run. These tasks will preempt the low priority task which owns the semaphore. Thus, the high priority task is blocked waiting for the low priority task to finish using the semaphore but the low priority task cannot run since other tasks are running. Thus, the high priority tasks is "inverted" in priority; in effect running at a much lower priority as normally it would preempt the other (lower priority) tasks. If this is an issue a mutex should be used instead of a semaphore. -Semaphores can also be used for task synchronization. A simple example of this would be the following. A task creates a semaphore and initializes it with no tokens. The task then waits on the semaphore, and since there are no tokens, the task is put to sleep. When other tasks want to wake up the sleeping task they simply add a token by calling *os_sem_release*. This will cause the sleeping task to wake up (instantly if no other higher priority tasks want to run). +Semaphores can also be used for task synchronization. A simple example of this would be the following. A task creates a semaphore and initializes it with no tokens. The task then waits on the semaphore, and since there are no tokens, the task is put to sleep. When other tasks want to wake up the sleeping task they simply add a token by calling `os_sem_release`. This will cause the sleeping task to wake up (instantly if no other higher priority tasks want to run). -The other common use of a counting semaphore is in what is commonly called a "producer/consumer" relationship. The producer adds tokens (by calling *os_sem_release*) and the consumer consumes them by calling *os_sem_pend*. In this relationship, the producer has work for the consumer to do. Each token added to the semaphore will cause the consumer to do whatever work is required. A simple example could be the following: every time a button is pressed there is some work to do (ring a bell). Each button press causes the producer to add a token. Each token consumed rings the bell. There will exactly the same number of bell rings as there are button presses. In other words, each call to *os_sem_pend* subtracts exactly one token and each call to *os_sem_release* adds exactly one token. +The other common use of a counting semaphore is in what is commonly called a "producer/consumer" relationship. The producer adds tokens (by calling `os_sem_release`) and the consumer consumes them by calling `os_sem_pend`. In this relationship, the producer has work for the consumer to do. Each token added to the semaphore will cause the consumer to do whatever work is required. A simple example could be the following: every time a button is pressed there is some work to do (ring a bell). Each button press causes the producer to add a token. Each token consumed rings the bell. There will be exactly the same number of bell rings as there are button presses. In other words, each call to `os_sem_pend` subtracts exactly one token and each call to `os_sem_release` adds exactly one token. ### Data structures http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/aac53ed0/docs/os/core_os/task/os_task_info_get_next.md ---------------------------------------------------------------------- diff --git a/docs/os/core_os/task/os_task_info_get_next.md b/docs/os/core_os/task/os_task_info_get_next.md index d1e5759..ef39372 100644 --- a/docs/os/core_os/task/os_task_info_get_next.md +++ b/docs/os/core_os/task/os_task_info_get_next.md @@ -3,27 +3,27 @@ ```c struct os_task *os_task_info_get_next(const struct os_task *prev, struct os_task_info *oti); ``` -Populates the os task info structure pointed to by *oti* with task information. -The task populating the *oti* structure is either the first task on the task -list if *prev* is NULL, or the next task in the task list (the next pointer of -*prev*). +Populates the os task info structure pointed to by `oti` with task information. +The task populating the `oti` structure is either the first task on the task +list if `prev` is **NULL**, or the next task in the task list (the next pointer of +`prev`). -If there are no tasks initialized, NULL is returned. Otherwise, the task -structure used to populate *oti* is returned. +If there are no tasks initialized, **NULL** is returned. Otherwise, the task +structure used to populate `oti` is returned. <br> #### Arguments | Arguments | Description | |-----------|-------------| -| prev | Pointer to previous task in task list. If NULL, use first task on list | -| oti | Pointer to `os_task_info` structure where task information will be stored | +| `prev` | Pointer to previous task in task list. If NULL, use first task on list | +| `oti` | Pointer to `os_task_info` structure where task information will be stored | <br> #### Returned values Returns a pointer to the os task structure that was used to populate the task -information structure. NULL means that no tasks were created. +information structure. **NULL** means that no tasks were created. <br> #### Example http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/aac53ed0/docs/os/core_os/task/os_task_init.md ---------------------------------------------------------------------- diff --git a/docs/os/core_os/task/os_task_init.md b/docs/os/core_os/task/os_task_init.md index a8329be..788ebbc 100644 --- a/docs/os/core_os/task/os_task_init.md +++ b/docs/os/core_os/task/os_task_init.md @@ -6,7 +6,7 @@ int os_task_init(struct os_task *t, char *name, os_task_func_t func, void *arg, uint16_t stack_size) ``` -Called to create a task. This adds the task object to the list of ready to run +Called to create a task. This adds the task object to the list of *ready to run* tasks. <br> @@ -14,19 +14,19 @@ tasks. | Arguments | Description | |-----------|-------------| -| t | Pointer to task | -| name | Task name | -| func | Task function | -| arg | Generic argument to pass to task | -| prio | Priority of task | -| sanity_itvl | The interval at which the sanity task will check to see if this task is sill alive | -| stack_bottom | Pointer to bottom of stack. | -| stack_size | The size of the stack. NOTE: this is not in bytes! It is the number of `os_stack_t` elements allocated (generally 32-bits each) | +| `t` | Pointer to task | +| `name` | Task name | +| `func` | Task function | +| `arg` | Generic argument to pass to task | +| `prio` | Priority of task | +| `sanity_itvl` | The interval at which the sanity task will check to see if this task is sill alive | +| `stack_bottom` | Pointer to bottom of stack. | +| `stack_size` | The size of the stack. NOTE: this is not in bytes! It is the number of `os_stack_t` elements allocated (generally 32-bits each) | <br> #### Returned values -OS_OK: task initialization successful. +`OS_OK`: task initialization successful. All other error codes indicate an internal error. http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/aac53ed0/docs/os/core_os/task/task.md ---------------------------------------------------------------------- diff --git a/docs/os/core_os/task/task.md b/docs/os/core_os/task/task.md index dac58d0..6ec0685 100644 --- a/docs/os/core_os/task/task.md +++ b/docs/os/core_os/task/task.md @@ -3,9 +3,8 @@ A task, along with the scheduler, forms the basis of the Mynewt OS. A task consists of two basic elements: a task stack and a task function. The task function is basically a forever loop, waiting for some "event" to wake it up. -There are two methods used to signal a task that it has work to do: event queues -and semaphores (see the appropriate manual sections for descriptions of these -features). +There are two methods used to signal a task that it has work to do: [event queues](../event_queue/event_queue.md) +and [semaphores](../semaphore/semaphore.md) . The Mynewt OS is a multi-tasking, preemptive OS. Every task is assigned a task priority (from 0 to 255), with 0 being the highest priority task. If a higher @@ -16,11 +15,11 @@ stack of the higher priority task and the task resumes execution where it left off. Tasks run to completion unless they are preempted by a higher priority task. The -developer must insure that tasks eventually "sleep"; otherwise lower priority +developer must ensure that tasks eventually "sleep"; otherwise lower priority tasks will never get a chance to run (actually, any task lower in priority than the task that never sleeps). A task will be put to sleep in the following cases: -it puts itself to sleep using `os_time_delay()`, it waits on an event queue -which is empty or attempts to obtain a mutex or a semaphore that is currently +it puts itself to sleep using `os_time_delay()`, it waits on an [event queue](../event_queue/event_queue.md) +which is empty or attempts to obtain a mutex or a [semaphore](../semaphore/semaphore.md) that is currently owned by another task. Note that other sections of the manual describe these OS features in more @@ -29,7 +28,7 @@ detail. ## Description In order to create a task two data structures need to be defined: the task -object (struct os_task) and its associated stack. Determining the stack size can +object (`struct os_task`) and its associated stack. Determining the stack size can be a bit tricky; generally developers should not declare large local variables on the stack so that task stacks can be of limited size. However, all applications are different and the developer must choose the stack size @@ -47,7 +46,7 @@ scheduler, the `os_task_init()` function is called. Once `os_task_init()` is called, the task is made ready to run and is added to the active task list. Note that a task can be initialized (started) before or after the os has started (i.e. before `os_start()` is called) but must be initialized after the os has -been initialized (i.e. 'os_init' has been called). In most of the examples and +been initialized (i.e. 'os_init()' has been called). In most of the examples and current Mynewt projects, the os is initialized, tasks are initialized, and the the os is started. Once the os has started, the highest priority task will be the first task set to run. http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/aac53ed0/docs/os/core_os/time/os_gettimeofday.md ---------------------------------------------------------------------- diff --git a/docs/os/core_os/time/os_gettimeofday.md b/docs/os/core_os/time/os_gettimeofday.md index 22d10a3..98875fb 100644 --- a/docs/os/core_os/time/os_gettimeofday.md +++ b/docs/os/core_os/time/os_gettimeofday.md @@ -8,8 +8,8 @@ int os_gettimeofday(struct os_timeval *utctime, struct os_timezone *timezone); | Arguments | Description | |-----------|-------------| -| utctime | UTC time corresponding to wallclock time | -| timezone | Timezone to convert UTC time to wallclock time | +| `utctime` | UTC time corresponding to wallclock time | +| `timezone` | Timezone to convert UTC time to wallclock time | #### Returned values http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/aac53ed0/docs/os/core_os/time/os_settimeofday.md ---------------------------------------------------------------------- diff --git a/docs/os/core_os/time/os_settimeofday.md b/docs/os/core_os/time/os_settimeofday.md index c5fc186..91615ce 100644 --- a/docs/os/core_os/time/os_settimeofday.md +++ b/docs/os/core_os/time/os_settimeofday.md @@ -8,8 +8,8 @@ int os_settimeofday(struct os_timeval *utctime, struct os_timezone *timezone); | Arguments | Description | |-----------|-------------| -| utctime | UTC time corresponding to the wallclock time | -| timezone | Timezone associated with the wallclock time | +| `utctime` | UTC time corresponding to the wallclock time | +| `timezone` | Timezone associated with the wallclock time | #### Returned values http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/aac53ed0/docs/os/core_os/time/os_time.md ---------------------------------------------------------------------- diff --git a/docs/os/core_os/time/os_time.md b/docs/os/core_os/time/os_time.md index eee868f..52d0376 100644 --- a/docs/os/core_os/time/os_time.md +++ b/docs/os/core_os/time/os_time.md @@ -17,18 +17,20 @@ Time is stored in Mynewt as an `os_time_t` value. Wallclock time is represented using the `struct os_timeval` and `struct os_timezone` tuple. -`struct os_timeval` represents the number of seconds elapsed since 00:00:00 Jan 1, 1970 UTC. -<pre> +`struct os_timeval` represents the number of seconds elapsed since the epoch (00:00:00 Jan 1, 1970 UTC). + +```c struct os_timeval { int64_t tv_sec; /* seconds since Jan 1 1970 UTC */ int32_t tv_usec; /* fractional seconds */ }; struct os_timeval tv = { 1457400000, 0 }; /* 01:20:00 Mar 8 2016 UTC */ -</pre> +``` `struct os_timezone` is used to specify the offset of local time from UTC and whether daylight savings is in effect. Note that `tz_minuteswest` is a positive number if the local time is *behind* UTC and a negative number if the local time is *ahead* of UTC. -<pre> + +```c struct os_timezone { int16_t tz_minuteswest; int16_t tz_dsttime; @@ -40,7 +42,7 @@ struct os_timezone PDT = { 480, 1 }; /* Indian Standard Time is 05:30 hours east of UTC */ struct os_timezone IST = { -330, 0 }; -</pre> +``` ## List of Functions http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/aac53ed0/docs/os/core_os/time/os_time_delay.md ---------------------------------------------------------------------- diff --git a/docs/os/core_os/time/os_time_delay.md b/docs/os/core_os/time/os_time_delay.md index a9199ba..8b70236 100644 --- a/docs/os/core_os/time/os_time_delay.md +++ b/docs/os/core_os/time/os_time_delay.md @@ -8,7 +8,7 @@ void os_time_delay(int32_t ticks) | Arguments | Description | |-----------|-------------| -| ticks | Number of ticks to delay. Less than or equal to zero means no delay | +| `ticks` | Number of ticks to delay. Less than or equal to zero means no delay | #### Returned values http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/aac53ed0/docs/os/get_started/vocabulary.md ---------------------------------------------------------------------- diff --git a/docs/os/get_started/vocabulary.md b/docs/os/get_started/vocabulary.md index 729bf2e..f35f019 100644 --- a/docs/os/get_started/vocabulary.md +++ b/docs/os/get_started/vocabulary.md @@ -133,8 +133,8 @@ Targets can also have additional items specified, including: In order to create and manipulate targets, the *newt* tool offers a set of helper commands, you can find more information about these by issuing: -```no-highlight $ newt target +```no-highligh Usage: newt target [flags] newt target [command] @@ -183,3 +183,9 @@ $ newt target config <target-name> ... $ ``` + +Keep in mind that this will only show the configuration options for any packages that are included in your applicaiton. + +If you really want to see **all** the available configuration options, you can go rough each package and look at the +`syscfg.yml` file in each. +
