http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/8e70b507/develop/mkdocs/search_index.json ---------------------------------------------------------------------- diff --git a/develop/mkdocs/search_index.json b/develop/mkdocs/search_index.json index 240c0f7..779e2f4 100644 --- a/develop/mkdocs/search_index.json +++ b/develop/mkdocs/search_index.json @@ -1942,7 +1942,7 @@ }, { "location": "/os/core_os/mynewt_os/", - "text": "Mynewt Core OS\n\n\nThe 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.\n\n\nA 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.\n\n\nWhy use an OS?\n\n\nYou may ask yourself \"why do I need a multitasking preemptive OS\"? The answ er may indeed be that you do not. Some applications are simple and only require a polling loop. Others are more complex and may require that certain jobs are executed in a timely manner or before other jobs are executed. If you have a simple polling loop, you cannot move on to service a job until the current job is done being serviced. With the Mynewt OS, the application developer need not worry about certain jobs taking too long or not executing in a timely fashion; the OS provides mechanisms to deal with these situations. Another benefit of using an OS is that it helps shield application developers from other application code being written; the developer does not have to worry (or has to worry less) about other application code behaving badly and causing undesirable behavior or preventing their code from executing properly. Other benefits of using an OS (and the Mynewt OS in particular) is that it also provides features that the developer would otherwise need to create on his/her own. \n\n\nCore OS Features\n\n\n\n\n\n\nScheduler/context switching\n\n\nTime\n\n\nTasks\n\n\nEvent queues/callouts\n\n\nSemaphores\n\n\nMutexes\n\n\nMemory pools\n\n\nHeap\n\n\nMbufs\n\n\nSanity\n\n\nCallouts\n\n\nPorting OS to other platforms\n\n\n\n\nBasic OS Application Creation\n\n\nCreating an application using the Mynewt Core OS is a relatively simple task: once you have installed the basic Newt Tool structure (build structure) for your application and created your BSP (Board Support Package), the developer initializes the OS by calling \nos_init()\n, performs application specific initializations, and then starts the os by calling \nos_start()\n. \n\n\nThe \nos_init()\n API performs two basic functions: calls architecture and bsp specific setup and initializes the idle task of the OS. This is required before the OS is started. The OS start API initializes the OS time tick interrupt and starts the highest priority task running (i.e starts the scheduler). Note that \nos_start( )\n never returns; once called the device is either running in an application task context or in idle task context.\n\n\nInitializing application modules and tasks can get somewhat complicated with RTOS's similar to Mynewt. Care must be taken that the API provided by a task are initialized prior to being called by another (higher priority) task. \n\n\nFor example, take a simple application with two tasks (tasks 1 and 2, with task 1 higher priority than task 2). Task 2 provides an API which has a semaphore lock and this semaphore is initialized by task 2 when the task handler for task 2 is called. Task 1 is expected to call this API.\n\n\nConsider the sequence of events when the OS is started. The scheduler starts running and picks the highest priority task (task 1 in this case). The task handler function for task 1 is called and will keep running until it yields execution. Before yielding, code in the task 1 handler function calls the API provided by task 2. The semaphore being acce ssed in the task 2 API has yet to be initialized since the task 2 handler function has not had a chance to run! This will lead to undesirable behavior and will need to be addressed by the application developer. Note that the Mynewt OS does guard against internal API being called before the OS has started (they will return error) but it does not safeguard application defined objects from access prior to initialization.\n\n\nExample\n\n\nOne 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 \nos_task_init()\n). \n\n\nIn 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 \nos_sem_init()\n for task2_sem inside \ntask2_handler()\n, task 1 would have called \nos_sem_pend()\n using task2_sem before task2_sem was initialized.\n\n\n \n/* Task 1 handler function */\n\n \nvoid\n\n \ntask1_handler\n(\nvoid\n \n*arg\n)\n {\n \nwhile\n (\n1\n) {\n \n/* Release semaphore to task 2 */\n\n \nos_sem_release\n(\ntask1_sem\n);\n\n \n/* Wait for semaphore from task 2 */\n\n \nos_sem_pend\n(\ntask2_sem\n, \nOS_TIMEOUT_NEVER\n);\n }\n }\n\n \n/* Task 2 handler function */\ n\n \nvoid\n\n \ntask2_handler\n(\nvoid\n \n*arg\n)\n {\n \nstruct\n \nos_task\n \n*t\n;\n\n \nwhile\n (\n1\n) {\n \n/* Wait for semaphore from task1 */\n\n \nos_sem_pend\n(\ntask1_sem\n, \nOS_TIMEOUT_NEVER\n);\n\n \n/* Release task2 semaphore */\n\n \nos_sem_release\n(\ntask2_sem\n);\n }\n }\n\n\n \n/* Initialize task 1 exposed data objects */\n\n \nvoid\n\n \ntask1_init\n(\nvoid\n)\n {\n \n/* Initialize task1 semaphore */\n\n \nos_sem_init\n(\ntask1_sem\n, \n0\n);\n }\n\n \n/* Initialize task 2 exposed data objects */\n\n \nvoid\n\n \ntask2_init\n(\nvoid\n)\n {\n \n/* Initialize task1 semaphore */\n\n \nos_sem_init\n(\ntask2_sem\n, \n0\n);\n }\n\n \n/**\n\n\n * init_app_tasks\n\n\n * \n\n\n * Called by main.c after os_init(). This function performs initializations \n\n\n * that are required before tasks are running. \n\n\n * \n\n\n * @return int 0 success; error otherwise.\n\n\n */\n\n \nstatic\n \nint\n\n \ninit_app_tasks\n(\nvoid\n)\n {\n \n/*\n\n\n * Initialize tasks 1 and 2. Note that the task handlers are not called yet; they will\n\n\n * be called when the OS is started.\n\n\n */\n\n \nos_task_init\n(\ntask1\n, \ntask1\n, \ntask1_handler\n, \nNULL\n, \nTASK1_PRIO\n, \n \nOS_WAIT_FOREVER\n, \ntask1_stack\n, \nTASK1_STACK_SIZE\n);\n\n \nos_task_init\n(\ntask2\n, \ntask2\n, \ntask2_handler\n, \nNULL\n, \nTASK2_PRIO\n, \n \nOS_WAIT_FOREVER\n, \ntask2_stack\n, \nTASK2_STACK_SIZE\n);\n\n \n/* Call task specific initialization functions. */\n\n \ntask1_init\n();\n \ntask2_init\n();\n\n \nreturn\n \n0\n;\n }\n\n \n/**\n\n\n * main\n\n\n * \n\n\n * The main function for the application. This function initializes the os, calls \n\n\n * the application spe cific task initialization function. then starts the \n\n\n * OS. We should not return from os start! \n\n\n */\n\n \nint\n\n \nmain\n(\nvoid\n)\n {\n \nint\n \ni\n;\n \nint\n \nrc\n;\n \nuint32_t\n \nseed\n;\n\n \n/* Initialize OS */\n\n \nos_init\n();\n\n \n/* Initialize application specific tasks */\n\n \ninit_app_tasks\n();\n\n \n/* Start the OS */\n\n \nos_start\n();\n\n \n/* os start should never return. If it does, this should be an error */\n\n \nassert\n(\n0\n);\n\n \nreturn\n \nrc\n;\n }\n\n\n\n\n\nOS Functions\n\n\nThe functions available at the OS level are:\n\n\n\n\nos_init\n\n\nos_start\n\n\nos_started", + "text": "Mynewt Core OS\n\n\nThe 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.\n\n\nA 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.\n\n\nWhy use an OS?\n\n\nYou may ask yourself \"why do I need a multitasking preemptive OS\"? The answ er may indeed be that you do not. Some applications are simple and only require a polling loop. Others are more complex and may require that certain jobs are executed in a timely manner or before other jobs are executed. If you have a simple polling loop, you cannot move on to service a job until the current job is done being serviced. With the Mynewt OS, the application developer need not worry about certain jobs taking too long or not executing in a timely fashion; the OS provides mechanisms to deal with these situations. Another benefit of using an OS is that it helps shield application developers from other application code being written; the developer does not have to worry (or has to worry less) about other application code behaving badly and causing undesirable behavior or preventing their code from executing properly. Other benefits of using an OS (and the Mynewt OS in particular) is that it also provides features that the developer would otherwise need to create on his/her own. \n\n\nCore OS Features\n\n\n\n\n\n\nScheduler/context switching\n\n\nTime\n\n\nTasks\n\n\nEvent queues/callouts\n\n\nSemaphores\n\n\nMutexes\n\n\nMemory pools\n\n\nHeap\n\n\nMbufs\n\n\nSanity\n\n\nCallouts\n\n\nPorting OS to other platforms\n\n\n\n\nBasic OS Application Creation\n\n\nCreating an application using the Mynewt Core OS is a relatively simple task. The main steps are:\n\n\n\n\nInstall the basic Newt Tool structure (build structure) for your application.\n\n\nCreate your BSP (Board Support Package).\n\n\nIn your application \nmain()\n function, call the \nsysinit()\n function to initialize \nthe system and packages, perform application specific initialization, then\nwait and dispatch events from the OS default event \nqueue in an infinite loop. (See \nSystem Configuration and Initialization\n for more details.) \n\n\n\n\nInitializing application modules and tasks can get somewhat complicated with RTOS's similar to Mynewt. Care must be taken that the API provided by a task are initialized prior to being called by another (higher priority) task. \n\n\nFor example, take a simple application with two tasks (tasks 1 and 2, with task 1 higher priority than task 2). Task 2 provides an API which has a semaphore lock and this semaphore is initialized by task 2 when the task handler for task 2 is called. Task 1 is expected to call this API.\n\n\nConsider the sequence of events when the OS is started. The scheduler starts running and picks the highest priority task (task 1 in this case). The task handler function for task 1 is called and will keep running until it yields execution. Before yielding, code in the task 1 handler function calls the API provided by task 2. The semaphore being accessed in the task 2 API has yet to be initialized since the task 2 handler function has not had a chance to run! This will lead to undesirable behavior and will need to be addressed by the application developer. Note that the Mynewt OS does guard against internal API be ing called before the OS has started (they will return error) but it does not safeguard application defined objects from access prior to initialization.\n\n\nExample\n\n\nOne way to avoid initialization issues like the one described above is for the application to \ninitialize the objects that are accessed by multiple tasks before it initializes the tasks with the OS.\n\n\nThe code example shown below illustrates this concept. The application initializes system and packages, calls an application specific \"task initialization\" function, and dispatches events from the default event queue. 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 \nos_task_init()\n). \n\n\nIn 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 \nos_sem_init()\n for task2_sem inside \ntask2_handler()\n, task 1 would have called \nos_sem_pend()\n using task2_sem before task2_sem was initialized.\n\n\n \nstruct\n \nos_sem\n \ntask1_sem\n;\n \nstruct\n \nos_sem\n \ntask2_sem\n;\n\n \n/* Task 1 handler function */\n\n \nvoid\n\n \ntask1_handler\n(\nvoid\n \n*arg\n)\n {\n \nwhile\n (\n1\n) {\n \n/* Release semaphore to task 2 */\n\n \nos_sem_release\n(\ntask1_sem\n);\n\n \n/* Wait for semaphore from task 2 */\n\n \nos_sem_pend\n(\ntask2_sem\n, \nOS_TIMEOUT_NEVER\n);\n }\n }\n\n \n/* Task 2 handler function */\n\n \nvoid\n\n \ntask2_handler\n(\nvoid\n \n*arg\n)\n { \n \nstruct\n \nos_task\n \n*t\n;\n\n \nwhile\n (\n1\n) {\n \n/* Wait for semaphore from task1 */\n\n \nos_sem_pend\n(\ntask1_sem\n, \nOS_TIMEOUT_NEVER\n);\n\n \n/* Release task2 semaphore */\n\n \nos_sem_release\n(\ntask2_sem\n);\n }\n }\n\n\n \n/* Initialize task 1 exposed data objects */\n\n \nvoid\n\n \ntask1_init\n(\nvoid\n)\n {\n \n/* Initialize task1 semaphore */\n\n \nos_sem_init\n(\ntask1_sem\n, \n0\n);\n }\n\n \n/* Initialize task 2 exposed data objects */\n\n \nvoid\n\n \ntask2_init\n(\nvoid\n)\n {\n \n/* Initialize task1 semaphore */\n\n \nos_sem_init\n(\ntask2_sem\n, \n0\n);\n }\n\n \n/**\n\n\n * init_app_tasks\n\n\n * \n\n\n * This function performs initializations that are required before tasks run. \n\n\n * \n\n\n * @return int 0 success; error otherwise.\n\n\n */\n\n \nstatic\n \nint\n\n \ninit_app_tasks\n(\ nvoid\n)\n {\n \n/* \n\n\n * Call task specific initialization functions to initialize any shared objects \n\n\n * before initializing the tasks with the OS.\n\n\n */\n\n \ntask1_init\n();\n \ntask2_init\n();\n\n \n/*\n\n\n * Initialize tasks 1 and 2 with the OS. \n\n\n */\n\n \nos_task_init\n(\ntask1\n, \ntask1\n, \ntask1_handler\n, \nNULL\n, \nTASK1_PRIO\n, \n \nOS_WAIT_FOREVER\n, \ntask1_stack\n, \nTASK1_STACK_SIZE\n);\n\n \nos_task_init\n(\ntask2\n, \ntask2\n, \ntask2_handler\n, \nNULL\n, \nTASK2_PRIO\n, \n \nOS_WAIT_FOREVER\n, \ntask2_stack\n, \nTASK2_STACK_SIZE\n);\n\n \nreturn\n \n0\n;\n }\n\n \n/**\n\n\n * main\n\n\n * \n\n\n * The main function for the application. This function initializes the system and packages, \n\n\n * calls the application specific task initialization function, then waits and dispatches \n\n\n * events from the OS default event queue in an infinite loop. \n\n\n */\n\n \nint\n\n \nmain\n(\nint\n \nargc\n, \nchar\n \n**arg\n)\n {\n\n \n/* Perform system and package initialization */\n\n \nsysinit\n();\n\n \n/* Initialize application specific tasks */\n\n \ninit_app_tasks\n();\n\n \nwhile\n (\n1\n) {\n \nos_eventq_run\n(\nos_eventq_dflt_get\n());\n }\n \n/* main never returns */\n \n}\n\n\n\n\n\nOS Functions\n\n\nThe functions available at the OS level are:\n\n\n\n\nos_started", "title": "toc" }, { @@ -1962,70 +1962,20 @@ }, { "location": "/os/core_os/mynewt_os/#basic-os-application-creation", - "text": "Creating an application using the Mynewt Core OS is a relatively simple task: once you have installed the basic Newt Tool structure (build structure) for your application and created your BSP (Board Support Package), the developer initializes the OS by calling os_init() , performs application specific initializations, and then starts the os by calling os_start() . The os_init() API performs two basic functions: calls architecture and bsp specific setup and initializes the idle task of the OS. This is required before the OS is started. The OS start API initializes the OS time tick interrupt and starts the highest priority task running (i.e starts the scheduler). Note that os_start() never returns; once called the device is either running in an application task context or in idle task context. Initializing application modules and tasks can get somewhat complicated with RTOS's similar to Mynewt. Care must be taken that the API provided by a task are initia lized prior to being called by another (higher priority) task. For example, take a simple application with two tasks (tasks 1 and 2, with task 1 higher priority than task 2). Task 2 provides an API which has a semaphore lock and this semaphore is initialized by task 2 when the task handler for task 2 is called. Task 1 is expected to call this API. Consider the sequence of events when the OS is started. The scheduler starts running and picks the highest priority task (task 1 in this case). The task handler function for task 1 is called and will keep running until it yields execution. Before yielding, code in the task 1 handler function calls the API provided by task 2. The semaphore being accessed in the task 2 API has yet to be initialized since the task 2 handler function has not had a chance to run! This will lead to undesirable behavior and will need to be addressed by the application developer. Note that the Mynewt OS does guard against internal API being called before the OS has started (they will return error) but it does not safeguard application defined objects from access prior to initialization.", + "text": "Creating an application using the Mynewt Core OS is a relatively simple task. The main steps are: Install the basic Newt Tool structure (build structure) for your application. Create your BSP (Board Support Package). In your application main() function, call the sysinit() function to initialize \nthe system and packages, perform application specific initialization, then\nwait and dispatch events from the OS default event \nqueue in an infinite loop. (See System Configuration and Initialization for more details.) Initializing application modules and tasks can get somewhat complicated with RTOS's similar to Mynewt. Care must be taken that the API provided by a task are initialized prior to being called by another (higher priority) task. For example, take a simple application with two tasks (tasks 1 and 2, with task 1 higher priority than task 2). Task 2 provides an API which has a semaphore lock and this semaphore is initialized by task 2 when the t ask handler for task 2 is called. Task 1 is expected to call this API. Consider the sequence of events when the OS is started. The scheduler starts running and picks the highest priority task (task 1 in this case). The task handler function for task 1 is called and will keep running until it yields execution. Before yielding, code in the task 1 handler function calls the API provided by task 2. The semaphore being accessed in the task 2 API has yet to be initialized since the task 2 handler function has not had a chance to run! This will lead to undesirable behavior and will need to be addressed by the application developer. Note that the Mynewt OS does guard against internal API being called before the OS has started (they will return error) but it does not safeguard application defined objects from access prior to initialization.", "title": "Basic OS Application Creation" }, { "location": "/os/core_os/mynewt_os/#example", - "text": "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 ca lled 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. /* Task 1 handler function */ \n void \n task1_handler ( void *arg )\n {\n while ( 1 ) {\n /* Release semaphore to task 2 */ \n os_sem_release ( task1_sem );\n\n /* Wait for semaphore from task 2 */ \n os_sem_pend ( task2_sem , OS_TIMEOUT_NEVER );\n }\n }\n\n /* Task 2 handler function */ \n void \n task2_handler ( void *arg )\n {\n struct os_task *t ;\n\n while ( 1 ) {\n /* Wait for semaphore from task1 */ \n os_sem_pend ( task1_sem , OS_TIMEOUT_NEVER );\n\n /* Release task2 semaphore */ \n os_sem_release ( task2_sem );\n }\n }\n\n\n /* Initialize task 1 exposed data objects */ \n void \n task1_init ( void )\n {\n /* Initialize t ask1 semaphore */ \n os_sem_init ( task1_sem , 0 );\n }\n\n /* Initialize task 2 exposed data objects */ \n void \n task2_init ( void )\n {\n /* Initialize task1 semaphore */ \n os_sem_init ( task2_sem , 0 );\n }\n\n /** * init_app_tasks * * Called by main.c after os_init(). This function performs initializations * that are required before tasks are running. * * @return int 0 success; error otherwise. */ \n static int \n init_app_tasks ( void )\n {\n /* * Initialize tasks 1 and 2. Note that the task handlers are not called yet; they will * be called when the OS is started. */ \n os_task_init ( task1 , task1 , task1_handler , NULL , TASK1_PRIO , \n OS_WAIT_FOREVER , task1_stack , TASK1_STACK_SIZE );\n\n os_task_init ( task2 , task2 , task2_handler , NULL , TASK2_PRIO , \n OS_WAIT_FOREVER , task2_stack , TASK2_STACK_SIZE );\n\n /* Call task specific initialization functions. */ \n task1_init ();\n task2_init ();\n\n return 0 ;\n }\n\n /** * main * * The main function for the application. This function initializes the os, calls * the application specific task initialization function. then starts the * OS. We should not return from os start! */ \n int \n main ( void )\n {\n int i ;\n int rc ;\n uint32_t seed ;\n\n /* Initialize OS */ \n os_init ();\n\n /* Initialize application specific tasks */ \n init_app_tasks ();\n\n /* Start the OS */ \n os_start ();\n\n /* os start should never return. If it does, this should be an error */ \n assert ( 0 );\n\n return rc ;\n }", + "text": "One way to avoid initialization issues like the one described above is for the application to \ninitialize the objects that are accessed by multiple tasks before it initializes the tasks with the OS. The code example shown below illustrates this concept. The application initializes system and packages, calls an application specific \"task initialization\" function, and dispatches events from the default event queue. 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 initial ization 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. struct os_sem task1_sem ;\n struct os_sem task2_sem ;\n\n /* Task 1 handler function */ \n void \n task1_handler ( void *arg )\n {\n while ( 1 ) {\n /* Release semaphore to task 2 */ \n os_sem_release ( task1_sem );\n\n /* Wait for semaphore from task 2 */ \n os_sem_pend ( task2_sem , OS_TIMEOUT_NEVER );\n }\n }\n\n /* Task 2 handler function */ \n void \n task2_handler ( void *arg )\n {\n struct os_task *t ;\n\n while ( 1 ) {\n /* Wait for semaphore from task1 */ \n os_sem_pend ( task1_sem , OS_TIMEOUT_NEVER );\n\n /* Release task2 semaphore */ \n os_sem_release ( task2_sem );\n }\n }\n\n\n /* Initialize task 1 exposed data objects */ \n void \n task1_init ( void )\n {\n /* Initialize task1 semaphore */ \n os_sem_init ( task1_sem , 0 );\n }\n\n /* Initialize task 2 exposed data objects */ \n void \n task2_init ( void )\n {\n /* Initialize task1 semaphore */ \n os_sem_init ( task2_sem , 0 );\n }\n\n /** * init_app_tasks * * This function performs initializations that are required before tasks run. * * @return int 0 success; error otherwise. */ \n static int \n init_app_tasks ( void )\n {\n /* * Call task specific initialization functions to initialize any shared objects * before initializing the tasks with the OS. */ \n task1_init ();\n task2_init ();\n\n /* * Initialize tasks 1 and 2 with the OS. */ \n os_task_init ( task1 , task1 , task1_handler , NULL , TASK1_PRIO , \n OS_WAIT_FOREVER , task1_stack , TASK1_STACK_SIZE );\n\n os_task_init ( task2 , task2 , task2_handler , NULL , TASK2_PRIO , \n OS_WAIT_FOREVER , task2_stack , TASK2_STACK_SIZE );\n\n return 0 ;\n }\n\n /** * main * * The main function for the application. This function initializes the system and packages, * calls the application specific task initialization function, then waits and dispatches * events from the OS default event queue in an infinite loop. */ \n int \n main ( int argc , char **arg )\n {\n\n /* Perform system and package initialization */ \n sysinit ();\n\n /* Initialize application specific tasks */ \n init_app_tasks ();\n\n while ( 1 ) {\n os_eventq_run ( os_eventq_dflt_get ());\n }\n /* main never returns */ \n}", "title": "Example" }, { "location": "/os/core_os/mynewt_os/#os-functions", - "text": "The functions available at the OS level are: os_init os_start os_started", + "text": "The functions available at the OS level are: os_started", "title": "OS Functions" }, { - "location": "/os/core_os/os_init/", - "text": "os_init\n\n\nvoid\n \nos_init\n(\nvoid\n)\n\n\n\n\n\nInitializes the OS. Must be called before the OS is started (i.e. \nos_start()\n is called).\n\n\n\n\nArguments\n\n\nNone\n\n\n\n\nReturned values\n\n\nNone\n\n\n\n\nNotes\n\n\nThe call to \nos_init()\n performs architecture and bsp initializations and initializes the idle task.\n\n\nThis function does not start the OS, the OS time tick interrupt, or the scheduler.", - "title": "os_init" - }, - { - "location": "/os/core_os/os_init/#os_init", - "text": "void os_init ( void ) Initializes the OS. Must be called before the OS is started (i.e. os_start() is called).", - "title": "os_init" - }, - { - "location": "/os/core_os/os_init/#arguments", - "text": "None", - "title": "Arguments" - }, - { - "location": "/os/core_os/os_init/#returned-values", - "text": "None", - "title": "Returned values" - }, - { - "location": "/os/core_os/os_init/#notes", - "text": "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.", - "title": "Notes" - }, - { - "location": "/os/core_os/os_start/", - "text": "os_start\n\n\nvoid\n \nos_start\n(\nvoid\n)\n\n\n\n\n\nStarts the OS by initializing and enabling the OS time tick and starting the scheduler.\n\n\nThis function does not return.\n\n\n\n\nArguments\n\n\nNone\n\n\n\n\nReturned values\n\n\nNone (does not return).\n\n\n\n\nNotes\n\n\nOnce \nos_start()\n has been called, context is switched to the highest priority task that was initialized prior to calling \nos_start()\n.", - "title": "os_start" - }, - { - "location": "/os/core_os/os_start/#os_start", - "text": "void os_start ( void ) Starts the OS by initializing and enabling the OS time tick and starting the scheduler. This function does not return.", - "title": "os_start" - }, - { - "location": "/os/core_os/os_start/#arguments", - "text": "None", - "title": "Arguments" - }, - { - "location": "/os/core_os/os_start/#returned-values", - "text": "None (does not return).", - "title": "Returned values" - }, - { - "location": "/os/core_os/os_start/#notes", - "text": "Once os_start() has been called, context is switched to the highest priority task that was initialized prior to calling os_start() .", - "title": "Notes" - }, - { "location": "/os/core_os/os_started/", "text": "os_started\n\n\nint\n \nos_started\n(\nvoid\n)\n\n\n\n\n\nReturns 'true' (1) if the os has been started; 0 otherwise.\n\n\n\n\nArguments\n\n\nNone\n\n\n\n\nReturned values\n\n\nInteger value with 0 meaning the OS has not been started and 1 indicating the OS has been started (i.e. \nos_start()\n has been called).", "title": "os_started" @@ -2567,7 +2517,7 @@ }, { "location": "/os/core_os/task/task/", - "text": "Task\n\n\nA task, along with the scheduler, forms the basis of the Mynewt OS. A task \nconsists of two basic elements: a task stack and a task function. The task \nfunction is basically a forever loop, waiting for some \"event\" to wake it up. \nThere are two methods used to signal a task that it has work to do: \nevent queues\n \nand \nsemaphores\n .\n\n\nThe Mynewt OS is a multi-tasking, preemptive OS. Every task is assigned a task \npriority (from 0 to 255), with 0 being the highest priority task. If a higher \npriority task than the current task wants to run, the scheduler preempts the \ncurrently running task and switches context to the higher priority task. This is \njust a fancy way of saying that the processor stack pointer now points to the \nstack of the higher priority task and the task resumes execution where it left \noff.\n\n\nTasks run to completion unless they are preempted by a higher priority task. The \ndeveloper must ensure that tasks eventua lly \"sleep\"; otherwise lower priority \ntasks will never get a chance to run (actually, any task lower in priority than \nthe task that never sleeps). A task will be put to sleep in the following cases: \nit puts itself to sleep using \nos_time_delay()\n, it waits on an \nevent queue\n\nwhich is empty or attempts to obtain a mutex or a \nsemaphore\n that is currently \nowned by another task.\n\n\nNote that other sections of the manual describe these OS features in more \ndetail.\n\n\nDescription\n\n\nIn order to create a task two data structures need to be defined: the task \nobject (\nstruct os_task\n) and its associated stack. Determining the stack size can \nbe a bit tricky; generally developers should not declare large local variables \non the stack so that task stacks can be of limited size. However, all \napplications are different and the developer must choose the stack size \naccordingly. NOTE: be careful when declaring your stack! The stack is in units \nof \nos_stack_t\ n sized elements (generally 32-bits). Looking at the example given \nbelow and assuming \nos_stack_t\n is defined to be a 32-bit unsigned value, \n\"my_task_stack\" will use 256 bytes. \n\n\nA task must also have an associated \"task function\". This is the function that \nwill be called when the task is first run. This task function should never \nreturn!\n\n\nIn order to inform the Mynewt OS of the new task and to have it added to the \nscheduler, the \nos_task_init()\n function is called. Once \nos_task_init()\n is \ncalled, the task is made ready to run and is added to the active task list. Note \nthat a task can be initialized (started) before or after the os has started \n(i.e. before \nos_start()\n is called) but must be initialized after the os has \nbeen initialized (i.e. 'os_init()' has been called). In most of the examples and \ncurrent Mynewt projects, the os is initialized, tasks are initialized, and the \nthe os is started. Once the os has started, the highest priority task will be \nthe first task set to run.\n\n\nInformation about a task can be obtained using the \nos_task_info_get_next()\n \nAPI. Developers can walk the list of tasks to obtain information on all created \ntasks. This information is of type \nos_task_info\n and is described below.\n\n\nThe following is a very simple example showing a single application task. This \ntask simply toggles an LED at a one second interval.\n\n\n/* Create a simple \nproject\n with a task that blinks a LED every second */\n\n\n\n/* Define task stack and task object */\n\n\n#define MY_TASK_PRI (OS_TASK_PRI_HIGHEST) \n\n\n#define MY_STACK_SIZE (64) \n\n\nstruct\n \nos_task\n \nmy_task\n; \n\nos_stack_t\n \nmy_task_stack\n[\nMY_STACK_SIZE\n]; \n\n\n/* This is the task function */\n\n\nvoid\n \nmy_task_func\n(\nvoid\n \n*arg\n) {\n \n/* Set the led pin as an output */\n\n \nhal_gpio_init_out\n(\nLED_BLINK_PIN\n, \n1\n);\n\n \n/* The task is a forever loop that does not return */\n\n \nwhile\n (\n1\n) {\n \n/* Wait one second */\n \n \nos_time_delay\n(\n1000\n);\n\n \n/* Toggle the LED */\n \n \nhal_gpio_toggle\n(\nLED_BLINK_PIN\n);\n }\n}\n\n\n/* This is the main function for the project */\n\n\nint\n \nmain\n(\nvoid\n) {\n \nint\n \nrc\n;\n\n \n/* Initialize OS */\n\n \nos_init\n();\n\n \n/* Initialize the task */\n\n \nos_task_init\n(\nmy_task\n, \nmy_task\n, \nmy_task_func\n, \nNULL\n, \nMY_TASK_PRIO\n, \n \nOS_WAIT_FOREVER\n, \nmy_task_stack\n, \nMY_STACK_SIZE\n);\n\n \n/* Start the OS */\n\n \nos_start\n();\n\n \n/* os start should never return. If it does, this should be an error */\n\n \nassert\n(\n0\n);\n\n \nreturn\n \nrc\n;\n}\n\n\n\n\n\nData structures\n\n\n/* The highest and lowest task priorities */\n\n\n#define OS_TASK_PRI_HIGHEST (0)\n\n\n#define OS_TASK_PRI_LOWEST (0xff)\n\n\n\n/* Task states */\n\n\ntypedef\n \nenum\n \nos_task_state\n {\n \nOS_T ASK_READY\n \n=\n \n1\n, \n \nOS_TASK_SLEEP\n \n=\n \n2\n\n} \nos_task_state_t\n;\n\n\n/* Task flags */\n\n\n#define OS_TASK_FLAG_NO_TIMEOUT (0x0001U)\n\n\n#define OS_TASK_FLAG_SEM_WAIT (0x0002U)\n\n\n#define OS_TASK_FLAG_MUTEX_WAIT (0x0004U)\n\n\n\ntypedef\n \nvoid\n (\n*\nos_task_func_t\n)(\nvoid\n \n*\n);\n\n\n#define OS_TASK_MAX_NAME_LEN (32)\n\n\n\n\n\n\n\n\nstruct\n \nos_task\n {\n \nos_stack_t\n \n*t_stackptr\n;\n \nos_stack_t\n \n*t_stacktop\n;\n\n \nuint16_t\n \nt_stacksize\n;\n \nuint16_t\n \nt_flags\n;\n\n \nuint8_t\n \nt_taskid\n;\n \nuint8_t\n \nt_prio\n;\n \nuint8_t\n \nt_state\n;\n \nuint8_t\n \nt_pad\n;\n\n \nchar\n \n*t_name\n;\n \nos_task_func_t\n \nt_func\n;\n \nvoid\n \n*t_arg\n;\n\n \nvoid\n \n*t_obj\n;\n\n \nstruct\n \nos_sanity_check\n \nt_sanity_check\n; \n\n \nos_time_t\n \nt_next_wakeup\n;\n \nos_time_t\n \nt_run_time\n;\n \nuint32_t\n \nt_ctx_sw_cnt\n;\n\n \n/* Global list of all tasks, ir respective of run or sleep lists */\n\n \nSTAILQ_ENTRY\n(\nos_task\n) \nt_os_task_list\n;\n\n \n/* Used to chain task to either the run or sleep list */\n \n \nTAILQ_ENTRY\n(\nos_task\n) \nt_os_list\n;\n\n \n/* Used to chain task to an object such as a semaphore or mutex */\n\n \nSLIST_ENTRY\n(\nos_task\n) \nt_obj_list\n;\n};\n\n\n\n\n\n\n\n\n\n\n\nElement\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\nt_stackptr\n\n\nCurrent stack pointer\n\n\n\n\n\n\nt_stacktop\n\n\nThe address of the top of the task stack. The stack grows downward\n\n\n\n\n\n\nt_stacksize\n\n\nThe size of the stack, in units of os_stack_t (not bytes!)\n\n\n\n\n\n\nt_flags\n\n\nTask flags (see flag definitions)\n\n\n\n\n\n\nt_taskid\n\n\nA numeric id assigned to each task\n\n\n\n\n\n\nt_prio\n\n\nThe priority of the task. The lower the number, the higher the priority\n\n\n\n\n\n\nt_state\n\n\nThe task state (see state definitions)\n\n\n\n\n\n\nt_pad\n\n\npadding (for alignment)\n\n\n\n\n\n\nt_name\n\n\nName of task\n\n\n\n\n\n\nt_func\n\n\nPointer to task function\n\n\n\n\n\n\nt_obj\n\n\nGeneric object used by mutexes and semaphores when the task is waiting on a mutex or semaphore\n\n\n\n\n\n\nt_sanity_check\n\n\nSanity task data structure\n\n\n\n\n\n\nt_next_wakeup\n\n\nOS time when task is next scheduled to wake up\n\n\n\n\n\n\nt_run_time\n\n\nThe amount of os time ticks this task has been running\n\n\n\n\n\n\nt_ctx_sw_cnt\n\n\nThe number of times that this task has been run\n\n\n\n\n\n\nt_os_task_list\n\n\nList pointer for global task list. All tasks are placed on this list\n\n\n\n\n\n\nt_os_list\n\n\nList pointer used by either the active task list or the sleeping task list\n\n\n\n\n\n\nt_obj_list\n\n\nList pointer for tasks waiting on a semaphore or mutex\n\n\n\n\n\n\n\n\n\n\nstruct\n \nos_task_info\n {\n \nuint8_t\n \noti_prio\n;\n \nuint8_t\n \noti_taskid\n;\n \nuint8_t\n \noti_state\n;\n \nuint8_t\n \noti_flags\n;\n \nuint16_t\n \noti_stkusage\n;\n \nuint16_t\ n \noti_stksize\n;\n \nuint32_t\n \noti_cswcnt\n;\n \nuint32_t\n \noti_runtime\n;\n \nos_time_t\n \noti_last_checkin\n;\n \nos_time_t\n \noti_next_checkin\n;\n\n \nchar\n \noti_name\n[\nOS_TASK_MAX_NAME_LEN\n];\n};\n\n\n\n\n\n\n\n\n\n\n\nElement\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\noti_prio\n\n\nTask priority\n\n\n\n\n\n\noti_taskid\n\n\nTask id\n\n\n\n\n\n\noti_state\n\n\nTask state\n\n\n\n\n\n\noti_flags\n\n\nTask flags\n\n\n\n\n\n\noti_stkusage\n\n\nAmount of stack used by the task (in os_stack_t units)\n\n\n\n\n\n\noti_stksize\n\n\nThe size of the stack (in os_stack_t units)\n\n\n\n\n\n\noti_cswcnt\n\n\nThe context switch count\n\n\n\n\n\n\noti_runtime\n\n\nThe amount of time that the task has run (in os time ticks)\n\n\n\n\n\n\noti_last_checkin\n\n\nThe time (os time) at which this task last checked in to the sanity task\n\n\n\n\n\n\noti_next_checkin\n\n\nThe time (os time) at which this task last checked in to the sanity task\n\n\n\n\n\n\noti_name\n\n\nName of the task\n\n\n\n\n\n\n\n\n\n\nList of Functions\n\n\nThe functions available in task are:\n\n\n\n\n\n\n\n\nFunction\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\nos_task_init\n\n\nCalled to create a task. This adds the task object to the list of ready to run tasks.\n\n\n\n\n\n\nos_task_count\n\n\nReturns the number of tasks that have been created.\n\n\n\n\n\n\nos_task_info_get_next\n\n\nPopulates the os task info structure given with task information.", + "text": "Task\n\n\nA task, along with the scheduler, forms the basis of the Mynewt OS. A task \nconsists of two basic elements: a task stack and a task function. The task \nfunction is basically a forever loop, waiting for some \"event\" to wake it up. \nThere are two methods used to signal a task that it has work to do: \nevent queues\n \nand \nsemaphores\n .\n\n\nThe Mynewt OS is a multi-tasking, preemptive OS. Every task is assigned a task \npriority (from 0 to 255), with 0 being the highest priority task. If a higher \npriority task than the current task wants to run, the scheduler preempts the \ncurrently running task and switches context to the higher priority task. This is \njust a fancy way of saying that the processor stack pointer now points to the \nstack of the higher priority task and the task resumes execution where it left \noff.\n\n\nTasks run to completion unless they are preempted by a higher priority task. The \ndeveloper must ensure that tasks eventua lly \"sleep\"; otherwise lower priority \ntasks will never get a chance to run (actually, any task lower in priority than \nthe task that never sleeps). A task will be put to sleep in the following cases: \nit puts itself to sleep using \nos_time_delay()\n, it waits on an \nevent queue\n\nwhich is empty or attempts to obtain a mutex or a \nsemaphore\n that is currently \nowned by another task.\n\n\nNote that other sections of the manual describe these OS features in more \ndetail.\n\n\nDescription\n\n\nIn order to create a task two data structures need to be defined: the task \nobject (\nstruct os_task\n) and its associated stack. Determining the stack size can \nbe a bit tricky; generally developers should not declare large local variables \non the stack so that task stacks can be of limited size. However, all \napplications are different and the developer must choose the stack size \naccordingly. NOTE: be careful when declaring your stack! The stack is in units \nof \nos_stack_t\ n sized elements (generally 32-bits). Looking at the example given \nbelow and assuming \nos_stack_t\n is defined to be a 32-bit unsigned value, \n\"my_task_stack\" will use 256 bytes. \n\n\nA task must also have an associated \"task function\". This is the function that \nwill be called when the task is first run. This task function should never \nreturn!\n\n\nIn order to inform the Mynewt OS of the new task and to have it added to the \nscheduler, the \nos_task_init()\n function is called. Once \nos_task_init()\n is \ncalled, the task is made ready to run and is added to the active task list. Note \nthat a task can be initialized (started) before or after the os has started \n(i.e. before \nos_start()\n is called) but must be initialized after the os has \nbeen initialized (i.e. 'os_init()' has been called). In most of the examples and \ncurrent Mynewt projects, the os is initialized, tasks are initialized, and the \nthe os is started. Once the os has started, the highest priority task will be \nthe first task set to run.\n\n\nInformation about a task can be obtained using the \nos_task_info_get_next()\n \nAPI. Developers can walk the list of tasks to obtain information on all created \ntasks. This information is of type \nos_task_info\n and is described below.\n\n\nThe following is a very simple example showing a single application task. This \ntask simply toggles an LED at a one second interval.\n\n\n/* Create a simple \nproject\n with a task that blinks a LED every second */\n\n\n\n/* Define task stack and task object */\n\n\n#define MY_TASK_PRI (OS_TASK_PRI_HIGHEST) \n\n\n#define MY_STACK_SIZE (64) \n\n\nstruct\n \nos_task\n \nmy_task\n; \n\nos_stack_t\n \nmy_task_stack\n[\nMY_STACK_SIZE\n]; \n\n\n/* This is the task function */\n\n\nvoid\n \nmy_task_func\n(\nvoid\n \n*arg\n) {\n \n/* Set the led pin as an output */\n\n \nhal_gpio_init_out\n(\nLED_BLINK_PIN\n, \n1\n);\n\n \n/* The task is a forever loop that does not return */\n\n \nwhile\n (\n1\n) {\n \n/* Wait one second */\n \n \nos_time_delay\n(\n1000\n);\n\n \n/* Toggle the LED */\n \n \nhal_gpio_toggle\n(\nLED_BLINK_PIN\n);\n }\n}\n\n\n/* This is the main function for the project */\n\n\nint\n \nmain\n(\nint\n \nargc\n, \nchar\n \n**argv\n) \n{\n\n \n/* Perform system and package initialization */\n\n \nsysinit\n();\n\n \n/* Initialize the task */\n\n \nos_task_init\n(\nmy_task\n, \nmy_task\n, \nmy_task_func\n, \nNULL\n, \nMY_TASK_PRIO\n, \n \nOS_WAIT_FOREVER\n, \nmy_task_stack\n, \nMY_STACK_SIZE\n);\n\n \n/* Process events from the default event queue. */\n\n \nwhile\n (\n1\n) {\n \nos_eventq_run\n(\nos_eventq_dflt_get\n());\n }\n \n/* main never returns */\n \n}\n\n\n\n\n\nData structures\n\n\n/* The highest and lowest task priorities */\n\n\n#define OS_TASK_PRI_HIGHEST (0)\n\n\n#define OS_TASK_PRI_LOWEST (0xff)\n\n\n\n/* Task states */\n\n\ntypedef\n \ nenum\n \nos_task_state\n {\n \nOS_TASK_READY\n \n=\n \n1\n, \n \nOS_TASK_SLEEP\n \n=\n \n2\n\n} \nos_task_state_t\n;\n\n\n/* Task flags */\n\n\n#define OS_TASK_FLAG_NO_TIMEOUT (0x0001U)\n\n\n#define OS_TASK_FLAG_SEM_WAIT (0x0002U)\n\n\n#define OS_TASK_FLAG_MUTEX_WAIT (0x0004U)\n\n\n\ntypedef\n \nvoid\n (\n*\nos_task_func_t\n)(\nvoid\n \n*\n);\n\n\n#define OS_TASK_MAX_NAME_LEN (32)\n\n\n\n\n\n\n\n\nstruct\n \nos_task\n {\n \nos_stack_t\n \n*t_stackptr\n;\n \nos_stack_t\n \n*t_stacktop\n;\n\n \nuint16_t\n \nt_stacksize\n;\n \nuint16_t\n \nt_flags\n;\n\n \nuint8_t\n \nt_taskid\n;\n \nuint8_t\n \nt_prio\n;\n \nuint8_t\n \nt_state\n;\n \nuint8_t\n \nt_pad\n;\n\n \nchar\n \n*t_name\n;\n \nos_task_func_t\n \nt_func\n;\n \nvoid\n \n*t_arg\n;\n\n \nvoid\n \n*t_obj\n;\n\n \nstruct\n \nos_sanity_check\n \nt_sanity_check\n; \n\n \nos_time_t\n \nt_next_wakeup\n;\n \nos_time_t\n \nt_run_time\n;\n \nuint32_t\n \nt_ctx_sw_cnt\n;\n \n \n/* Global list of all tasks, irrespective of run or sleep lists */\n\n \nSTAILQ_ENTRY\n(\nos_task\n) \nt_os_task_list\n;\n\n \n/* Used to chain task to either the run or sleep list */\n \n \nTAILQ_ENTRY\n(\nos_task\n) \nt_os_list\n;\n\n \n/* Used to chain task to an object such as a semaphore or mutex */\n\n \nSLIST_ENTRY\n(\nos_task\n) \nt_obj_list\n;\n};\n\n\n\n\n\n\n\n\n\n\n\nElement\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\nt_stackptr\n\n\nCurrent stack pointer\n\n\n\n\n\n\nt_stacktop\n\n\nThe address of the top of the task stack. The stack grows downward\n\n\n\n\n\n\nt_stacksize\n\n\nThe size of the stack, in units of os_stack_t (not bytes!)\n\n\n\n\n\n\nt_flags\n\n\nTask flags (see flag definitions)\n\n\n\n\n\n\nt_taskid\n\n\nA numeric id assigned to each task\n\n\n\n\n\n\nt_prio\n\n\nThe priority of the task. The lower the number, the higher the priority\n\n\n\n\n\n\nt_state\n\n\nThe task state (see state definitions)\n\n\n\n\n\n\nt_pad\n\n\npadding (for al ignment)\n\n\n\n\n\n\nt_name\n\n\nName of task\n\n\n\n\n\n\nt_func\n\n\nPointer to task function\n\n\n\n\n\n\nt_obj\n\n\nGeneric object used by mutexes and semaphores when the task is waiting on a mutex or semaphore\n\n\n\n\n\n\nt_sanity_check\n\n\nSanity task data structure\n\n\n\n\n\n\nt_next_wakeup\n\n\nOS time when task is next scheduled to wake up\n\n\n\n\n\n\nt_run_time\n\n\nThe amount of os time ticks this task has been running\n\n\n\n\n\n\nt_ctx_sw_cnt\n\n\nThe number of times that this task has been run\n\n\n\n\n\n\nt_os_task_list\n\n\nList pointer for global task list. All tasks are placed on this list\n\n\n\n\n\n\nt_os_list\n\n\nList pointer used by either the active task list or the sleeping task list\n\n\n\n\n\n\nt_obj_list\n\n\nList pointer for tasks waiting on a semaphore or mutex\n\n\n\n\n\n\n\n\n\n\nstruct\n \nos_task_info\n {\n \nuint8_t\n \noti_prio\n;\n \nuint8_t\n \noti_taskid\n;\n \nuint8_t\n \noti_state\n;\n \nuint8_t\n \noti_flags\n;\n \nuint16 _t\n \noti_stkusage\n;\n \nuint16_t\n \noti_stksize\n;\n \nuint32_t\n \noti_cswcnt\n;\n \nuint32_t\n \noti_runtime\n;\n \nos_time_t\n \noti_last_checkin\n;\n \nos_time_t\n \noti_next_checkin\n;\n\n \nchar\n \noti_name\n[\nOS_TASK_MAX_NAME_LEN\n];\n};\n\n\n\n\n\n\n\n\n\n\n\nElement\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\noti_prio\n\n\nTask priority\n\n\n\n\n\n\noti_taskid\n\n\nTask id\n\n\n\n\n\n\noti_state\n\n\nTask state\n\n\n\n\n\n\noti_flags\n\n\nTask flags\n\n\n\n\n\n\noti_stkusage\n\n\nAmount of stack used by the task (in os_stack_t units)\n\n\n\n\n\n\noti_stksize\n\n\nThe size of the stack (in os_stack_t units)\n\n\n\n\n\n\noti_cswcnt\n\n\nThe context switch count\n\n\n\n\n\n\noti_runtime\n\n\nThe amount of time that the task has run (in os time ticks)\n\n\n\n\n\n\noti_last_checkin\n\n\nThe time (os time) at which this task last checked in to the sanity task\n\n\n\n\n\n\noti_next_checkin\n\n\nThe time (os time) at which this task last checked in to the sanity t ask\n\n\n\n\n\n\noti_name\n\n\nName of the task\n\n\n\n\n\n\n\n\n\n\nList of Functions\n\n\nThe functions available in task are:\n\n\n\n\n\n\n\n\nFunction\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\nos_task_init\n\n\nCalled to create a task. This adds the task object to the list of ready to run tasks.\n\n\n\n\n\n\nos_task_count\n\n\nReturns the number of tasks that have been created.\n\n\n\n\n\n\nos_task_info_get_next\n\n\nPopulates the os task info structure given with task information.", "title": "toc" }, { @@ -2577,7 +2527,7 @@ }, { "location": "/os/core_os/task/task/#description", - "text": "In order to create a task two data structures need to be defined: the task \nobject ( struct os_task ) and its associated stack. Determining the stack size can \nbe a bit tricky; generally developers should not declare large local variables \non the stack so that task stacks can be of limited size. However, all \napplications are different and the developer must choose the stack size \naccordingly. NOTE: be careful when declaring your stack! The stack is in units \nof os_stack_t sized elements (generally 32-bits). Looking at the example given \nbelow and assuming os_stack_t is defined to be a 32-bit unsigned value, \n\"my_task_stack\" will use 256 bytes. A task must also have an associated \"task function\". This is the function that \nwill be called when the task is first run. This task function should never \nreturn! In order to inform the Mynewt OS of the new task and to have it added to the \nscheduler, the os_task_init() function is called. Once o s_task_init() is \ncalled, the task is made ready to run and is added to the active task list. Note \nthat a task can be initialized (started) before or after the os has started \n(i.e. before os_start() is called) but must be initialized after the os has \nbeen initialized (i.e. 'os_init()' has been called). In most of the examples and \ncurrent Mynewt projects, the os is initialized, tasks are initialized, and the \nthe os is started. Once the os has started, the highest priority task will be \nthe first task set to run. Information about a task can be obtained using the os_task_info_get_next() \nAPI. Developers can walk the list of tasks to obtain information on all created \ntasks. This information is of type os_task_info and is described below. The following is a very simple example showing a single application task. This \ntask simply toggles an LED at a one second interval. /* Create a simple project with a task that blinks a LED every second */ /* Define task st ack and task object */ #define MY_TASK_PRI (OS_TASK_PRI_HIGHEST) #define MY_STACK_SIZE (64) struct os_task my_task ; os_stack_t my_task_stack [ MY_STACK_SIZE ]; /* This is the task function */ void my_task_func ( void *arg ) {\n /* Set the led pin as an output */ \n hal_gpio_init_out ( LED_BLINK_PIN , 1 );\n\n /* The task is a forever loop that does not return */ \n while ( 1 ) {\n /* Wait one second */ \n os_time_delay ( 1000 );\n\n /* Toggle the LED */ \n hal_gpio_toggle ( LED_BLINK_PIN );\n }\n} /* This is the main function for the project */ int main ( void ) {\n int rc ;\n\n /* Initialize OS */ \n os_init ();\n\n /* Initialize the task */ \n os_task_init ( my_task , my_task , my_task_func , NULL , MY_TASK_PRIO , \n OS_WAIT_FOREVER , my_task_stack , MY_STACK_SIZE );\n\n /* Start the OS */ \n os_start ();\n\n /* os start should never r eturn. If it does, this should be an error */ \n assert ( 0 );\n\n return rc ;\n}", + "text": "In order to create a task two data structures need to be defined: the task \nobject ( struct os_task ) and its associated stack. Determining the stack size can \nbe a bit tricky; generally developers should not declare large local variables \non the stack so that task stacks can be of limited size. However, all \napplications are different and the developer must choose the stack size \naccordingly. NOTE: be careful when declaring your stack! The stack is in units \nof os_stack_t sized elements (generally 32-bits). Looking at the example given \nbelow and assuming os_stack_t is defined to be a 32-bit unsigned value, \n\"my_task_stack\" will use 256 bytes. A task must also have an associated \"task function\". This is the function that \nwill be called when the task is first run. This task function should never \nreturn! In order to inform the Mynewt OS of the new task and to have it added to the \nscheduler, the os_task_init() function is called. Once o s_task_init() is \ncalled, the task is made ready to run and is added to the active task list. Note \nthat a task can be initialized (started) before or after the os has started \n(i.e. before os_start() is called) but must be initialized after the os has \nbeen initialized (i.e. 'os_init()' has been called). In most of the examples and \ncurrent Mynewt projects, the os is initialized, tasks are initialized, and the \nthe os is started. Once the os has started, the highest priority task will be \nthe first task set to run. Information about a task can be obtained using the os_task_info_get_next() \nAPI. Developers can walk the list of tasks to obtain information on all created \ntasks. This information is of type os_task_info and is described below. The following is a very simple example showing a single application task. This \ntask simply toggles an LED at a one second interval. /* Create a simple project with a task that blinks a LED every second */ /* Define task st ack and task object */ #define MY_TASK_PRI (OS_TASK_PRI_HIGHEST) #define MY_STACK_SIZE (64) struct os_task my_task ; os_stack_t my_task_stack [ MY_STACK_SIZE ]; /* This is the task function */ void my_task_func ( void *arg ) {\n /* Set the led pin as an output */ \n hal_gpio_init_out ( LED_BLINK_PIN , 1 );\n\n /* The task is a forever loop that does not return */ \n while ( 1 ) {\n /* Wait one second */ \n os_time_delay ( 1000 );\n\n /* Toggle the LED */ \n hal_gpio_toggle ( LED_BLINK_PIN );\n }\n} /* This is the main function for the project */ int main ( int argc , char **argv ) \n{\n\n /* Perform system and package initialization */ \n sysinit ();\n\n /* Initialize the task */ \n os_task_init ( my_task , my_task , my_task_func , NULL , MY_TASK_PRIO , \n OS_WAIT_FOREVER , my_task_stack , MY_STACK_SIZE );\n\n /* Process events from the default e vent queue. */ \n while ( 1 ) {\n os_eventq_run ( os_eventq_dflt_get ());\n }\n /* main never returns */ \n}", "title": "Description" }, { @@ -4752,17 +4702,17 @@ }, { "location": "/os/modules/console/console/", - "text": "Console\n\n\nThe console is an operating system window where users interact with system programs of the operating system \nor a console application by entering text input (typically from a keyboard) and reading text output \n(typically on the computer terminal or monitor). The text written on the console brings some information \nand is a sequence of characters sent by the OS or programs running on the OS. \n\n\nSupport is currently available for console access via the serial port on the hardware board.\n\n\nDescription\n\n\nIn the Mynewt OS, the console library comes in two versions:\n\n\n\n\nfull - containing the full implementation\n\n\nstub - containing stubs for the API\n\n\n\n\nBoth of these have a \npkg.yml\n file which states that they provide the \nconsole\n API. If a pkg uses \nthis API, it should list \nconsole\n as a requirement. For example, the shell pkg is defined by the \nfollowing pkg.yml file:\n\n\n pkg.name: libs/shell \n pkg.vers: 0.1\n pkg.deps:\n - libs/os\n - libs/util\n pkg.reqs:\n - console\n pkg.identities:\n - SHELL \n\n\n\n\n\nThe project .yml file decides which version of the console pkg should be included. \nIf a project requires the full console capability it lists dependency \nlibs/console/full\n in its pkg.yml \nfile. On the other hand, a project may not have a physical console (e.g. a UART port to connect a terminal to) \nbut may have a dependency on a pkg that has console capability. In that case you would use a console stub. \n\n\nAnother example would be the bootloader project where we want to keep the size of the image small. It includes \nthe \nlibs/os\n pkg that can print out messages on a console (e.g. if there is a hard fault) and the \nlibs/util\n \npkg that uses the full console (but only if SHELL is present to provide a CLI). However, we do not want to use \nany console I/O capability in this particular bootloader project to keep the size small. We simp ly use the console \nstub instead, and the pkg.yml file for the project boot pkg looks like the following:\n\n\n project.name: boot\n project.identities: bootloader\n project.pkgs:\n - libs/os\n - libs/bootutil\n - libs/nffs\n - libs/console/stub\n - libs/util \n\n\n\n\n\nConsole has 2 modes for transmit; \nblocking mode\n and \nnon-blocking mode\n. Usually the \nnon-blocking mode\n is the \nactive one; the output buffer is drained by getting TX completion interrupts from hardware, and more data is added \nbased on these interrupts.\n\n\nBlocking mode\n is used when we don't want TX completion interrupts. It is used when system crashes, and we still \nwant to output info related to that crash.\n\n\nConsole, by default, echoes everything it receives back. Terminal programs expect this, and is a way for the user to \nknow that the console is connected and responsive. Whether echoing happens or not can be controlled programmatically.\n\n\nThe Console also has a prompt that is configurable. It is off by default but can be turned on programatically. The\nprompt cahracter can also be changed by the user.\n\n\nData structures\n\n\nN/A\n\n\nList of Functions\n\n\nThe functions available in console are:\n\n\n\n\n\n\n\n\nFunction\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\nconsole_blocking_mode\n\n\nCalls the \nconsole_blocking_tx\n function to flush the buffered console output (transmit) queue.\n\n\n\n\n\n\nconsole_echo\n\n\nControls whether echoing is on or off for the console.\n\n\n\n\n\n\nconsole_init\n\n\nInitialize the console.\n\n\n\n\n\n\nconsole_is_init\n\n\nReturns whether console has been initialized or not.\n\n\n\n\n\n\nconsole_printf\n\n\nWrites a formatted message instead of raw output to the console.\n\n\n\n\n\n\nconsole_read\n\n\nCopies up the to given number of bytes to the input string.\n\n\n\n\n\n\nconsole_write\n\n\nQueues characters to console display over serial port.", + "text": "Console\n\n\nThe console is an operating system window where users interact with the OS subsystems or a console \napplication. A user typically inputs text from a keyboard and reads the OS output text on a computer\nmonitor. The text are sent as a sequence of characters between the user and the OS. \n\n\nSupport is currently available for console access via the serial port on the hardware board.\n\n\nDescription\n\n\nIn the Mynewt OS, the console library comes in two versions:\n\n\n\n\n\n\nThe \nsys/console/full\n package implements the complete console functionality and API.\n\n\n\n\n\n\nThe \nsys/console/stub\n package implements stubs for the API.\n\n\n\n\n\n\nBoth packages export the \nconsole\n API, and any package that uses \nthe console API must list \nconsole\n as a requirement. For example, the shell package defines the following \npkg.yml\n\nfile:\n\n\npkg.name: sys/shell\npkg.deps:\n - kernel/os\n - encoding/base64\n - time/datetime\n - util/crc\npkg.req_apis:\n - console\n\n\n\n\n\nThe project \npkg.yml\n file specifies the version of the console package to use.\nA project that requires the full console capability must list the \nsys/console/full\n package as a dependency \nin its \npkg.yml\n file.\n\n\nAn example is the \nslinky\n application. It requires the full console capability and has the following\n\npkg.yml\n file: \n\n\npkg.name: apps/slinky\npkg.deps:\n - test/flash_test\n - mgmt/imgmgr\n - mgmt/newtmgr\n - mgmt/newtmgr/transport/nmgr_shell\n - kernel/os\n - boot/bootutil\n - sys/shell\n - sys/console/full\n ...\n - sys/id\n\n\n\n\n\nOn the other hand, a project may not have a physical console (e.g. a UART port to connect a terminal to) \nbut may have a dependency on a package that has console capability. In this case, you use \nthe console stub API and list the \nsys/console/stub\n package as a dependency in its \npkg.yml\n file. \n\n\nAn example is the bootloader pr oject where we want to keep the size of the image small. It includes \nthe \nkernel/os\n package that can print out messages on a console (e.g. if there is a hard fault).\nHowever, we do not want to use any console I/O capability in this particular bootloader project to \nkeep the size small. The project uses the console stub API and has the following \npkg.yml\n file: \n\n\npkg.name: apps/boot\npkg.deps:\n - boot/bootutil\n - kernel/os\n - sys/console/stub\n\n\n\n\n\nConsole has 2 modes for transmit; \nblocking mode\n and \nnon-blocking mode\n. Usually the \nnon-blocking mode\n is the \nactive one; the output buffer is drained by getting TX completion interrupts from hardware, and more data is added \nbased on these interrupts.\n\n\nBlocking mode\n is used when we don't want TX completion interrupts. It is used when system crashes, and we still \nwant to output info related to that crash.\n\n\nConsole, by default, echoes everything it receives back. Terminal programs expec t this, and is a way for the user to \nknow that the console is connected and responsive. Whether echoing happens or not can be controlled programmatically.\n\n\nThe Console also has a prompt that is configurable. It is off by default but can be turned on programmatically. The\nprompt character can also be changed by the user.\n\n\nData structures\n\n\nN/A\n\n\nList of Functions\n\n\nThe functions available in console are:\n\n\n\n\n\n\n\n\nFunction\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\nconsole_blocking_mode\n\n\nCalls the \nconsole_blocking_tx\n function to flush the buffered console output (transmit) queue.\n\n\n\n\n\n\nconsole_echo\n\n\nControls whether echoing is on or off for the console.\n\n\n\n\n\n\nconsole_init\n\n\nInitialize the console.\n\n\n\n\n\n\nconsole_is_init\n\n\nReturns whether console has been initialized or not.\n\n\n\n\n\n\nconsole_printf\n\n\nWrites a formatted message instead of raw output to the console.\n\n\n\n\n\n\nconsole_read\n\n\nCopies up the to given n umber of bytes to the input string.\n\n\n\n\n\n\nconsole_write\n\n\nQueues characters to console display over serial port.", "title": "toc" }, { "location": "/os/modules/console/console/#console", - "text": "The console is an operating system window where users interact with system programs of the operating system \nor a console application by entering text input (typically from a keyboard) and reading text output \n(typically on the computer terminal or monitor). The text written on the console brings some information \nand is a sequence of characters sent by the OS or programs running on the OS. Support is currently available for console access via the serial port on the hardware board.", + "text": "The console is an operating system window where users interact with the OS subsystems or a console \napplication. A user typically inputs text from a keyboard and reads the OS output text on a computer\nmonitor. The text are sent as a sequence of characters between the user and the OS. Support is currently available for console access via the serial port on the hardware board.", "title": "Console" }, { "location": "/os/modules/console/console/#description", - "text": "In the Mynewt OS, the console library comes in two versions: full - containing the full implementation stub - containing stubs for the API Both of these have a pkg.yml file which states that they provide the console API. If a pkg uses \nthis API, it should list console as a requirement. For example, the shell pkg is defined by the \nfollowing pkg.yml file: pkg.name: libs/shell \n pkg.vers: 0.1\n pkg.deps:\n - libs/os\n - libs/util\n pkg.reqs:\n - console\n pkg.identities:\n - SHELL The project .yml file decides which version of the console pkg should be included. \nIf a project requires the full console capability it lists dependency libs/console/full in its pkg.yml \nfile. On the other hand, a project may not have a physical console (e.g. a UART port to connect a terminal to) \nbut may have a dependency on a pkg that has console capability. In that case you would use a console stub. Another example w ould be the bootloader project where we want to keep the size of the image small. It includes \nthe libs/os pkg that can print out messages on a console (e.g. if there is a hard fault) and the libs/util \npkg that uses the full console (but only if SHELL is present to provide a CLI). However, we do not want to use \nany console I/O capability in this particular bootloader project to keep the size small. We simply use the console \nstub instead, and the pkg.yml file for the project boot pkg looks like the following: project.name: boot\n project.identities: bootloader\n project.pkgs:\n - libs/os\n - libs/bootutil\n - libs/nffs\n - libs/console/stub\n - libs/util Console has 2 modes for transmit; blocking mode and non-blocking mode . Usually the non-blocking mode is the \nactive one; the output buffer is drained by getting TX completion interrupts from hardware, and more data is added \nbased on these interrupts. Blocking mode is used when we don't want TX completion interrupts. It is used when system crashes, and we still \nwant to output info related to that crash. Console, by default, echoes everything it receives back. Terminal programs expect this, and is a way for the user to \nknow that the console is connected and responsive. Whether echoing happens or not can be controlled programmatically. The Console also has a prompt that is configurable. It is off by default but can be turned on programatically. The\nprompt cahracter can also be changed by the user.", + "text": "In the Mynewt OS, the console library comes in two versions: The sys/console/full package implements the complete console functionality and API. The sys/console/stub package implements stubs for the API. Both packages export the console API, and any package that uses \nthe console API must list console as a requirement. For example, the shell package defines the following pkg.yml \nfile: pkg.name: sys/shell\npkg.deps:\n - kernel/os\n - encoding/base64\n - time/datetime\n - util/crc\npkg.req_apis:\n - console The project pkg.yml file specifies the version of the console package to use.\nA project that requires the full console capability must list the sys/console/full package as a dependency \nin its pkg.yml file. An example is the slinky application. It requires the full console capability and has the following pkg.yml file: pkg.name: apps/slinky\npkg.deps:\n - test/flash_test\n - mgmt/imgmgr\n - mgmt/newtm gr\n - mgmt/newtmgr/transport/nmgr_shell\n - kernel/os\n - boot/bootutil\n - sys/shell\n - sys/console/full\n ...\n - sys/id On the other hand, a project may not have a physical console (e.g. a UART port to connect a terminal to) \nbut may have a dependency on a package that has console capability. In this case, you use \nthe console stub API and list the sys/console/stub package as a dependency in its pkg.yml file. An example is the bootloader project where we want to keep the size of the image small. It includes \nthe kernel/os package that can print out messages on a console (e.g. if there is a hard fault).\nHowever, we do not want to use any console I/O capability in this particular bootloader project to \nkeep the size small. The project uses the console stub API and has the following pkg.yml file: pkg.name: apps/boot\npkg.deps:\n - boot/bootutil\n - kernel/os\n - sys/console/stub Console has 2 modes for transmit; blocking mode a nd non-blocking mode . Usually the non-blocking mode is the \nactive one; the output buffer is drained by getting TX completion interrupts from hardware, and more data is added \nbased on these interrupts. Blocking mode is used when we don't want TX completion interrupts. It is used when system crashes, and we still \nwant to output info related to that crash. Console, by default, echoes everything it receives back. Terminal programs expect this, and is a way for the user to \nknow that the console is connected and responsive. Whether echoing happens or not can be controlled programmatically. The Console also has a prompt that is configurable. It is off by default but can be turned on programmatically. The\nprompt character can also be changed by the user.", "title": "Description" }, { @@ -4962,17 +4912,17 @@ }, { "location": "/os/modules/shell/shell/", - "text": "Shell\n\n\nThe shell is package sitting on top of console, handling 2 jobs: processing console input and implementing \n\nnewtmgr\n line protocol over serial line. Shell runs in its own task.\n\n\nDescription\n\n\n\n\n\n\nShell's first job is directing incoming commands to other subsystems. It parses the incoming character string \nand splits it into tokens. Then it looks for the subsystem to handle this command based on the first token of input.\n\n\n\n\n\n\nSubsystems register their command handlers using \nshell_cmd_register()\n. When shell calls the command handler, it passes the other tokens as arguments.\n\n\n\n\n\n\nA few commands are currently available in the shell - \ntasks\n, \nlog\n, \necho\n, \ndate\n and \nprompt\n.\n\n\n\n\n\n\n\n\n\n\nShell's second job is doing framing, encoding and decoding newtmgr protocol when it's carried over the console. \nProtocol handler (libs/newtmgr) registers itself using \nshell_nlip_input_register()\n, and shell cal ls the registered \nhandler for every frame. Outgoing frames for the protocol are sent using \nshell_nlip_output()\n.\n\n\n\n\n\n\n\n\nCreate a sim target to check out these commands available in shell.\n\n\nuser@~/dev/larva$ newt target create blinky_sim\nCreating target blinky_sim\nTarget blinky_sim successfully created!\nuser@~/dev/larva$ newt target set blinky_sim name=blinky_sim\nTarget blinky_sim successfully set name to blinky_sim\nuser@~/dev/larva$ newt target set blinky_sim arch=sim\nTarget blinky_sim successfully set arch to sim\nuser@~/dev/larva$ newt target set blinky_sim project=blinky\nTarget blinky_sim successfully set project to blinky\nuser@~/dev/larva$ newt target set blinky_sim bsp=hw/bsp/native\nTarget blinky_sim successfully set bsp to hw/bsp/native\nuser@~/dev/larva$ newt target set blinky_sim compiler_def=debug\nTarget blinky_sim successfully set compiler_def to debug\nuser@~/dev/larva$ newt target set blinky_sim compiler=sim\nTarget blinky_sim successfully se t compiler to sim\nuser@~/dev/larva$ newt target show\nblinky_sim\n arch: sim\n bsp: hw/bsp/native\n compiler: sim\n compiler_def: debug\n name: blinky_sim\n project: blinky\nuser@~/dev/larva$ newt target build blinky_sim\nBuilding target blinky_sim (project = blinky)\nCompiling case.c\nCompiling suite.c\nCompiling testutil.c\n..\n..\nBuilding project blinky\nLinking blinky.elf\nSuccessfully run!\n\nuser@~/dev/larva$ ./project/blinky/bin/blinky_sim/blinky.elf\nuart0 at /dev/ttys005\n\n\n\n\n\nOpen up a new terminal to run minicom, a text-based serial port control and terminal emulation program. Set device name to the serial port of the target. \n\n\nuser@~$ minicom -D /dev/ttys005\nWelcome to minicom 2.7\n\nOPTIONS: \nCompiled on Nov 24 2015, 16:14:21.\nPort /dev/ttys005, 11:32:17\n\nPress Meta-Z for help on special keys\n\nlog \n174578:[0] bla\n174578:[0] bab\n\ntasks\n217809:6 tasks: \n217809: shell (prio: 3, nw: 0, flags: 0x0, ssize: 0, cswcnt: 59, tot_run_time : 0ms)\n217840: idle (prio: 255, nw: 0, flags: 0x0, ssize: 0, cswcnt: 18763, tot_run_time: 217809ms)\n217878: uart_poller (prio: 0, nw: 217819, flags: 0x0, ssize: 0, cswcnt: 18667, tot_run_time: 0ms)\n217923: task1 (prio: 1, nw: 218710, flags: 0x0, ssize: 0, cswcnt: 218, tot_run_time: 0ms)\n217953: os_sanity (prio: 254, nw: 218710, flags: 0x0, ssize: 0, cswcnt: 218, tot_run_time: 0ms)\n218010: task2 (prio: 2, nw: 217709, flags: 0x3, ssize: 0, cswcnt: 218, tot_run_time: 0ms)\n\n\nprompt\nUsage: prompt [set|show] [prompt_char]\nprompt set \n\nPrompt set to: \n\n229370: \n\n\n\n\n\n\nData structures\n\n\nThis data structure is used in holding information about registered command handlers.\n\n\nstruct\n \nshell_cmd\n {\n \nchar\n \n*sc_cmd\n;\n \nshell_cmd_func_t\n \nsc_cmd_func\n;\n \nSTAILQ_ENTRY\n(\nshell_cmd\n) \nsc_next\n;\n};\n\n\n\n\n\n\n\n\n\n\n\nElement\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\nsc_cmd\n\n\nCharacter string of the command\n\n\n\n\n\n\nsc_cmd_func\n\n\n Pointer to the command handler\n\n\n\n\n\n\nsc_next\n\n\nBookkeeping linkage internal for shell\n\n\n\n\n\n\n\n\nList of Functions\n\n\n\n\nThe functions available in this OS feature are:\n\n\n\n\n\n\n\n\nFunction\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\nshell_task_init\n\n\nInitializes the shell package. This creates a task for shell, and registers few commands on its own.\n\n\n\n\n\n\nshell_cmd_register\n\n\nRegisters a handler for incoming console commands.\n\n\n\n\n\n\nshell_nlip_input_register\n\n\nRegisters a handler for incoming newtmgr messages.\n\n\n\n\n\n\nshell_nlip_output\n\n\nQueue outgoing newtmgr message for transmission.", + "text": "Shell\n\n\nThe shell runs above the console and provides two functionalities:\n\n\n\n\nProcesses console input. \n\n\nImplements the \nnewtmgr\n line protocol over serial transport. \n\n\n\n\nThe \nsys/shell\n package implements the shell. The shell uses the OS default event queue \nfor shell events and runs in the context of the main task. An application can, optionally, \nspecify a dedicated event queue for the shell to use.\n\n\nDescription\n\n\n\n\n\n\nThe shell's first job is to direct incoming commands to other subsystems. It parses the incoming character string \ninto tokens and uses the first token to determine the subsystem command handler to call to process the command.\n\n\n\n\n\n\nSubsystems register their command handlers using the \nshell_cmd_register()\n \n function. When shell calls the command handler, it passes the other tokens as arguments.\n\n\n\n\n\n\nA few commands are currently available in the shell - \ntasks\n, \nlog\n, \necho\n, \nda te\n and \nprompt\n.\n\n\n\n\n\n\n\n\n\n\nThe shell's second job is to handle packet framing, encoding, and decoding of newtmgr protocol messages that are\nsent over the console. The Newtmgr serial transport package (\nmgmt/newtmgr/transport/newtmgr_shell\n) \ncalls the \nshell_nlip_input_register()\n function to register a handler that the shell calls when it \nreceives newtmgr request messages.\n\n\n\n\n\n\n\n\nCreate a sim target to check out these commands available in shell.\n\n\nuser@~/dev/larva$ newt target create blinky_sim\nCreating target blinky_sim\nTarget blinky_sim successfully created!\nuser@~/dev/larva$ newt target set blinky_sim name=blinky_sim\nTarget blinky_sim successfully set name to blinky_sim\nuser@~/dev/larva$ newt target set blinky_sim arch=sim\nTarget blinky_sim successfully set arch to sim\nuser@~/dev/larva$ newt target set blinky_sim project=blinky\nTarget blinky_sim successfully set project to blinky\nuser@~/dev/larva$ newt target set blinky_sim bsp=hw/b sp/native\nTarget blinky_sim successfully set bsp to hw/bsp/native\nuser@~/dev/larva$ newt target set blinky_sim compiler_def=debug\nTarget blinky_sim successfully set compiler_def to debug\nuser@~/dev/larva$ newt target set blinky_sim compiler=sim\nTarget blinky_sim successfully set compiler to sim\nuser@~/dev/larva$ newt target show\nblinky_sim\n arch: sim\n bsp: hw/bsp/native\n compiler: sim\n compiler_def: debug\n name: blinky_sim\n project: blinky\nuser@~/dev/larva$ newt target build blinky_sim\nBuilding target blinky_sim (project = blinky)\nCompiling case.c\nCompiling suite.c\nCompiling testutil.c\n..\n..\nBuilding project blinky\nLinking blinky.elf\nSuccessfully run!\n\nuser@~/dev/larva$ ./project/blinky/bin/blinky_sim/blinky.elf\nuart0 at /dev/ttys005\n\n\n\n\n\nOpen up a new terminal to run minicom, a text-based serial port control and terminal emulation program. Set device name to the serial port of the target. \n\n\nuser@~$ minicom -D /dev/ttys005\nWelco me to minicom 2.7\n\nOPTIONS: \nCompiled on Nov 24 2015, 16:14:21.\nPort /dev/ttys005, 11:32:17\n\nPress Meta-Z for help on special keys\n\nlog \n174578:[0] bla\n174578:[0] bab\n\ntasks\n217809:6 tasks: \n217809: shell (prio: 3, nw: 0, flags: 0x0, ssize: 0, cswcnt: 59, tot_run_time: 0ms)\n217840: idle (prio: 255, nw: 0, flags: 0x0, ssize: 0, cswcnt: 18763, tot_run_time: 217809ms)\n217878: uart_poller (prio: 0, nw: 217819, flags: 0x0, ssize: 0, cswcnt: 18667, tot_run_time: 0ms)\n217923: task1 (prio: 1, nw: 218710, flags: 0x0, ssize: 0, cswcnt: 218, tot_run_time: 0ms)\n217953: os_sanity (prio: 254, nw: 218710, flags: 0x0, ssize: 0, cswcnt: 218, tot_run_time: 0ms)\n218010: task2 (prio: 2, nw: 217709, flags: 0x3, ssize: 0, cswcnt: 218, tot_run_time: 0ms)\n\n\nprompt\nUsage: prompt [set|show] [prompt_char]\nprompt set \n\nPrompt set to: \n\n229370: \n\n\n\n\n\n\nData structures\n\n\nThis data structure is used in holding information about registered command handlers.\n\n\nstruct\n \nshell_cmd\n {\n \nchar\n \n*sc_cmd\n;\n \nshell_cmd_func_t\n \nsc_cmd_func\n;\n \nSTAILQ_ENTRY\n(\nshell_cmd\n) \nsc_next\n;\n};\n\n\n\n\n\n\n\n\n\n\n\nElement\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\nsc_cmd\n\n\nCharacter string of the command\n\n\n\n\n\n\nsc_cmd_func\n\n\nPointer to the command handler\n\n\n\n\n\n\nsc_next\n\n\nBookkeeping linkage internal for shell\n\n\n\n\n\n\n\n\nList of Functions\n\n\n\n\nThe functions available in this OS feature are:\n\n\n\n\n\n\n\n\nFunction\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\nshell_cmd_register\n\n\nRegisters a handler for incoming console commands.\n\n\n\n\n\n\nshell_nlip_input_register\n\n\nRegisters a handler for incoming newtmgr messages.\n\n\n\n\n\n\nshell_nlip_output\n\n\nQueue outgoing newtmgr message for transmission.\n\n\n\n\n\n\nshell_evq_set\n\n\nSpecifies a dedicated event queue for shell events.", "title": "toc" }, { "location": "/os/modules/shell/shell/#shell", - "text": "The shell is package sitting on top of console, handling 2 jobs: processing console input and implementing newtmgr line protocol over serial line. Shell runs in its own task.", + "text": "The shell runs above the console and provides two functionalities: Processes console input. Implements the newtmgr line protocol over serial transport. The sys/shell package implements the shell. The shell uses the OS default event queue \nfor shell events and runs in the context of the main task. An application can, optionally, \nspecify a dedicated event queue for the shell to use.", "title": "Shell" }, { "location": "/os/modules/shell/shell/#description", - "text": "Shell's first job is directing incoming commands to other subsystems. It parses the incoming character string \nand splits it into tokens. Then it looks for the subsystem to handle this command based on the first token of input. Subsystems register their command handlers using shell_cmd_register() . When shell calls the command handler, it passes the other tokens as arguments. A few commands are currently available in the shell - tasks , log , echo , date and prompt . Shell's second job is doing framing, encoding and decoding newtmgr protocol when it's carried over the console. \nProtocol handler (libs/newtmgr) registers itself using shell_nlip_input_register() , and shell calls the registered \nhandler for every frame. Outgoing frames for the protocol are sent using shell_nlip_output() . Create a sim target to check out these commands available in shell. user@~/dev/larva$ newt target create blinky_sim\nCreating target blinky_sim\nTarget blinky_sim successfully created!\nuser@~/dev/larva$ newt target set blinky_sim name=blinky_sim\nTarget blinky_sim successfully set name to blinky_sim\nuser@~/dev/larva$ newt target set blinky_sim arch=sim\nTarget blinky_sim successfully set arch to sim\nuser@~/dev/larva$ newt target set blinky_sim project=blinky\nTarget blinky_sim successfully set project to blinky\nuser@~/dev/larva$ newt target set blinky_sim bsp=hw/bsp/native\nTarget blinky_sim successfully set bsp to hw/bsp/native\nuser@~/dev/larva$ newt target set blinky_sim compiler_def=debug\nTarget blinky_sim successfully set compiler_def to debug\nuser@~/dev/larva$ newt target set blinky_sim compiler=sim\nTarget blinky_sim successfully set compiler to sim\nuser@~/dev/larva$ newt target show\nblinky_sim\n arch: sim\n bsp: hw/bsp/native\n compiler: sim\n compiler_def: debug\n name: blinky_sim\n project: blinky\nuser@~/dev/larva$ newt target build blinky_sim\nBuilding target blinky_sim (project = blinky)\nCom piling case.c\nCompiling suite.c\nCompiling testutil.c\n..\n..\nBuilding project blinky\nLinking blinky.elf\nSuccessfully run!\n\nuser@~/dev/larva$ ./project/blinky/bin/blinky_sim/blinky.elf\nuart0 at /dev/ttys005 Open up a new terminal to run minicom, a text-based serial port control and terminal emulation program. Set device name to the serial port of the target. user@~$ minicom -D /dev/ttys005\nWelcome to minicom 2.7\n\nOPTIONS: \nCompiled on Nov 24 2015, 16:14:21.\nPort /dev/ttys005, 11:32:17\n\nPress Meta-Z for help on special keys\n\nlog \n174578:[0] bla\n174578:[0] bab\n\ntasks\n217809:6 tasks: \n217809: shell (prio: 3, nw: 0, flags: 0x0, ssize: 0, cswcnt: 59, tot_run_time: 0ms)\n217840: idle (prio: 255, nw: 0, flags: 0x0, ssize: 0, cswcnt: 18763, tot_run_time: 217809ms)\n217878: uart_poller (prio: 0, nw: 217819, flags: 0x0, ssize: 0, cswcnt: 18667, tot_run_time: 0ms)\n217923: task1 (prio: 1, nw: 218710, flags: 0x0, ssize: 0, cswcnt: 218, tot_run_time: 0ms)\n217953: o s_sanity (prio: 254, nw: 218710, flags: 0x0, ssize: 0, cswcnt: 218, tot_run_time: 0ms)\n218010: task2 (prio: 2, nw: 217709, flags: 0x3, ssize: 0, cswcnt: 218, tot_run_time: 0ms)\n\n\nprompt\nUsage: prompt [set|show] [prompt_char]\nprompt set \nPrompt set to: \n229370:", + "text": "The shell's first job is to direct incoming commands to other subsystems. It parses the incoming character string \ninto tokens and uses the first token to determine the subsystem command handler to call to process the command. Subsystems register their command handlers using the shell_cmd_register() \n function. When shell calls the command handler, it passes the other tokens as arguments. A few commands are currently available in the shell - tasks , log , echo , date and prompt . The shell's second job is to handle packet framing, encoding, and decoding of newtmgr protocol messages that are\nsent over the console. The Newtmgr serial transport package ( mgmt/newtmgr/transport/newtmgr_shell ) \ncalls the shell_nlip_input_register() function to register a handler that the shell calls when it \nreceives newtmgr request messages. Create a sim target to check out these commands available in shell. user@~/dev/larva$ newt target create bli nky_sim\nCreating target blinky_sim\nTarget blinky_sim successfully created!\nuser@~/dev/larva$ newt target set blinky_sim name=blinky_sim\nTarget blinky_sim successfully set name to blinky_sim\nuser@~/dev/larva$ newt target set blinky_sim arch=sim\nTarget blinky_sim successfully set arch to sim\nuser@~/dev/larva$ newt target set blinky_sim project=blinky\nTarget blinky_sim successfully set project to blinky\nuser@~/dev/larva$ newt target set blinky_sim bsp=hw/bsp/native\nTarget blinky_sim successfully set bsp to hw/bsp/native\nuser@~/dev/larva$ newt target set blinky_sim compiler_def=debug\nTarget blinky_sim successfully set compiler_def to debug\nuser@~/dev/larva$ newt target set blinky_sim compiler=sim\nTarget blinky_sim successfully set compiler to sim\nuser@~/dev/larva$ newt target show\nblinky_sim\n arch: sim\n bsp: hw/bsp/native\n compiler: sim\n compiler_def: debug\n name: blinky_sim\n project: blinky\nuser@~/dev/larva$ newt target build blinky_sim\nBuildin g target blinky_
<TRUNCATED>
