Normalize OS Core Docs Trying to get consistency in docs formatting.
Project: http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/repo Commit: http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/commit/aac53ed0 Tree: http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/tree/aac53ed0 Diff: http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/diff/aac53ed0 Branch: refs/heads/develop Commit: aac53ed0482b786670727964e8026ab07e62cfed Parents: 05b828c Author: David G. Simmons <[email protected]> Authored: Tue Nov 1 10:24:08 2016 -0400 Committer: David G. Simmons <[email protected]> Committed: Tue Nov 1 10:24:08 2016 -0400 ---------------------------------------------------------------------- docs/os/core_os/callout/callout.md | 20 +-- docs/os/core_os/callout/os_callout_func_init.md | 20 +-- docs/os/core_os/callout/os_callout_init.md | 16 +-- docs/os/core_os/callout/os_callout_queued.md | 7 +- docs/os/core_os/callout/os_callout_reset.md | 12 +- docs/os/core_os/callout/os_callout_stop.md | 10 +- .../os/core_os/context_switch/context_switch.md | 20 +-- .../os/core_os/context_switch/os_arch_ctx_sw.md | 10 +- docs/os/core_os/context_switch/os_sched.md | 6 +- .../context_switch/os_sched_ctx_sw_hook.md | 2 +- .../core_os/context_switch/os_sched_insert.md | 7 +- .../context_switch/os_sched_os_timer_exp.md | 4 +- .../core_os/context_switch/os_sched_resort.md | 6 +- .../context_switch/os_sched_set_current_task.md | 6 +- .../os/core_os/context_switch/os_sched_sleep.md | 10 +- .../core_os/context_switch/os_sched_wakeup.md | 2 +- docs/os/core_os/event_queue/event_queue.md | 16 +-- docs/os/core_os/event_queue/os_eventq_get.md | 4 +- docs/os/core_os/event_queue/os_eventq_init.md | 4 +- docs/os/core_os/event_queue/os_eventq_put.md | 6 +- docs/os/core_os/event_queue/os_eventq_remove.md | 6 +- docs/os/core_os/heap/heap.md | 2 +- docs/os/core_os/heap/os_free.md | 4 +- docs/os/core_os/heap/os_malloc.md | 12 +- docs/os/core_os/heap/os_realloc.md | 10 +- docs/os/core_os/mbuf/OS_MBUF_DATA.md | 4 +- docs/os/core_os/mbuf/OS_MBUF_LEADINGSPACE.md | 4 +- docs/os/core_os/mbuf/OS_MBUF_PKTHDR.md | 2 +- docs/os/core_os/mbuf/OS_MBUF_PKTHDR_TO_MBUF.md | 2 +- docs/os/core_os/mbuf/OS_MBUF_PKTLEN.md | 2 +- docs/os/core_os/mbuf/OS_MBUF_TRAILINGSPACE.md | 4 +- docs/os/core_os/mbuf/OS_MBUF_USRHDR.md | 2 +- docs/os/core_os/mbuf/OS_MBUF_USRHDR_LEN.md | 2 +- docs/os/core_os/mbuf/mbuf.md | 26 ++-- docs/os/core_os/mbuf/os_mbuf_adj.md | 6 +- docs/os/core_os/mbuf/os_mbuf_append.md | 14 +-- docs/os/core_os/mbuf/os_mbuf_concat.md | 4 +- docs/os/core_os/mbuf/os_mbuf_copydata.md | 10 +- docs/os/core_os/mbuf/os_mbuf_copyinto.md | 8 +- docs/os/core_os/mbuf/os_mbuf_dup.md | 4 +- docs/os/core_os/mbuf/os_mbuf_extend.md | 8 +- docs/os/core_os/mbuf/os_mbuf_free_chain.md | 2 +- docs/os/core_os/mbuf/os_mbuf_get.md | 8 +- docs/os/core_os/mbuf/os_mbuf_get_pkthdr.md | 10 +- docs/os/core_os/mbuf/os_mbuf_memcmp.md | 10 +- docs/os/core_os/mbuf/os_mbuf_off.md | 12 +- docs/os/core_os/mbuf/os_mbuf_pool_init.md | 10 +- docs/os/core_os/mbuf/os_mbuf_prepend.md | 8 +- docs/os/core_os/mbuf/os_mbuf_pullup.md | 8 +- docs/os/core_os/memory_pool/OS_MEMPOOL_BYTES.md | 8 +- docs/os/core_os/memory_pool/OS_MEMPOOL_SIZE.md | 16 +-- docs/os/core_os/memory_pool/memory_pool.md | 2 +- docs/os/core_os/memory_pool/os_memblock_get.md | 6 +- docs/os/core_os/memory_pool/os_memblock_put.md | 8 +- docs/os/core_os/memory_pool/os_mempool_init.md | 26 ++-- docs/os/core_os/mqueue/mqueue.md | 6 +- docs/os/core_os/mqueue/os_mqueue_get.md | 6 +- docs/os/core_os/mqueue/os_mqueue_init.md | 6 +- docs/os/core_os/mqueue/os_mqueue_put.md | 10 +- docs/os/core_os/msys/msys.md | 4 +- docs/os/core_os/msys/os_msys_get.md | 10 +- docs/os/core_os/msys/os_msys_get_pkthdr.md | 8 +- docs/os/core_os/msys/os_msys_register.md | 2 +- docs/os/core_os/mutex/mutex.md | 2 +- docs/os/core_os/mutex/os_mutex_init.md | 6 +- docs/os/core_os/mutex/os_mutex_pend.md | 14 +-- docs/os/core_os/mutex/os_mutex_release.md | 10 +- docs/os/core_os/mynewt_os.md | 8 +- docs/os/core_os/os_init.md | 6 +- docs/os/core_os/os_start.md | 4 +- docs/os/core_os/os_started.md | 6 +- docs/os/core_os/porting/port_bsp.md | 124 ++++++++++++------- docs/os/core_os/porting/port_cpu.md | 20 +-- docs/os/core_os/porting/port_mcu.md | 9 +- docs/os/core_os/porting/port_os.md | 38 ++++-- docs/os/core_os/sanity/sanity.md | 2 +- docs/os/core_os/semaphore/os_sem_init.md | 8 +- docs/os/core_os/semaphore/os_sem_pend.md | 14 +-- docs/os/core_os/semaphore/os_sem_release.md | 8 +- docs/os/core_os/semaphore/semaphore.md | 8 +- docs/os/core_os/task/os_task_info_get_next.md | 18 +-- docs/os/core_os/task/os_task_init.md | 20 +-- docs/os/core_os/task/task.md | 15 ++- docs/os/core_os/time/os_gettimeofday.md | 4 +- docs/os/core_os/time/os_settimeofday.md | 4 +- docs/os/core_os/time/os_time.md | 12 +- docs/os/core_os/time/os_time_delay.md | 2 +- docs/os/get_started/vocabulary.md | 8 +- 88 files changed, 469 insertions(+), 411 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/aac53ed0/docs/os/core_os/callout/callout.md ---------------------------------------------------------------------- diff --git a/docs/os/core_os/callout/callout.md b/docs/os/core_os/callout/callout.md index 042dd7b..ced9eb8 100644 --- a/docs/os/core_os/callout/callout.md +++ b/docs/os/core_os/callout/callout.md @@ -20,34 +20,36 @@ Callout timer fires out just once. For periodic timer type of operation you need ### Data structures +```c struct os_callout { struct os_event c_ev; struct os_eventq *c_evq; uint32_t c_ticks; TAILQ_ENTRY(os_callout) c_next; }; - +``` | Element | Description | |---------|-------------| -| c_ev | Event structure of this callout | -| c_evq | Event queue where this callout is placed on timer expiry | -| c_ticks | OS tick amount when timer fires | -| c_next | Linkage to other unexpired callouts | - +| `c_ev` | Event structure of this callout | +| `c_evq` | Event queue where this callout is placed on timer expiry | +| `c_ticks` | OS tick amount when timer fires | +| `c_next` | Linkage to other unexpired callouts | +```c struct os_callout_func { struct os_callout cf_c; os_callout_func_t cf_func; void *cf_arg; }; +``` | Element | Description | |---------|-------------| -| cf_c | struct os_callout. See above | -| cf_func | Function pointer which should be called by event queue processing | -| cf_arg | Generic void * argument to that function | +| `cf_c` | struct os_callout. See above | +| `cf_func` | Function pointer which should be called by event queue processing | +| `cf_arg` | Generic void * argument to that function | ### List of Functions http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/aac53ed0/docs/os/core_os/callout/os_callout_func_init.md ---------------------------------------------------------------------- diff --git a/docs/os/core_os/callout/os_callout_func_init.md b/docs/os/core_os/callout/os_callout_func_init.md index 2c45817..de62bef 100644 --- a/docs/os/core_os/callout/os_callout_func_init.md +++ b/docs/os/core_os/callout/os_callout_func_init.md @@ -1,20 +1,20 @@ ## <font color="#F2853F" style="font-size:24pt"> os_callout_func_init </font> - +```c void os_callout_func_init(struct os_callout_func *cf, struct os_eventq *evq, os_callout_func_t timo_func, void *ev_arg) +``` - -Initializes the given *struct os_callout_func*. Data structure is filled in with elements given as argument. +Initializes the given `struct os_callout_func`. Data structure is filled in with elements given as argument. #### Arguments | Arguments | Description | |-----------|-------------| -| cf | Pointer to os_callout_func being initialized | -| evq | Event queue where this gets delivered to | -| timo_func | Timeout function. Event processing should call this | -| ev_arg | Generic argument for the event | +| `cf` | Pointer to os_callout_func being initialized | +| `evq` | Event queue where this gets delivered to | +| `timo_func` | Timeout function. Event processing should call this | +| `ev_arg` | Generic argument for the event | #### Returned values @@ -22,13 +22,13 @@ N/A #### Notes -The same notes as with *os_callout_init()*. +The same notes as with [`os_callout_init()`](os_callout_init.md). #### Example <Add text to set up the context for the example here> - +```c struct os_callout_func g_native_cputimer; struct os_eventq g_native_cputime_evq; void native_cputimer_cb(void *arg); @@ -38,7 +38,7 @@ The same notes as with *os_callout_init()*. &g_native_cputime_evq, native_cputimer_cb, NULL); - +``` http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/aac53ed0/docs/os/core_os/callout/os_callout_init.md ---------------------------------------------------------------------- diff --git a/docs/os/core_os/callout/os_callout_init.md b/docs/os/core_os/callout/os_callout_init.md index 7d30fdc..e4896f6 100644 --- a/docs/os/core_os/callout/os_callout_init.md +++ b/docs/os/core_os/callout/os_callout_init.md @@ -1,19 +1,19 @@ ## <font color="#F2853F" style="font-size:24pt">os_callout_init </font> - +```c void os_callout_init(struct os_callout *c, struct os_eventq *evq, void *ev_arg) +``` - -Initializes *struct os_callout*. Event type will be set to *OS_EVENT_T_TIMER*. +Initializes `struct os_callout`. Event type will be set to `OS_EVENT_T_TIMER`. #### Arguments | Arguments | Description | |-----------|-------------| -| c | Pointer to os_callout to initialize | -| evq | Event queue where this gets delivered to | -| ev_arg | Generic argument which is filled in for the event | +| `c` | Pointer to os_callout to initialize | +| `evq` | Event queue where this gets delivered to | +| `ev_arg` | Generic argument which is filled in for the event | #### Returned values @@ -28,11 +28,11 @@ Or if the timer has already fired, it will mess up the event queue where the cal <Add text to set up the context for the example here> - +```c struct os_eventq my_evq; struct os_callout my_callouts[8]; for (i = 0; i < 8; i++) { os_callout_init(&my_callouts[i], &my_evq, (void *)i); } - +``` http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/aac53ed0/docs/os/core_os/callout/os_callout_queued.md ---------------------------------------------------------------------- diff --git a/docs/os/core_os/callout/os_callout_queued.md b/docs/os/core_os/callout/os_callout_queued.md index 9e69f96..0917d13 100644 --- a/docs/os/core_os/callout/os_callout_queued.md +++ b/docs/os/core_os/callout/os_callout_queued.md @@ -1,8 +1,8 @@ ## <font color="#F2853F" style="font-size:24pt">os_callout_queued</font> - +```c int os_callout_queued(struct os_callout *c) - +``` Tells whether the callout has been armed or not. @@ -11,11 +11,12 @@ Tells whether the callout has been armed or not. | Arguments | Description | |-----------|-------------| -| c | Pointer to callout being checked | +| `c` | Pointer to callout being checked | #### Returned values 0: timer is not armed + non-zero: timer is armed http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/aac53ed0/docs/os/core_os/callout/os_callout_reset.md ---------------------------------------------------------------------- diff --git a/docs/os/core_os/callout/os_callout_reset.md b/docs/os/core_os/callout/os_callout_reset.md index 5c6875b..d9ff1d8 100644 --- a/docs/os/core_os/callout/os_callout_reset.md +++ b/docs/os/core_os/callout/os_callout_reset.md @@ -1,8 +1,8 @@ ## <font color="#F2853F" style="font-size:24pt"> os_callout_reset </font> - +```c void os_callout_reset(struct os_callout *c, int32_t timo) - +``` Resets the callout to happen *timo* in OS ticks. @@ -11,8 +11,8 @@ Resets the callout to happen *timo* in OS ticks. | Arguments | Description | |-----------|-------------| -| c | Pointer to os_callout being reset | -| timo | OS ticks the timer is being set to | +| `c` | Pointer to os_callout being reset | +| `timo` | OS ticks the timer is being set to | #### Returned values @@ -27,7 +27,7 @@ N/A <Add text to set up the context for the example here> - +```c /* Re-start the timer (run every 50 msecs) */ os_callout_reset(&g_bletest_timer.cf_c, OS_TICKS_PER_SEC / 20); - +``` http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/aac53ed0/docs/os/core_os/callout/os_callout_stop.md ---------------------------------------------------------------------- diff --git a/docs/os/core_os/callout/os_callout_stop.md b/docs/os/core_os/callout/os_callout_stop.md index 76aa87d..45359b4 100644 --- a/docs/os/core_os/callout/os_callout_stop.md +++ b/docs/os/core_os/callout/os_callout_stop.md @@ -1,8 +1,8 @@ ## <font color="#F2853F" style="font-size:24pt"> os_callout_stop </font> - +```c void os_callout_stop(struct os_callout *c) - +``` Disarms a timer. @@ -11,7 +11,7 @@ Disarms a timer. | Arguments | Description | |-----------|-------------| -| c | Pointer to os_callout being stopped | +| `c` | Pointer to os_callout being stopped | #### Returned values @@ -22,10 +22,10 @@ N/A #### Example - +```c struct os_callout_func g_native_cputimer; os_callout_stop(&g_native_cputimer.cf_c); - +``` http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/aac53ed0/docs/os/core_os/context_switch/context_switch.md ---------------------------------------------------------------------- diff --git a/docs/os/core_os/context_switch/context_switch.md b/docs/os/core_os/context_switch/context_switch.md index b507149..e3c582a 100644 --- a/docs/os/core_os/context_switch/context_switch.md +++ b/docs/os/core_os/context_switch/context_switch.md @@ -7,19 +7,19 @@ Scheduler's job is to maintain the list of tasks and decide which one should be Task states can be *running*, *ready to run* or *sleeping*. -When task is *running*, CPU is executing in that task's context. The program counter (PC) is pointing to instructions task wants to execute and stack pointer (SP) is pointing to task's stack. +When a task is *running*, the CPU is executing in that task's context. The program counter (PC) is pointing to instructions that task wants to execute and the stack pointer (SP) is pointing to that task's stack. -Task which is *ready to run* wants to get on the CPU to do its work. +A task which is *ready to run* wants to get on the CPU to do its work. -Task which is *sleeping* has no more work to do. It's waiting for someone else to wake it up. +A task which is *sleeping* has no more work to do. It's waiting for someone or something else to wake it up. -Scheduler algorithm is simple: from among the tasks which are ready to run, pick the the one with highest priority (lowest numeric value in task's t_prio field), and make its state *running*. +The Scheduler algorithm is simple: from among the tasks which are ready to run, pick the the one with highest priority (lowest numeric value in task's `t_prio` field), and make its state *running*. -Tasks which are either *running* or *ready to run* are kept in linked list `g_os_run_list`. This list is ordered by priority. +Tasks which are either *running* or *ready to run* are kept in a linked list `g_os_run_list`. This list is ordered by priority. -Tasks which are *sleeping* are kept in linked list `g_os_sleep_list`. +Tasks which are *sleeping* are kept in a linked list `g_os_sleep_list`. -Scheduler has a CPU architecture specific component; this code is responsible for swapping in the task which should be *running*. This process is called context switch. During context switching the state of the CPU (e.g. registers) for the currently *running* task is stored and the new task is swapped in. +The scheduler has a CPU architecture specific component; this code is responsible for swapping in the task which should be *running*. This process is called context switch. During context switching the state of the CPU (e.g. registers) for the currently *running* task is stored and the new task is swapped in. ## List of Functions @@ -30,10 +30,10 @@ The functions available in context_switch are: | **Function** | **Description** | |-----------|-------------| | [os_sched](os_sched.md) | Performs context switch if needed. | -| [os_arch_ctx_sw](os_arch_ctx_sw.md) | Change the state of task given task to *running*. | +| [os_arch_ctx_sw](os_arch_ctx_sw.md) | Change the state of a given task to *running*. | | [os_sched_ctx_sw_hook](os_sched_ctx_sw_hook.md) | Performs task accounting when context switching. | -| [os_sched_get_current_task](os_sched_get_current_task.md) | Returns the pointer to task which is currently *running*. | -| [os_sched_insert](os_sched_insert.md) | Insert task into scheduler's ready to run list. | +| [os_sched_get_current_task](os_sched_get_current_task.md) | Returns the pointer to the task which is currently *running*. | +| [os_sched_insert](os_sched_insert.md) | Insert a task into scheduler's *ready to run* list. | | [os_sched_next_task](os_sched_next_task.md) | Returns the pointer to highest priority task from the list which are *ready to run*. | | [os_sched_os_timer_exp](os_sched_os_timer_exp.md) | Inform scheduler that OS time has moved forward. | | [os_sched_resort](os_sched_resort.md) | Inform scheduler that the priority of the given task has changed and the *ready to run* list should be re-sorted. | http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/aac53ed0/docs/os/core_os/context_switch/os_arch_ctx_sw.md ---------------------------------------------------------------------- diff --git a/docs/os/core_os/context_switch/os_arch_ctx_sw.md b/docs/os/core_os/context_switch/os_arch_ctx_sw.md index 2a1c7f7..9c59b28 100644 --- a/docs/os/core_os/context_switch/os_arch_ctx_sw.md +++ b/docs/os/core_os/context_switch/os_arch_ctx_sw.md @@ -1,16 +1,16 @@ -## <font color="#F2853F" style="font-size:24pt"> os_arch_ctx_sw </font> - +##<font color="#F2853F" style="font-size:24pt"> os_arch_ctx_sw </font> +```c void os_arch_ctx_sw(struct os_task *next_t) +``` - -Change the state of task pointed by *next_t* to be *running*. +Change the state of task pointed by `next_t` to be *running*. #### Arguments | Arguments | Description | |-----------|-------------| -| next_t | Pointer to task which must run next | +| `next_t` | Pointer to task which must run next | #### Returned values http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/aac53ed0/docs/os/core_os/context_switch/os_sched.md ---------------------------------------------------------------------- diff --git a/docs/os/core_os/context_switch/os_sched.md b/docs/os/core_os/context_switch/os_sched.md index 2eb34cf..4cbeefc 100644 --- a/docs/os/core_os/context_switch/os_sched.md +++ b/docs/os/core_os/context_switch/os_sched.md @@ -1,10 +1,10 @@ -## <font color="#F2853F" style="font-size:24pt"> os_sched </font> +##<font color="#F2853F" style="font-size:24pt"> os_sched </font> ```c void os_sched(struct os_task *next_t) ``` -Performs context switch if needed. If *next_t* is set, that task will be made *running*. If *next_t* is NULL, highest priority *ready to run* is swapped in. This function can be called when new tasks were made *ready to run* or if the current task is moved to *sleeping* state. +Performs context switch if needed. If `next_t` is set, that task will be made *running*. If `next_t` is **NULL**, highest priority *ready to run* is swapped in. This function can be called when new tasks were made *ready to run* or if the current task is moved to *sleeping* state. This function will call the architecture specific routine to swap in the new task. @@ -12,7 +12,7 @@ This function will call the architecture specific routine to swap in the new tas | Arguments | Description | |-----------|-------------| -| next_t | Pointer to task which must run next (optional) | +| `next_t` | Pointer to task which must run next (optional) | #### Returned values http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/aac53ed0/docs/os/core_os/context_switch/os_sched_ctx_sw_hook.md ---------------------------------------------------------------------- diff --git a/docs/os/core_os/context_switch/os_sched_ctx_sw_hook.md b/docs/os/core_os/context_switch/os_sched_ctx_sw_hook.md index 3042478..dd586fd 100644 --- a/docs/os/core_os/context_switch/os_sched_ctx_sw_hook.md +++ b/docs/os/core_os/context_switch/os_sched_ctx_sw_hook.md @@ -6,7 +6,7 @@ void os_sched_ctx_sw_hook(struct os_task *next_t) Performs task accounting when context switching. -This function must be called from the architecture specific context switching routine *os_arch_ctx_sw()* before resuming execution of the *running* task. +This function must be called from the architecture specific context switching routine `os_arch_ctx_sw()` before resuming execution of the *running* task. #### Arguments http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/aac53ed0/docs/os/core_os/context_switch/os_sched_insert.md ---------------------------------------------------------------------- diff --git a/docs/os/core_os/context_switch/os_sched_insert.md b/docs/os/core_os/context_switch/os_sched_insert.md index dce6755..46fcb52 100644 --- a/docs/os/core_os/context_switch/os_sched_insert.md +++ b/docs/os/core_os/context_switch/os_sched_insert.md @@ -1,8 +1,7 @@ ## <font color="#F2853F" style="font-size:24pt"> os_sched_insert </font> ```c -os_error_t -os_sched_insert(struct os_task *t) +os_error_t os_sched_insert(struct os_task *t) ``` Insert task into scheduler's *ready to run* list. @@ -12,11 +11,11 @@ Insert task into scheduler's *ready to run* list. | Arguments | Description | |-----------|-------------| -| t | Pointer to task | +| `t`| Pointer to task | #### Returned values -Returns OS_EINVAL if task state is not *READY*. +Returns `OS_EINVAL` if task state is not **READY**. Returns 0 on success. #### Notes http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/aac53ed0/docs/os/core_os/context_switch/os_sched_os_timer_exp.md ---------------------------------------------------------------------- diff --git a/docs/os/core_os/context_switch/os_sched_os_timer_exp.md b/docs/os/core_os/context_switch/os_sched_os_timer_exp.md index f5a03fc..3d2c5ca 100644 --- a/docs/os/core_os/context_switch/os_sched_os_timer_exp.md +++ b/docs/os/core_os/context_switch/os_sched_os_timer_exp.md @@ -4,9 +4,9 @@ void os_sched_os_timer_exp(void) ``` -Inform scheduler that OS time has moved forward, and it should inspect tasks which are *sleeping* to check whether they should be moved to *g_run_list* or not. +Inform scheduler that OS time has moved forward, and it should inspect tasks which are *sleeping* to check whether they should be moved to `g_run_list` or not. -This function should be called from code which handles moving OS time forward. After calling it, the highest priority task which is *ready to run* might've changed, so call to *os_sched()* should be done. +This function should be called from code which handles moving OS time forward. After calling it, the highest priority task which is *ready to run* might've changed, so call to `os_sched()` should be done. #### Arguments http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/aac53ed0/docs/os/core_os/context_switch/os_sched_resort.md ---------------------------------------------------------------------- diff --git a/docs/os/core_os/context_switch/os_sched_resort.md b/docs/os/core_os/context_switch/os_sched_resort.md index c755fb3..5109a88 100644 --- a/docs/os/core_os/context_switch/os_sched_resort.md +++ b/docs/os/core_os/context_switch/os_sched_resort.md @@ -4,13 +4,13 @@ void os_sched_resort(struct os_task *t) ``` -Inform scheduler that the priority of the task *t* has changed (e.g. in order to avoid priority inversion), and the *ready to run* list should be re-sorted. +Inform scheduler that the priority of the task `t` has changed (e.g. in order to avoid priority inversion), and the *ready to run* list should be re-sorted. #### Arguments | Arguments | Description | |-----------|-------------| -| t | Pointer to a task whose priority has changed | +| `t` | Pointer to a task whose priority has changed | #### Returned values @@ -18,7 +18,7 @@ N/A #### Notes -*t* must be *ready to run* before calling this. +`t` must be *ready to run* before calling this. #### Example http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/aac53ed0/docs/os/core_os/context_switch/os_sched_set_current_task.md ---------------------------------------------------------------------- diff --git a/docs/os/core_os/context_switch/os_sched_set_current_task.md b/docs/os/core_os/context_switch/os_sched_set_current_task.md index 8839980..8604e1a 100644 --- a/docs/os/core_os/context_switch/os_sched_set_current_task.md +++ b/docs/os/core_os/context_switch/os_sched_set_current_task.md @@ -5,15 +5,15 @@ void os_sched_set_current_task(struct os_task *t) ``` -Sets the currently running task to 't'. +Sets the currently running task to `t`. -This is called from architecture specific context switching code to update scheduler state. Call is made when state of the task 't' is made *running*. +This is called from architecture specific context switching code to update scheduler state. Call is made when state of the task `t` is made *running*. #### Arguments | Arguments | Description | |-----------|-------------| -| t | Pointer to a task | +| `t` | Pointer to a task | #### Returned values http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/aac53ed0/docs/os/core_os/context_switch/os_sched_sleep.md ---------------------------------------------------------------------- diff --git a/docs/os/core_os/context_switch/os_sched_sleep.md b/docs/os/core_os/context_switch/os_sched_sleep.md index 3c46887..1ea45aa 100644 --- a/docs/os/core_os/context_switch/os_sched_sleep.md +++ b/docs/os/core_os/context_switch/os_sched_sleep.md @@ -5,18 +5,18 @@ int os_sched_sleep(struct os_task *t, os_time_t nticks) ``` -Task 't' state is changed from *ready to run* to *sleeping*. Sleep time will be specified in *nticks*. +Task `t` state is changed from *ready to run* to *sleeping*. Sleep time will be specified in `nticks`. -Task will be woken up after sleep timer expires, unless there are other signals causing it to wake up. +Task will be woken up after sleep timer expires, unless there are other signals causing it to wake up. -If *nticks* is set to *OS_TIMEOUT_NEVER*, task never wakes up with a sleep timer. +If `nticks` is set to `OS_TIMEOUT_NEVER`, task never wakes up with a sleep timer. #### Arguments | Arguments | Description | |-----------|-------------| -| t | Pointer to task | -| nticks | Number of ticks to sleep in OS ticks | +| `t` | Pointer to task | +| `nticks` | Number of ticks to sleep in OS ticks | #### Returned values http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/aac53ed0/docs/os/core_os/context_switch/os_sched_wakeup.md ---------------------------------------------------------------------- diff --git a/docs/os/core_os/context_switch/os_sched_wakeup.md b/docs/os/core_os/context_switch/os_sched_wakeup.md index 4407c96..cb884be 100644 --- a/docs/os/core_os/context_switch/os_sched_wakeup.md +++ b/docs/os/core_os/context_switch/os_sched_wakeup.md @@ -12,7 +12,7 @@ Called to make task *ready to run*. If task is *sleeping*, it is woken up. | Arguments | Description | |-----------|-------------| -| t | Pointer to task | +| `t` | Pointer to task | #### Returned values http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/aac53ed0/docs/os/core_os/event_queue/event_queue.md ---------------------------------------------------------------------- diff --git a/docs/os/core_os/event_queue/event_queue.md b/docs/os/core_os/event_queue/event_queue.md index 7f3d36d..748673e 100644 --- a/docs/os/core_os/event_queue/event_queue.md +++ b/docs/os/core_os/event_queue/event_queue.md @@ -3,23 +3,23 @@ Event queue is a way of serializing events arring to a task. This makes it easy to queue processing to happen inside task's context. This would be done either from an interrupt handler, or from another task. -Events arrive in a form of a data structure *struct os_event*. +Events arrive in a form of a data structure `struct os_event`. ### Description -Events are in form of a data structure *struct os_event*, and they are queued to data structure *struct os_eventq*. +Events are in form of a data structure `struct os_event`, and they are queued to data structure `struct os_eventq`. -Queue must be initialized before trying to add events to it. This is done using *os_eventq_init()*. +Queue must be initialized before trying to add events to it. This is done using `os_eventq_init()`. -Common way of using event queues is to have a task loop while calling *os_eventq_get()*, waiting for work to do. -Other tasks (or interrupts) then call *os_eventq_put()* to wake it up. Once event has been queued task waiting on that queue is woken up, and will get a pointer to queued event structure. +Common way of using event queues is to have a task loop while calling `os_eventq_get()`, waiting for work to do. +Other tasks (or interrupts) then call `os_eventq_put()` to wake it up. Once event has been queued task waiting on that queue is woken up, and will get a pointer to queued event structure. Processing task would then act according to event type. -When *os_event* is queued, it should not be freed until processing task is done with it. +When `os_event` is queued, it should not be freed until processing task is done with it. -It is assumed that there is only one task consuming events from an event queue. Only one task should be sleeping on a particular *os_eventq* at a time. +It is assumed that there is only one task consuming events from an event queue. Only one task should be sleeping on a particular `os_eventq` at a time. -Note that os_callout subsystem assumes that event queue is used as the wakeup mechanism. +Note that [os_callout](../callout/callout.md) subsystem assumes that event queue is used as the wakeup mechanism. ### Data structures http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/aac53ed0/docs/os/core_os/event_queue/os_eventq_get.md ---------------------------------------------------------------------- diff --git a/docs/os/core_os/event_queue/os_eventq_get.md b/docs/os/core_os/event_queue/os_eventq_get.md index 6cfe242..9bff17c 100644 --- a/docs/os/core_os/event_queue/os_eventq_get.md +++ b/docs/os/core_os/event_queue/os_eventq_get.md @@ -12,12 +12,12 @@ Fetches the first event from a queue. Task will sleep until something gets queue | Arguments | Description | |-----------|-------------| -| evq | Queue to wait on | +| `evq` | Queue to wait on | #### Returned values -Will return with a pointer to first *struct event* which is in the queue. +Will return with a pointer to first `struct event` which is in the queue. #### Notes http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/aac53ed0/docs/os/core_os/event_queue/os_eventq_init.md ---------------------------------------------------------------------- diff --git a/docs/os/core_os/event_queue/os_eventq_init.md b/docs/os/core_os/event_queue/os_eventq_init.md index 5251a89..0c712bd 100644 --- a/docs/os/core_os/event_queue/os_eventq_init.md +++ b/docs/os/core_os/event_queue/os_eventq_init.md @@ -5,13 +5,13 @@ os_eventq_init(struct os_eventq *evq) ``` -Initializes *struct os_eventq*, making it ready for use. +Initializes `struct os_eventq`, making it ready for use. #### Arguments | Arguments | Description | |-----------|-------------| -| evq | Pointer to event queue getting initialized | +| `evq` | Pointer to event queue getting initialized | #### Returned values http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/aac53ed0/docs/os/core_os/event_queue/os_eventq_put.md ---------------------------------------------------------------------- diff --git a/docs/os/core_os/event_queue/os_eventq_put.md b/docs/os/core_os/event_queue/os_eventq_put.md index 9bf3543..d46197c 100644 --- a/docs/os/core_os/event_queue/os_eventq_put.md +++ b/docs/os/core_os/event_queue/os_eventq_put.md @@ -5,15 +5,15 @@ void os_eventq_put(struct os_eventq *evq, struct os_event *ev) ``` -Queues an event to tail of the event queue. +Queues an event to the tail of the event queue. #### Arguments | Arguments | Description | |-----------|-------------| -| evq | Queue where event is being placed | -| ev | Event which is being queued | +| `evq` | Queue where event is being placed | +| `ev` | Event which is being queued | #### Returned values http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/aac53ed0/docs/os/core_os/event_queue/os_eventq_remove.md ---------------------------------------------------------------------- diff --git a/docs/os/core_os/event_queue/os_eventq_remove.md b/docs/os/core_os/event_queue/os_eventq_remove.md index 88cd7c5..7adcd36 100644 --- a/docs/os/core_os/event_queue/os_eventq_remove.md +++ b/docs/os/core_os/event_queue/os_eventq_remove.md @@ -12,8 +12,8 @@ Removes an event which has been placed in a queue. | Arguments | Description | |-----------|-------------| -| evq | Queue where event is being removed from | -| ev | Event which is being removed | +| `evq` | Queue where event is being removed from | +| `ev` | Event which is being removed | #### Returned values @@ -26,7 +26,7 @@ N/A #### Example <Add text to set up the context for the example here> -This is from os_callout_stop(). User wants to stop a callout from getting passed to a task. If the event has already been queued, then remove it before it is seen. +This is from `os_callout_stop()`. User wants to stop a callout from getting passed to a task. If the event has already been queued, then remove it before it is seen. ```c if (c->c_evq) { http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/aac53ed0/docs/os/core_os/heap/heap.md ---------------------------------------------------------------------- diff --git a/docs/os/core_os/heap/heap.md b/docs/os/core_os/heap/heap.md index 1981a4f..efdd5f6 100644 --- a/docs/os/core_os/heap/heap.md +++ b/docs/os/core_os/heap/heap.md @@ -6,7 +6,7 @@ API for doing dynamic memory allocation. ### Description -This provides malloc()/free() functionality with locking. The shared resource heap needs to be protected from concurrent access when OS has been started. *os_malloc()* function grabs a mutex before calling *malloc()*. +This provides `malloc()` & `free()` functionality with locking. The shared resource heap needs to be protected from concurrent access when OS has been started. `os_malloc()` function grabs a mutex before calling `malloc()`. ### Data structures http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/aac53ed0/docs/os/core_os/heap/os_free.md ---------------------------------------------------------------------- diff --git a/docs/os/core_os/heap/os_free.md b/docs/os/core_os/heap/os_free.md index feb4946..9a22ec2 100644 --- a/docs/os/core_os/heap/os_free.md +++ b/docs/os/core_os/heap/os_free.md @@ -11,7 +11,7 @@ Frees previously allocated memory back to the heap. | Arguments | Description | |-----------|-------------| -| mem | Pointer to memory being released | +| `mem` | Pointer to memory being released | #### Returned values @@ -19,7 +19,7 @@ N/A #### Notes -Calls C-library *free()* behind the covers. +Calls C-library `free()` under the covers. #### Example http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/aac53ed0/docs/os/core_os/heap/os_malloc.md ---------------------------------------------------------------------- diff --git a/docs/os/core_os/heap/os_malloc.md b/docs/os/core_os/heap/os_malloc.md index ab6544b..65220a3 100644 --- a/docs/os/core_os/heap/os_malloc.md +++ b/docs/os/core_os/heap/os_malloc.md @@ -4,24 +4,24 @@ void *os_malloc(size_t size) ``` -Allocates *size* number of bytes from heap and returns a pointer to it. +Allocates `size` number of bytes from heap and returns a pointer to it. #### Arguments | Arguments | Description | |-----------|-------------| -| size | Number of bytes to allocate | +| `size` | Number of bytes to allocate | #### Returned values -<ptr>: pointer to memory allocated from heap. -NULL: not enough memory available. +`<ptr>`: pointer to memory allocated from heap. +**NULL**: not enough memory available. #### Notes -*os_malloc()* calls *malloc()*, which is provided by C-library. The heap must be set up during platform initialization. -Depending on which C-library you use, you might have to do the heap setup differently. Most often *malloc()* implementation will maintain a list of allocated and then freed memory blocks. If user asks for memory which cannot be satisfied from free list, they'll call platform's *sbrk()*, which then tries to grow the heap. +`os_malloc()` calls `malloc()`, which is provided by the C-library. The heap must be set up during platform initialization. +Depending on which C-library you use, you might have to do the heap setup differently. Most often `malloc()` implementation will maintain a list of allocated and then freed memory blocks. If user asks for memory which cannot be satisfied from free list, they'll call platform's `sbrk()`, which then tries to grow the heap. #### Example http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/aac53ed0/docs/os/core_os/heap/os_realloc.md ---------------------------------------------------------------------- diff --git a/docs/os/core_os/heap/os_realloc.md b/docs/os/core_os/heap/os_realloc.md index e675155..7e2e08e 100644 --- a/docs/os/core_os/heap/os_realloc.md +++ b/docs/os/core_os/heap/os_realloc.md @@ -5,19 +5,19 @@ void *os_realloc(void *ptr, size_t size) ``` Tries to resize previously allocated memory block, and returns pointer to resized memory. -ptr can be NULL, in which case the call is similar to calling *os_malloc()*. +`ptr` can be **NULL**, in which case the call is similar to calling `os_malloc()`. #### Arguments | Arguments | Description | |-----------|-------------| -| ptr | Pointer to previously allocated memory | -| size | New size to adjust the memory block to | +| `ptr` | Pointer to previously allocated memory | +| `size` | New size to adjust the memory block to | #### Returned values -NULL: size adjustment was not successful. <br> -ptr: pointer to new start of memory block +**NULL**: size adjustment was not successful. <br> +`ptr`: pointer to new start of memory block #### Notes http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/aac53ed0/docs/os/core_os/mbuf/OS_MBUF_DATA.md ---------------------------------------------------------------------- diff --git a/docs/os/core_os/mbuf/OS_MBUF_DATA.md b/docs/os/core_os/mbuf/OS_MBUF_DATA.md index 27effcb..bce48af 100644 --- a/docs/os/core_os/mbuf/OS_MBUF_DATA.md +++ b/docs/os/core_os/mbuf/OS_MBUF_DATA.md @@ -14,8 +14,8 @@ Macro used to cast the data pointer of an mbuf to a given type. | Arguments | Description | |-----------|-------------| -| __om | Pointer to mbuf (struct os_mbuf *) | -| __type | Type to cast | +| `__om` | Pointer to mbuf (struct os_mbuf *) | +| `__type` | Type to cast | <br> http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/aac53ed0/docs/os/core_os/mbuf/OS_MBUF_LEADINGSPACE.md ---------------------------------------------------------------------- diff --git a/docs/os/core_os/mbuf/OS_MBUF_LEADINGSPACE.md b/docs/os/core_os/mbuf/OS_MBUF_LEADINGSPACE.md index a132362..ecbbb1f 100644 --- a/docs/os/core_os/mbuf/OS_MBUF_LEADINGSPACE.md +++ b/docs/os/core_os/mbuf/OS_MBUF_LEADINGSPACE.md @@ -14,13 +14,13 @@ Macro used to get the amount of leading space in an mbuf (in bytes). | Arguments | Description | |-----------|-------------| -| __om | Pointer to mbuf (struct os_mbuf *) | +| `__om` | Pointer to mbuf (struct os_mbuf *) | <br> #### Notes -This macro works on both normal mbufs and packet header mbufs. The amount of leading space is the number of bytes between the current om_data pointer of the mbuf and the start of the mbuf user data buffer. +This macro works on both normal mbufs and packet header mbufs. The amount of leading space is the number of bytes between the current `om_data` pointer of the mbuf and the start of the mbuf user data buffer. <br> http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/aac53ed0/docs/os/core_os/mbuf/OS_MBUF_PKTHDR.md ---------------------------------------------------------------------- diff --git a/docs/os/core_os/mbuf/OS_MBUF_PKTHDR.md b/docs/os/core_os/mbuf/OS_MBUF_PKTHDR.md index 98faaec..c867b16 100644 --- a/docs/os/core_os/mbuf/OS_MBUF_PKTHDR.md +++ b/docs/os/core_os/mbuf/OS_MBUF_PKTHDR.md @@ -14,7 +14,7 @@ Macro used to get a pointer to the os mbuf packet header of an mbuf. | Arguments | Description | |-----------|-------------| -| __om | Pointer to mbuf (struct os_mbuf *) | +| `__om` | Pointer to mbuf (struct os_mbuf *) | <br> http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/aac53ed0/docs/os/core_os/mbuf/OS_MBUF_PKTHDR_TO_MBUF.md ---------------------------------------------------------------------- diff --git a/docs/os/core_os/mbuf/OS_MBUF_PKTHDR_TO_MBUF.md b/docs/os/core_os/mbuf/OS_MBUF_PKTHDR_TO_MBUF.md index 942dcd2..0a9dbf8 100644 --- a/docs/os/core_os/mbuf/OS_MBUF_PKTHDR_TO_MBUF.md +++ b/docs/os/core_os/mbuf/OS_MBUF_PKTHDR_TO_MBUF.md @@ -12,7 +12,7 @@ Macro used to get a pointer to the mbuf given a pointer to the os mbuf packet he | Arguments | Description | |-----------|-------------| -| __hdr | Pointer to os mbuf packet header (struct os_mbuf_pkthdr *) | +| `__hdr` | Pointer to os mbuf packet header (struct os_mbuf_pkthdr *) | <br> http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/aac53ed0/docs/os/core_os/mbuf/OS_MBUF_PKTLEN.md ---------------------------------------------------------------------- diff --git a/docs/os/core_os/mbuf/OS_MBUF_PKTLEN.md b/docs/os/core_os/mbuf/OS_MBUF_PKTLEN.md index 104cca3..fdab0b5 100644 --- a/docs/os/core_os/mbuf/OS_MBUF_PKTLEN.md +++ b/docs/os/core_os/mbuf/OS_MBUF_PKTLEN.md @@ -14,7 +14,7 @@ Macro used to get the length of an entire mbuf chain. | Arguments | Description | |-----------|-------------| -| __om | Pointer to mbuf (struct os_mbuf *) | +| `__om` | Pointer to mbuf (struct os_mbuf *) | <br> http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/aac53ed0/docs/os/core_os/mbuf/OS_MBUF_TRAILINGSPACE.md ---------------------------------------------------------------------- diff --git a/docs/os/core_os/mbuf/OS_MBUF_TRAILINGSPACE.md b/docs/os/core_os/mbuf/OS_MBUF_TRAILINGSPACE.md index d93d948..40a1825 100644 --- a/docs/os/core_os/mbuf/OS_MBUF_TRAILINGSPACE.md +++ b/docs/os/core_os/mbuf/OS_MBUF_TRAILINGSPACE.md @@ -14,13 +14,13 @@ Macro used to get the amount of trailing space in an mbuf (in bytes). | Arguments | Description | |-----------|-------------| -| __om | Pointer to mbuf (struct os_mbuf *) | +| `__om` | Pointer to mbuf (struct os_mbuf *) | <br> #### Notes -This macro works on both normal mbufs and packet header mbufs. The amount of trailing space is the number of bytes between the current om_data pointer of the mbuf and the end of the mbuf. +This macro works on both normal mbufs and packet header mbufs. The amount of trailing space is the number of bytes between the current `om_data` pointer of the mbuf and the end of the mbuf. <br> http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/aac53ed0/docs/os/core_os/mbuf/OS_MBUF_USRHDR.md ---------------------------------------------------------------------- diff --git a/docs/os/core_os/mbuf/OS_MBUF_USRHDR.md b/docs/os/core_os/mbuf/OS_MBUF_USRHDR.md index e54cbb7..024f86e 100644 --- a/docs/os/core_os/mbuf/OS_MBUF_USRHDR.md +++ b/docs/os/core_os/mbuf/OS_MBUF_USRHDR.md @@ -13,7 +13,7 @@ Macro used to get a pointer to the user packet header of an mbuf. | Arguments | Description | |-----------|-------------| -| __om | Pointer to mbuf (struct os_mbuf *). Must be head of chain (i.e. a packet header mbuf) | +| `__om` | Pointer to mbuf (struct os_mbuf *). Must be head of chain (i.e. a packet header mbuf) | <br> http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/aac53ed0/docs/os/core_os/mbuf/OS_MBUF_USRHDR_LEN.md ---------------------------------------------------------------------- diff --git a/docs/os/core_os/mbuf/OS_MBUF_USRHDR_LEN.md b/docs/os/core_os/mbuf/OS_MBUF_USRHDR_LEN.md index ebc8611..529d163 100644 --- a/docs/os/core_os/mbuf/OS_MBUF_USRHDR_LEN.md +++ b/docs/os/core_os/mbuf/OS_MBUF_USRHDR_LEN.md @@ -13,7 +13,7 @@ Macro used to retrieve the length of the user packet header in an mbuf. | Arguments | Description | |-----------|-------------| -| __om | Pointer to mbuf (struct os_mbuf *). Must be head of chain (i.e. a packet header mbuf) | +| `__om` | Pointer to mbuf (struct os_mbuf *). Must be head of chain (i.e. a packet header mbuf) | <br> http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/aac53ed0/docs/os/core_os/mbuf/mbuf.md ---------------------------------------------------------------------- diff --git a/docs/os/core_os/mbuf/mbuf.md b/docs/os/core_os/mbuf/mbuf.md index 4f14818..01b6a8c 100644 --- a/docs/os/core_os/mbuf/mbuf.md +++ b/docs/os/core_os/mbuf/mbuf.md @@ -10,7 +10,7 @@ The main reason is to conserve memory. Consider a networking protocol that gener ### Packet Header mbuf -Not all mbufs are created equal. The first mbuf in a chain of mbufs is a special mbuf called a "packet header mbuf". The reason that this mbuf is special is that it contains the length of all the data contained by the chain of mbufs (the packet length, in other words). The packet header mbuf may also contain a user defined structure (called a "user header") so that networking protocol specific information can be conveyed to various layers of the networking stack. Any mbufs that are part of the packet (i.e. in the mbuf chain but not the first one) are "normal" (i.e. non-packet header) mbufs. A normal mbuf does not have any packet header or user packet header structures in them; they only contain the basic mbuf header (`struct os_mbuf`). Figure 1 illustrates these two types of mbufs. Note that the numbers/text in parentheses denote the size of the structures/elements (in bytes) and that MBLEN is the memory block length of the memory pool used by the mbuf pool. +Not all mbufs are created equal. The first mbuf in a chain of mbufs is a special mbuf called a "packet header mbuf". The reason that this mbuf is special is that it contains the length of all the data contained by the chain of mbufs (the packet length, in other words). The packet header mbuf may also contain a user defined structure (called a "user header") so that networking protocol specific information can be conveyed to various layers of the networking stack. Any mbufs that are part of the packet (i.e. in the mbuf chain but not the first one) are "normal" (i.e. non-packet header) mbufs. A normal mbuf does not have any packet header or user packet header structures in them; they only contain the basic mbuf header (`struct os_mbuf`). Figure 1 illustrates these two types of mbufs. Note that the numbers/text in parentheses denote the size of the structures/elements (in bytes) and that `MBLEN` is the memory block length of the memory pool used by the mbuf pool.  @@ -18,28 +18,28 @@ Not all mbufs are created equal. The first mbuf in a chain of mbufs is a special Now let's take a deeper dive into the mbuf structure. Figure 2 illustrates a normal mbuf and breaks out the various fields in the `os_mbuf` structure. -* The *om_data* field is a pointer to where the data starts inside the data buffer. Typically, mbufs that are allocated from the mbuf pool (discussed later) have their om_data pointer set to the start of the data buffer but there are cases where this may not be desirable (added a protocol header to a packet, for example). -* The *om_flags* field is a set of flags used internally by the mbuf library. Currently, no flags have been defined. -* The *om_pkthdr_len* field is the total length of all packet headers in the mbuf. For normal mbufs this is set to 0 as there is no packet or user packet headers. For packet header mbufs, this would be set to the length of the packet header structure (16) plus the size of the user packet header (if any). Note that it is this field which differentiates packet header mbufs from normal mbufs (i.e. if *om_pkthdr_len* is zero, this is a normal mbuf; otherwise it is a packet header mbuf). -* The *om_len* field contains the amount of user data in the data buffer. When initially allocated, this field is 0 as there is no user data in the mbuf. -* The *omp_pool* field is a pointer to the pool from which this mbuf has been allocated. This is used internally by the mbuf library. -* The *omp_next* field is a linked list element which is used to chain mbufs. +* The `om_data` field is a pointer to where the data starts inside the data buffer. Typically, mbufs that are allocated from the mbuf pool (discussed later) have their `om_data` pointer set to the start of the data buffer but there are cases where this may not be desirable (added a protocol header to a packet, for example). +* The `om_flags` field is a set of flags used internally by the mbuf library. Currently, no flags have been defined. +* The `om_pkthdr_len` field is the total length of all packet headers in the mbuf. For normal mbufs this is set to 0 as there is no packet or user packet headers. For packet header mbufs, this would be set to the length of the packet header structure (16) plus the size of the user packet header (if any). Note that it is this field which differentiates packet header mbufs from normal mbufs (i.e. if `om_pkthdr_len` is zero, this is a normal mbuf; otherwise it is a packet header mbuf). +* The `om_len` field contains the amount of user data in the data buffer. When initially allocated, this field is 0 as there is no user data in the mbuf. +* The `omp_pool` field is a pointer to the pool from which this mbuf has been allocated. This is used internally by the mbuf library. +* The `omp_next` field is a linked list element which is used to chain mbufs. -Figure 2 also shows a normal mbuf with actual values in the `os_mbuf` structure. This mbuf starts at address 0x1000 and is 256 bytes in total length. In this example, the user has copied 33 bytes into the data buffer starting at address 0x1010 (this is where om_data points). Note that the packet header length in this mbuf is 0 as it is not a packet header mbuf. +Figure 2 also shows a normal mbuf with actual values in the `os_mbuf` structure. This mbuf starts at address 0x1000 and is 256 bytes in total length. In this example, the user has copied 33 bytes into the data buffer starting at address 0x1010 (this is where `om_data` points). Note that the packet header length in this mbuf is 0 as it is not a packet header mbuf.  -Figure 3 illustrates the packet header mbuf along with some chained mbufs (i.e a "packet"). In this example, the user header structure is defined to be 8 bytes. Note that in figure 3 we show a number of different mbufs with varying *om_data* pointers and lengths since we want to show various examples of valid mbufs. For all the mbufs (both packet header and normal ones) the total length of the memory block is 128 bytes. +Figure 3 illustrates the packet header mbuf along with some chained mbufs (i.e a "packet"). In this example, the user header structure is defined to be 8 bytes. Note that in figure 3 we show a number of different mbufs with varying `om_data` pointers and lengths since we want to show various examples of valid mbufs. For all the mbufs (both packet header and normal ones) the total length of the memory block is 128 bytes.  ### Mbuf pools -Mbufs are collected into "mbuf pools" much like memory blocks. The mbuf pool itself contains a pointer to a memory pool. The memory blocks in this memory pool are the actual mbufs; both normal and packet header mbufs. Thus, the memory block (and corresponding memory pool) must be sized correctly. In other words, the memory blocks which make up the memory pool used by the mbuf pool must be at least: sizeof(struct os_mbuf) + sizeof(struct os_mbuf_pkthdr) + sizeof(struct user_defined_header) + desired minimum data buffer length. For example, if the developer wants mbufs to contain at least 64 bytes of user data and they have a user header of 12 bytes, the size of the memory block would be (at least): 64 + 12 + 16 + 8, or 100 bytes. Yes, this is a fair amount of overhead. However, the flexibility provided by the mbuf library usually outweighs overhead concerns. +Mbufs are collected into "mbuf pools" much like memory blocks. The mbuf pool itself contains a pointer to a memory pool. The memory blocks in this memory pool are the actual mbufs; both normal and packet header mbufs. Thus, the memory block (and corresponding memory pool) must be sized correctly. In other words, the memory blocks which make up the memory pool used by the mbuf pool must be at least: `sizeof(struct os_mbuf)` + `sizeof(struct os_mbuf_pkthdr)` + `sizeof(struct user_defined_header)` + *desired minimum data buffer length*. For example, if the developer wants mbufs to contain at least 64 bytes of user data and they have a user header of 12 bytes, the size of the memory block would be (at least): 64 + 12 + 16 + 8, or 100 bytes. Yes, this is a fair amount of overhead. However, the flexibility provided by the mbuf library usually outweighs overhead concerns. ### Create mbuf pool -Creating an mbuf pool is fairly simple: create a memory pool and then create the mbuf pool using that memory pool. Once the developer has determined the size of the user data needed per mbuf (this is based on the application/networking stack and is outside the scope of this discussion) and the size of the user header (if any), the memory blocks can be sized. In the example shown below, the application requires 64 bytes of user data per mbuf and also allocates a user header (called struct user_hdr). Note that we do not show the user header data structure as there really is no need; all we need to do is to account for it when creating the memory pool. In the example, we use the macro *MBUF_PKTHDR_OVERHEAD* to denote the amount of packet header overhead per mbuf and *MBUF_MEMBLOCK_OVERHEAD* to denote the total amount of overhead required per memory block. The macro *MBUF_BUF_SIZE* is used to denote the amount of payload that the application requires (aligned on a 32-bit boundary in thi s case). All this leads to the total memory block size required, denoted by the macro *MBUF_MEMBLOCK_OVERHEAD*. +Creating an mbuf pool is fairly simple: create a memory pool and then create the mbuf pool using that memory pool. Once the developer has determined the size of the user data needed per mbuf (this is based on the application/networking stack and is outside the scope of this discussion) and the size of the user header (if any), the memory blocks can be sized. In the example shown below, the application requires 64 bytes of user data per mbuf and also allocates a user header (called `struct user_hdr`). Note that we do not show the user header data structure as there really is no need; all we need to do is to account for it when creating the memory pool. In the example, we use the macro `MBUF_PKTHDR_OVERHEAD` to denote the amount of packet header overhead per mbuf and `MBUF_MEMBLOCK_OVERHEAD` to denote the total amount of overhead required per memory block. The macro `MBUF_BUF_SIZE` is used to denote the amount of payload that the application requires (aligned on a 32-bit boundary in t his case). All this leads to the total memory block size required, denoted by the macro `MBUF_MEMBLOCK_OVERHEAD`. ```c @@ -106,9 +106,9 @@ mbuf_usage_example1(uint8_t *mydata, int mydata_length) } ``` -In `example2` we show use of the pullup api as this illustrates some of the typical pitfalls developers encounter when using mbufs. The first pitfall is one of alignment/padding. Depending on the processor and/or compiler, the sizeof() a structure may vary. Thus, the size of *my_protocol_header* may be different inside the packet data of the mbuf than the size of the structure on the stack or as a global variable, for instance. While some networking protcols may align protocol information on convenient processor boundaries many others try to conserve bytes "on the air" (i.e inside the packet data). Typical methods used to deal with this are "packing" the structure (i.e. force compiler to not pad) or creating protocol headers that do not require padding. `example2` assumes that one of these methods was used when defining the *my_protocol_header* structure. +In `example2` we show use of the pullup api as this illustrates some of the typical pitfalls developers encounter when using mbufs. The first pitfall is one of alignment/padding. Depending on the processor and/or compiler, the `sizeof()` a structure may vary. Thus, the size of `my_protocol_header` may be different inside the packet data of the mbuf than the size of the structure on the stack or as a global variable, for instance. While some networking protcols may align protocol information on convenient processor boundaries many others try to conserve bytes "on the air" (i.e inside the packet data). Typical methods used to deal with this are "packing" the structure (i.e. force compiler to not pad) or creating protocol headers that do not require padding. `example2` assumes that one of these methods was used when defining the `my_protocol_header` structure. -Another common pitfall occurs around endianness. A network protocol may be little endian or big endian; it all depends on the protocol specification. Processors also have an endianness; this means that the developer has to be careful that the processor endianness and the protocol endianness are handled correctly. In `example2`, some common networking functions are used: `ntohs()` and `ntohl()`. These are shorthand for "network order to host order, short" and "network order to host order, long". Basically, these functions convert data of a certain size (i.e. 16 bits, 32 bits, etc) to the endianness of the host. Network byte order is big-endian (most significant byte first), so these functions convert big-endian byte order to host order (thus, the implementation of these functions is host dependent). Note that the BLE networking stack "on the air" format is least signigicant byte first (i.e. little endian), so a "bletoh" function would have to take little endian format and convert to host format. +Another common pitfall occurs around endianness. A network protocol may be little endian or big endian; it all depends on the protocol specification. Processors also have an endianness; this means that the developer has to be careful that the processor endianness and the protocol endianness are handled correctly. In `example2`, some common networking functions are used: `ntohs()` and `ntohl()`. These are shorthand for "network order to host order, short" and "network order to host order, long". Basically, these functions convert data of a certain size (i.e. 16 bits, 32 bits, etc) to the endianness of the host. Network byte order is big-endian (most significant byte first), so these functions convert big-endian byte order to host order (thus, the implementation of these functions is host dependent). Note that the BLE networking stack "on the air" format is least signigicant byte first (i.e. little-endian), so a `bletoh` function would have to take little-endian format and convert to host format. A long story short: the developer must take care when copying structure data to/from mbufs and flat buffers! http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/aac53ed0/docs/os/core_os/mbuf/os_mbuf_adj.md ---------------------------------------------------------------------- diff --git a/docs/os/core_os/mbuf/os_mbuf_adj.md b/docs/os/core_os/mbuf/os_mbuf_adj.md index a3881b4..c89a4a8 100644 --- a/docs/os/core_os/mbuf/os_mbuf_adj.md +++ b/docs/os/core_os/mbuf/os_mbuf_adj.md @@ -4,7 +4,7 @@ void os_mbuf_adj(struct os_mbuf *mp, int req_len); ``` -Trims *req_len* bytes from either the head (if positive) or tail (if negative) of an mbuf chain. Adjusts the packet length of the mbuf chain if *mp* points to a packet header mbuf. When trimming from the head, no mbufs are freed. When trimming from the tail, any mbufs of zero length left at the end of the chain are freed. +Trims `req_len` bytes from either the head (if positive) or tail (if negative) of an mbuf chain. Adjusts the packet length of the mbuf chain if `mp` points to a packet header mbuf. When trimming from the head, no mbufs are freed. When trimming from the tail, any mbufs of zero length left at the end of the chain are freed. <br> @@ -12,8 +12,8 @@ Trims *req_len* bytes from either the head (if positive) or tail (if negative) o | Arguments | Description | |-----------|-------------| -| mp | Pointer to mbuf. Can be head of a chain of mbufs, a single mbuf or a packet header mbuf | -| req_len | Number of bytes to trim from head or tail of mbuf +| `mp` | Pointer to mbuf. Can be head of a chain of mbufs, a single mbuf or a packet header mbuf | +| `req_len` | Number of bytes to trim from head or tail of mbuf <br> http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/aac53ed0/docs/os/core_os/mbuf/os_mbuf_append.md ---------------------------------------------------------------------- diff --git a/docs/os/core_os/mbuf/os_mbuf_append.md b/docs/os/core_os/mbuf/os_mbuf_append.md index 423409f..8d66e18 100644 --- a/docs/os/core_os/mbuf/os_mbuf_append.md +++ b/docs/os/core_os/mbuf/os_mbuf_append.md @@ -4,7 +4,7 @@ int os_mbuf_append(struct os_mbuf *om, const void *data, uint16_t len) ``` -Appends a data buffer of length *len* to the end of an mbuf chain, adjusting packet length if *om* is a packet header mbuf. If not enough trailing space exists at the end of the mbuf chain, mbufs are allocated to hold the data. +Appends a data buffer of length `len` to the end of an mbuf chain, adjusting packet length if `om` is a packet header mbuf. If not enough trailing space exists at the end of the mbuf chain, mbufs are allocated to hold the data. <br> @@ -12,9 +12,9 @@ Appends a data buffer of length *len* to the end of an mbuf chain, adjusting pac | Arguments | Description | |-----------|-------------| -| om | Pointer to mbuf. Can be head of a chain of mbufs, a single mbuf or a packet header mbuf | -| data | Pointer to data buffer to copy from | -| len | Number of bytes to copy from data buffer to the end of the mbuf | +| `om` | Pointer to mbuf. Can be head of a chain of mbufs, a single mbuf or a packet header mbuf | +| `data` | Pointer to data buffer to copy from | +| `len` | Number of bytes to copy from data buffer to the end of the mbuf | <br> @@ -22,8 +22,8 @@ Appends a data buffer of length *len* to the end of an mbuf chain, adjusting pac #### Returned values 0: success -OS_ENOMEM: Could not allocate enough mbufs to hold data. -OS_EINVAL: *om* was NULL on entry. +`OS_ENOMEM`: Could not allocate enough mbufs to hold data. +`OS_EINVAL`: `om` was **NULL** on entry. <br> @@ -32,7 +32,7 @@ If not enough mbufs were available the packet header length of the mbuf may get <br> -If any mbufs are allocated, they are allocated from the same pool as *om* +If any mbufs are allocated, they are allocated from the same pool as `om` <br> http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/aac53ed0/docs/os/core_os/mbuf/os_mbuf_concat.md ---------------------------------------------------------------------- diff --git a/docs/os/core_os/mbuf/os_mbuf_concat.md b/docs/os/core_os/mbuf/os_mbuf_concat.md index 69df9f6..5ef32fd 100644 --- a/docs/os/core_os/mbuf/os_mbuf_concat.md +++ b/docs/os/core_os/mbuf/os_mbuf_concat.md @@ -12,8 +12,8 @@ Attaches a second mbuf chain onto the end of the first. If the first chain conta | Arguments | Description | |-----------|-------------| -| first | Pointer to first mbuf chain | -| second | Pointer to second mbuf chain | +| `first` | Pointer to first mbuf chain | +| `second` | Pointer to second mbuf chain | <br> http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/aac53ed0/docs/os/core_os/mbuf/os_mbuf_copydata.md ---------------------------------------------------------------------- diff --git a/docs/os/core_os/mbuf/os_mbuf_copydata.md b/docs/os/core_os/mbuf/os_mbuf_copydata.md index ff2dcd0..25e24fe 100644 --- a/docs/os/core_os/mbuf/os_mbuf_copydata.md +++ b/docs/os/core_os/mbuf/os_mbuf_copydata.md @@ -4,7 +4,7 @@ int os_mbuf_copydata(const struct os_mbuf *m, int off, int len, void *dst) ``` -Copy data from an mbuf chain starting *off* bytes from the beginning, continuing for *len* bytes, into the indicated buffer. +Copy data from an mbuf chain starting `off` bytes from the beginning, continuing for `len` bytes, into the indicated buffer. <br> @@ -12,10 +12,10 @@ Copy data from an mbuf chain starting *off* bytes from the beginning, continuing | Arguments | Description | |-----------|-------------| -| m | Pointer to mbuf chain | -| off | Start copy offset, in bytes, from beginning of mbuf chain | -| len | Number of bytes to copy | -| dst | Data buffer to copy into | +| `m` | Pointer to mbuf chain | +| `off` | Start copy offset, in bytes, from beginning of mbuf chain | +| `len` | Number of bytes to copy | +| `dst` | Data buffer to copy into | <br> http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/aac53ed0/docs/os/core_os/mbuf/os_mbuf_copyinto.md ---------------------------------------------------------------------- diff --git a/docs/os/core_os/mbuf/os_mbuf_copyinto.md b/docs/os/core_os/mbuf/os_mbuf_copyinto.md index 6c18f57..ed6dd68 100644 --- a/docs/os/core_os/mbuf/os_mbuf_copyinto.md +++ b/docs/os/core_os/mbuf/os_mbuf_copyinto.md @@ -12,10 +12,10 @@ Copies the contents of a flat buffer into an mbuf chain, starting at the specifi | Arguments | Description | |-----------|-------------| -| om | Pointer to mbuf chain | -| off | Start copy offset, in bytes, from beginning of mbuf chain | -| src | Address from which bytes are copied | -| len | Number of bytes to copy from src | +| `om` | Pointer to mbuf chain | +| `off` | Start copy offset, in bytes, from beginning of mbuf chain | +| `src` | Address from which bytes are copied | +| `len` | Number of bytes to copy from src | <br> http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/aac53ed0/docs/os/core_os/mbuf/os_mbuf_dup.md ---------------------------------------------------------------------- diff --git a/docs/os/core_os/mbuf/os_mbuf_dup.md b/docs/os/core_os/mbuf/os_mbuf_dup.md index 13f9d9e..df32960 100644 --- a/docs/os/core_os/mbuf/os_mbuf_dup.md +++ b/docs/os/core_os/mbuf/os_mbuf_dup.md @@ -12,13 +12,13 @@ Duplicate a chain of mbufs. Return the start of the duplicated chain. | Arguments | Description | |-----------|-------------| -| om | Pointer to mbuf chain to duplicate | +| `om` | Pointer to mbuf chain to duplicate | <br> #### Returned values -Pointer to the duplicated chain or NULL if not enough mbufs were available to duplicate the chain. +Pointer to the duplicated chain or **NULL** if not enough mbufs were available to duplicate the chain. <br> http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/aac53ed0/docs/os/core_os/mbuf/os_mbuf_extend.md ---------------------------------------------------------------------- diff --git a/docs/os/core_os/mbuf/os_mbuf_extend.md b/docs/os/core_os/mbuf/os_mbuf_extend.md index 3986e37..3db1001 100644 --- a/docs/os/core_os/mbuf/os_mbuf_extend.md +++ b/docs/os/core_os/mbuf/os_mbuf_extend.md @@ -12,16 +12,16 @@ Increases the length of an mbuf chain by the specified amount. If there is not | Arguments | Description | |-----------|-------------| -| om | Pointer to mbuf chain | -| len | Number of bytes to increase packet header | +| `om` | Pointer to mbuf chain | +| `len` | Number of bytes to increase packet header | <br> #### Returned values -Pointer to start of extended data. Caller is guaranteed that there are at least *len* bytes from this pointer to the end of the mbuf. +Pointer to start of extended data. Caller is guaranteed that there are at least `len` bytes from this pointer to the end of the mbuf. -Returns NULL if extension fails due to insufficient mbufs or *len* too large. +Returns **NULL** if extension fails due to insufficient mbufs or `len` too large. <br> http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/aac53ed0/docs/os/core_os/mbuf/os_mbuf_free_chain.md ---------------------------------------------------------------------- diff --git a/docs/os/core_os/mbuf/os_mbuf_free_chain.md b/docs/os/core_os/mbuf/os_mbuf_free_chain.md index 660fa5a..17ec186 100644 --- a/docs/os/core_os/mbuf/os_mbuf_free_chain.md +++ b/docs/os/core_os/mbuf/os_mbuf_free_chain.md @@ -12,7 +12,7 @@ Frees a chain of mbufs | Arguments | Description | |-----------|-------------| -| om | Pointer to mbuf chain | +| `om` | Pointer to mbuf chain | <br> http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/aac53ed0/docs/os/core_os/mbuf/os_mbuf_get.md ---------------------------------------------------------------------- diff --git a/docs/os/core_os/mbuf/os_mbuf_get.md b/docs/os/core_os/mbuf/os_mbuf_get.md index 96aa273..fe04dd6 100644 --- a/docs/os/core_os/mbuf/os_mbuf_get.md +++ b/docs/os/core_os/mbuf/os_mbuf_get.md @@ -4,7 +4,7 @@ struct os_mbuf *os_mbuf_get(struct os_mbuf_pool *omp, uint16_t leadingspace) ``` -Get an mbuf from the mbuf pool. The mbuf is allocated, and initialized prior to being returned. The *leadingspace* parameter allows the user to specify the amount of leading space in the allocated mbuf. +Get an mbuf from the mbuf pool. The mbuf is allocated, and initialized prior to being returned. The `eadingspace` parameter allows the user to specify the amount of leading space in the allocated mbuf. <br> @@ -13,14 +13,14 @@ Get an mbuf from the mbuf pool. The mbuf is allocated, and initialized prior to | Arguments | Description | |-----------|-------------| -| om | Pointer to mbuf pool from which to allocate mbuf | -| leadingspace | Amount of leading space in allocated mbuf. Request cannot exceed the mbuf data buffer size. | +| `om` | Pointer to mbuf pool from which to allocate mbuf | +| `leadingspace` | Amount of leading space in allocated mbuf. Request cannot exceed the mbuf data buffer size. | <br> #### Returned values -Returns a pointer to the allocated mbuf or NULL if there are no mbufs available or *leadingspace* was too large. +Returns a pointer to the allocated mbuf or **NULL** if there are no mbufs available or `leadingspace` was too large. <br> #### Notes http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/aac53ed0/docs/os/core_os/mbuf/os_mbuf_get_pkthdr.md ---------------------------------------------------------------------- diff --git a/docs/os/core_os/mbuf/os_mbuf_get_pkthdr.md b/docs/os/core_os/mbuf/os_mbuf_get_pkthdr.md index d975b4b..304aef8 100644 --- a/docs/os/core_os/mbuf/os_mbuf_get_pkthdr.md +++ b/docs/os/core_os/mbuf/os_mbuf_get_pkthdr.md @@ -4,7 +4,7 @@ struct os_mbuf *os_mbuf_get_pkthdr(struct os_mbuf_pool *omp, uint8_t pkthdr_len); ``` -Allocates a packet header mbuf from the mbuf pool pointed to by *omp*. Adds a user header of length *pkthdr_len* to packet header mbuf. +Allocates a packet header mbuf from the mbuf pool pointed to by `omp`. Adds a user header of length `pkthdr_len` to packet header mbuf. <br> @@ -12,19 +12,19 @@ Allocates a packet header mbuf from the mbuf pool pointed to by *omp*. Adds a us | Arguments | Description | |-----------|-------------| -| om | Pointer to mbuf pool from which to allocate mbuf | -| pkthdr_len | The user header packet length to allocate for the packet header mbuf | +| `om` | Pointer to mbuf pool from which to allocate mbuf | +| `pkthdr_len` | The user header packet length to allocate for the packet header mbuf | <br> #### Returned values -Returns a pointer to the allocated mbuf or NULL if there are no mbufs available or the user packet header was too large. +Returns a pointer to the allocated mbuf or **NULL** if there are no mbufs available or the user packet header was too large. <br> #### Notes -The packet header mbuf returned will have its data pointer incremented by the sizeof(struct os_mbuf_pkthdr) as well as the amount of user header data (i.e. *pkthdr_len*). In other words, the data pointer is offset from the start of the mbuf by: sizeof(struct os_mbuf) + sizeof(struct os_mbuf_pkthdr) + pkthdr_len. The `om_pkthdr_len` element in the allocated mbuf is set to: sizeof(struct os_mbuf_pkthdr) + pkthdr_len. +The packet header mbuf returned will have its data pointer incremented by the `sizeof(struct os_mbuf_pkthdr)` as well as the amount of user header data (i.e. `pkthdr_len`). In other words, the data pointer is offset from the start of the mbuf by: `sizeof(struct os_mbuf)` + `sizeof(struct os_mbuf_pkthdr)` + `pkthdr_len`. The `om_pkthdr_len` element in the allocated mbuf is set to: `sizeof(struct os_mbuf_pkthdr)` + `pkthdr_len`. <br> http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/aac53ed0/docs/os/core_os/mbuf/os_mbuf_memcmp.md ---------------------------------------------------------------------- diff --git a/docs/os/core_os/mbuf/os_mbuf_memcmp.md b/docs/os/core_os/mbuf/os_mbuf_memcmp.md index 20ca328..b2315c9 100644 --- a/docs/os/core_os/mbuf/os_mbuf_memcmp.md +++ b/docs/os/core_os/mbuf/os_mbuf_memcmp.md @@ -12,10 +12,10 @@ Performs a memory compare of the specified region of an mbuf chain against a fla | Arguments | Description | |-----------|-------------| -| om | Pointer to mbuf | -| off | Offset, in bytes, from start of mbuf to start of comparison | -| data | Pointer to flat data buffer to compare | -| len | Number of bytes to compare | +| `om` | Pointer to mbuf | +| `off` | Offset, in bytes, from start of mbuf to start of comparison | +| `data` | Pointer to flat data buffer to compare | +| `len` | Number of bytes to compare | <br> @@ -25,7 +25,7 @@ A value of zero means the memory regions are identical; all other values represe <br> #### Notes -This function will compare bytes starting from *off* bytes from the start of the mbuf chain with a data buffer. +This function will compare bytes starting from `off` bytes from the start of the mbuf chain with a data buffer. <br> http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/aac53ed0/docs/os/core_os/mbuf/os_mbuf_off.md ---------------------------------------------------------------------- diff --git a/docs/os/core_os/mbuf/os_mbuf_off.md b/docs/os/core_os/mbuf/os_mbuf_off.md index 9c9f790..b6fa810 100644 --- a/docs/os/core_os/mbuf/os_mbuf_off.md +++ b/docs/os/core_os/mbuf/os_mbuf_off.md @@ -4,7 +4,7 @@ struct os_mbuf *os_mbuf_off(struct os_mbuf *om, int off, int *out_off) ``` -Given an offset in the packet (i.e. user data byte offset in the mbuf chain), return the mbuf and the offset in that mbuf where byte 'off' is located. Note that the offset is 'returned' in *out_off*. +Given an offset in the packet (i.e. user data byte offset in the mbuf chain), return the mbuf and the offset in that mbuf where byte 'off' is located. Note that the offset is *returned* in `out_off`. <br> @@ -12,21 +12,21 @@ Given an offset in the packet (i.e. user data byte offset in the mbuf chain), re | Arguments | Description | |-----------|-------------| -| om | Pointer to mbuf | -| off | Location in mbuf chain of desired byte offset | -| out_off | Pointer to storage for the relative offset of the absolute location in the returned mbuf | +| `om` | Pointer to mbuf | +| `off` | Location in mbuf chain of desired byte offset | +| `out_off` | Pointer to storage for the relative offset of the absolute location in the returned mbuf | <br> #### Returned values -NULL if the offset is not within the mbuf chain or *om* points to NULL. +**NULL** if the offset is not within the mbuf chain or `om` points to **NULL**. <br> #### Notes The user is allowed to call this function with the length of the mbuf chain but no greater. This allows the user to get the mbuf and offset (in that mbuf) where the next user data byte should be written. -While this api is provided to the user, other API are expected to be used by the applciation developer (i.e. `os_mbuf_append()` or `os_mbuf_copyinto()`). +While this api is provided to the user, other APIs are expected to be used by the applciation developer (i.e. `os_mbuf_append()` or `os_mbuf_copyinto()`). <br> #### Example http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/aac53ed0/docs/os/core_os/mbuf/os_mbuf_pool_init.md ---------------------------------------------------------------------- diff --git a/docs/os/core_os/mbuf/os_mbuf_pool_init.md b/docs/os/core_os/mbuf/os_mbuf_pool_init.md index b3ae463..aa3b11b 100644 --- a/docs/os/core_os/mbuf/os_mbuf_pool_init.md +++ b/docs/os/core_os/mbuf/os_mbuf_pool_init.md @@ -13,10 +13,10 @@ Initialize an mbuf pool | Arguments | Description | |-----------|-------------| -| omp | Pointer to mbuf pool to initialize | -| mp | Pointer to memory pool used by mbuf pool | -| buf_len | The size of the memory blocks in the memory pool used by the mbuf pool | -| nbufs | The number of mbufs in the pool | +| `omp` | Pointer to mbuf pool to initialize | +| `mp` | Pointer to memory pool used by mbuf pool | +| `buf_len` | The size of the memory blocks in the memory pool used by the mbuf pool | +| `nbufs` | The number of mbufs in the pool | <br> @@ -26,7 +26,7 @@ Initialize an mbuf pool <br> #### Notes -The parameter *buf_len* is the total size of the memory block. This must accommodate the os_mbuf structure, the os_mbuf_pkthdr structure, any user headers plus the desired amount of user data. +The parameter `buf_len` is the total size of the memory block. This must accommodate the `os_mbuf` structure, the `os_mbuf_pkthdr` structure, any user headers plus the desired amount of user data. <br> http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/aac53ed0/docs/os/core_os/mbuf/os_mbuf_prepend.md ---------------------------------------------------------------------- diff --git a/docs/os/core_os/mbuf/os_mbuf_prepend.md b/docs/os/core_os/mbuf/os_mbuf_prepend.md index ab146df..91629ec 100644 --- a/docs/os/core_os/mbuf/os_mbuf_prepend.md +++ b/docs/os/core_os/mbuf/os_mbuf_prepend.md @@ -12,18 +12,18 @@ Increases the length of an mbuf chain by adding data to the front. If there is | Arguments | Description | |-----------|-------------| -| om | Pointer to mbuf | -| len | Length, in bytes, to prepend | +| `om` | Pointer to mbuf | +| `len` | Length, in bytes, to prepend | <br> #### Returned values -Pointer to mbuf at head of chain; NULL if not enough mbufs were available to accommodate *len*. +Pointer to mbuf at head of chain; **NULL** if not enough mbufs were available to accommodate `len`. <br> #### Notes -If *om* is a packet header mbuf, the total length of the packet is adjusted by *len*. Note that the returned mbuf may not point to *om* if insufficient leading space was available in *om*. +If `om` is a packet header mbuf, the total length of the packet is adjusted by `len`. Note that the returned mbuf may not point to `om` if insufficient leading space was available in `om`. <br> http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/aac53ed0/docs/os/core_os/mbuf/os_mbuf_pullup.md ---------------------------------------------------------------------- diff --git a/docs/os/core_os/mbuf/os_mbuf_pullup.md b/docs/os/core_os/mbuf/os_mbuf_pullup.md index 3a9fdc4..8bce3ad 100644 --- a/docs/os/core_os/mbuf/os_mbuf_pullup.md +++ b/docs/os/core_os/mbuf/os_mbuf_pullup.md @@ -4,7 +4,7 @@ struct os_mbuf *os_mbuf_pullup(struct os_mbuf *om, uint16_t len) ``` -Rearrange an mbuf chain so that len bytes are contiguous, and in the data area of an mbuf (so that OS_MBUF_DATA() will work on a structure of size len.) Returns the resulting mbuf chain on success, free's it and returns NULL on failure. +Rearrange an mbuf chain so that len bytes are contiguous, and in the data area of an mbuf (so that `OS_MBUF_DATA()` will work on a structure of size `len`.) Returns the resulting mbuf chain on success, free's it and returns **NULL** on failure. <br> @@ -12,13 +12,13 @@ Rearrange an mbuf chain so that len bytes are contiguous, and in the data area o | Arguments | Description | |-----------|-------------| -| om | Pointer to mbuf | -| len | Length, in bytes, to pullup (make contiguous in mbuf) | +| `om` | Pointer to mbuf | +| `len` | Length, in bytes, to pullup (make contiguous in mbuf) | <br> #### Returned values -Pointer to mbuf at head of chain; NULL if not enough mbufs were available to accommodate *len* or if the requested pullup size was too large. +Pointer to mbuf at head of chain; **NULL** if not enough mbufs were available to accommodate `len` or if the requested pullup size was too large. <br> http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/aac53ed0/docs/os/core_os/memory_pool/OS_MEMPOOL_BYTES.md ---------------------------------------------------------------------- diff --git a/docs/os/core_os/memory_pool/OS_MEMPOOL_BYTES.md b/docs/os/core_os/memory_pool/OS_MEMPOOL_BYTES.md index dc7fc33..65aaaae 100644 --- a/docs/os/core_os/memory_pool/OS_MEMPOOL_BYTES.md +++ b/docs/os/core_os/memory_pool/OS_MEMPOOL_BYTES.md @@ -4,22 +4,22 @@ OS_MEMPOOL_BYTES(n,blksize) ``` -Calculates how many bytes of memory is used by *n* number of elements, when individual element size is *blksize* bytes. +Calculates how many bytes of memory is used by `n` number of elements, when individual element size is `blksize` bytes. <br> #### Arguments | Arguments | Description | |-----------|-------------| -| n | Number of elements | -| blksize | Size of an element is number of bytes | +| `n` | Number of elements | +| `blksize` | Size of an element is number of bytes | #### Returned values The number of bytes used by the memory pool. <br> #### Notes -OS_MEMPOOL_BYTES is a macro and not a function. +`OS_MEMPOOL_BYTES` is a macro and not a function. <br> #### Example http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/aac53ed0/docs/os/core_os/memory_pool/OS_MEMPOOL_SIZE.md ---------------------------------------------------------------------- diff --git a/docs/os/core_os/memory_pool/OS_MEMPOOL_SIZE.md b/docs/os/core_os/memory_pool/OS_MEMPOOL_SIZE.md index 577547e..e0f3247 100644 --- a/docs/os/core_os/memory_pool/OS_MEMPOOL_SIZE.md +++ b/docs/os/core_os/memory_pool/OS_MEMPOOL_SIZE.md @@ -4,31 +4,31 @@ OS_MEMPOOL_SIZE(n,blksize) ``` -Calculates the number of os_membuf_t elements used by *n* blocks of size *blksize* bytes. +Calculates the number of `os_membuf_t` elements used by `n` blocks of size `blksize` bytes. -Note that os_membuf_t is used so that memory blocks are aligned on OS_ALIGNMENT boundaries. +Note that `os_membuf_t` is used so that memory blocks are aligned on `OS_ALIGNMENT` boundaries. -The *blksize* variable is the minimum number of bytes required for each block; the actual block size is padded so that each block is aligned on OS_ALIGNMENT boundaries. +The `blksize` variable is the minimum number of bytes required for each block; the actual block size is padded so that each block is aligned on `OS_ALIGNMENT` boundaries. <br> #### Arguments | Arguments | Description | |-----------|-------------| -| n | Number of elements | -| blksize | Size of an element is number of bytes | +| `n` | Number of elements | +| `blksize` | Size of an element is number of bytes | #### Returned values -The number of os_membuf_t elements used by the memory pool. Note that os_membuf_t is defined to be a unsigned, 32-bit integer when OS_ALIGNMENT is 4 and an unsigned, 64-bit integer when OS_ALIGNMENT is 8. +The number of `os_membuf_t` elements used by the memory pool. Note that `os_membuf_t` is defined to be a unsigned, 32-bit integer when `OS_ALIGNMENT` is 4 and an unsigned, 64-bit integer when `OS_ALIGNMENT` is 8. <br> #### Notes -OS_MEMPOOL_SIZE is a macro and not a function. +`OS_MEMPOOL_SIZE` is a macro and not a function. <br> #### Example -Here we define a memory buffer to be used by a memory pool using OS_MEMPOOL_SIZE +Here we define a memory buffer to be used by a memory pool using `OS_MEMPOOL_SIZE` ```c #define NUM_BLOCKS (16) http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/aac53ed0/docs/os/core_os/memory_pool/memory_pool.md ---------------------------------------------------------------------- diff --git a/docs/os/core_os/memory_pool/memory_pool.md b/docs/os/core_os/memory_pool/memory_pool.md index 7009920..0a9cc77 100644 --- a/docs/os/core_os/memory_pool/memory_pool.md +++ b/docs/os/core_os/memory_pool/memory_pool.md @@ -16,7 +16,7 @@ The next order of business is to allocate the memory used by the memory pool. Th In order to simplify this for the user two macros have been provided: `OS_MEMPOOL_BYTES(n, blksize)` and `OS_MEMPOOL_SIZE(n, blksize)`. The first macro returns the number of bytes needed for the memory pool while the second returns the number of `os_membuf_t` elements required by the memory pool. The `os_membuf_t` type is used to guarantee that the memory buffer used by the memory pool is aligned on the correct boundary. -Here are some examples. Note that if a custom malloc implementation is used it must guarantee that the memory buffer used by the pool is allocated on the correct boundary (i.e. OS_ALIGNMENT). +Here are some examples. Note that if a custom malloc implementation is used it must guarantee that the memory buffer used by the pool is allocated on the correct boundary (i.e. `OS_ALIGNMENT`). ```c void *my_memory_buffer; http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/aac53ed0/docs/os/core_os/memory_pool/os_memblock_get.md ---------------------------------------------------------------------- diff --git a/docs/os/core_os/memory_pool/os_memblock_get.md b/docs/os/core_os/memory_pool/os_memblock_get.md index e341d4f..bdb8435 100644 --- a/docs/os/core_os/memory_pool/os_memblock_get.md +++ b/docs/os/core_os/memory_pool/os_memblock_get.md @@ -4,18 +4,18 @@ void *os_memblock_get(struct os_mempool *mp) ``` -Allocate an element from the memory pool. If successful, you'll get a pointer to allocated element. If there are no elements available, you'll get NULL as response. +Allocate an element from the memory pool. If successful, you'll get a pointer to allocated element. If there are no elements available, you'll get **NULL** as response. #### Arguments | Arguments | Description | |-----------|-------------| -| mp | Pool where element is getting allocated from | +| `mp` | Pool where element is getting allocated from | #### Returned values -NULL: no elements available. +**NULL**: no elements available. <pointer>: pointer to allocated element. #### Notes
