You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@mynewt.apache.org by ad...@apache.org on 2016/06/28 21:56:19 UTC
[5/7] incubator-mynewt-site git commit: Pushing pull requests #98 by
bgiori and #99 by spoonofpower for function descriptions in docs and Docker
installation instruction changes respectively
http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/ae75dc7d/latest/mkdocs/search_index.json
----------------------------------------------------------------------
diff --git a/latest/mkdocs/search_index.json b/latest/mkdocs/search_index.json
index af84de7..aaf7797 100644
--- a/latest/mkdocs/search_index.json
+++ b/latest/mkdocs/search_index.json
@@ -137,20 +137,30 @@
},
{
"location": "/os/get_started/docker/",
- "text": "Everything You Need in a Docker Container\n\n\nDocker provides a quick and easy way to get up and running with Mynewt. The\nnewt command line tool and the entire build toolchain is available in a single\ndocker container. The container is all that's needed to run your Mynewt based\napplication in the simulator. Enabling USB2 with your docker installation will\nallow you to load your application on a supported device.\n\n\nThe Docker is the only supported option if you are working on a Windows machine. If you are using Mac OS X or Linux, you have the choice of installing a Docker container of tools and toolchains or installing them natively. This chapter describes how to set up the Docker image for all three platforms.\n\n\n\n\nInstall Docker\n\n\nInstall docker for your platform. \nMac OS X\n / \nWindows\n / \nLinux\n\n\nMake sure to double click the Docker Quickstart Terminal application if you're on Mac or Windows.\n\n\n\n\nUse the newt wrapper script\n\n\nUs
e the newt wrapper script to invoke newt. Create the following file, name it\n\nnewt\n, make it executable, and put it in your path. This will allow you to run newt as if it was natively installed. You can now follow the normal tutorials using the newt wrapper script.\n\n\n#!/bin/bash\n\n\ndocker run -e \nNEWT_USER=\n$(\nid -u\n)\n -e \nNEWT_GROUP=\n$(\nid -g\n)\n -e \nNEWT_HOST=\n$(\nuname\n)\n -ti --rm --device\n=\n/dev/bus/usb --privileged -v \n$(pwd)\n:/workspace -w /workspace mynewt/newt:latest /newt \n$@\n\n\n\n\n\n\n\n\nNote 1:\n Remember to point to the correct subdirectory level when invoking \nnewt\n. For example, invoke it using \n../newt\n in the example below.\n\n\nuser@~/dockertest$ ls\nmyproj newt\nuser@~/dockertest$ cd myproj\n\nuser@~/dockertest/myproj$ ../newt version\n\nApache Newt (incubating) version: 0.8.0-b2\n\n\n\n\n\n\n\nNote 2:\n You can upgrade your container by running \ndocker pull mynewt/newt:latest\n when updates are made available.\n\n\n\n\nEnable
USB2 Support for Mac or Windows\n\n\nIf you plan on loading your application on an actual device, do the steps below.\n\n\n\n\nInstall VirtualBox extension pack\n\n\nDocker uses a VirtualBox Linux VM to run containers. A free VirtualBox\nextension pack is required to enable USB2 support. Download the \nVirtualBox\n5.0.16 Oracle VM VirtualBox Extension\nPack\n\nand double click to install\n\n\n\n\nEnable USB2 and select your device\n\n\n\n\n\n\nThe \"default\" VM created by docker-machine must first be stopped before you\n can enable USB2. You have two options:\n\n\n\n\nRun the command \ndocker-machine stop default\n in the terminal window or\n\n\nUse the VirtualBox UI. Right click on \ndefault\n -\n Close -\n Power Off\n\n\n\n\n\n\n\n\nEnable USB2 using the VirtualBox UI. Select the \"default\"\n VM-\nSettings-\nPorts-\nUSB2 to enable USB2. Add your device to the USB Device\n Filters to make the device visible in the docker container. See the image below.\n\n\n\n\n\n\n\n\n\
n\nRestart the \"default\" VM. You have two options:\n\n\nRun \ndocker-machine start default\n in the terminal window or \n\n\nUse the VirtualBox UI. Make sure the \"default\" machine is highlighted. Click the green \"Start\" button. Select \"Headless Start\".\n\n\n\n\n\n\n\n\n\n\nNote 3\n: When working with actual hardware, remember that each board has an ID. If you swap boards and do not refresh the USB Device Filter on the VirtualBox UI, the ID might be stale and the Docker instance may not be able to see the board correctly. For example, you may see an error message like \nError: unable to find CMSIS-DAP device\n when you try to load or run an image on the board. In that case, you need to click on the USB link in VirtualBox UI, remove the existing USB Device Filter (e.g. \"Atmel Corp. EDBG CMSIS-DAP[0101]\") by clicking on the \"Removes selected USB filter\" button, and add a new filter by clicking on the \"Adds new USB filter\" button.",
+ "text": "Everything You Need in a Docker Container\n\n\nDocker provides a quick and easy way to get up and running with Mynewt. The\nnewt command line tool and the entire build toolchain is available in a single\ndocker container. The container is all that's needed to run your Mynewt based\napplication in the simulator. Enabling USB2 with your docker installation will\nallow you to load your application on a supported device.\n\n\nDocker is the only supported option if you are working on a Windows machine. If you are using Mac OS X or Linux, you have the choice of installing a Docker container of tools and toolchains or installing them natively. This chapter describes how to set up the Docker image for all three platforms.\n\n\n\n\nInstall Docker\n\n\nInstall docker for your platform. \nMac OS X\n / \nWindows\n / \nLinux\n\n\nMac and Windows\n\n\nMac and Windows require Docker Toolbox to interact with USB devices. Docker\nfor Mac and Docker for Windows do not support U
SB. Docker Toolbox uses\nVirtualBox and allows you to map USB devices into docker containers as\ndescribed below.\n\n\nMake sure to double click the Docker Quickstart Terminal application if you're\non Mac or Windows.\n\n\nLinux\n\n\nThe docker daemon listens on a Unix domain socket on Linux. That socket is\nowned by root, which means by default you must be root to start a container.\nMake sure to follow the optional step of adding yourself to the docker group so\nyou can start the newt container as yourself.\n\n\n\n\nUse the newt wrapper script\n\n\nUse the newt wrapper script to invoke newt. Create the following file, name it\n\nnewt\n, make it executable, and put it in your path. This will allow you to run newt as if it was natively installed. You can now follow the normal tutorials using the newt wrapper script.\n\n\n#!/bin/bash\n\n\ndocker run -e \nNEWT_USER=\n$(\nid -u\n)\n -e \nNEWT_GROUP=\n$(\nid -g\n)\n -e \nNEWT_HOST=\n$(\nuname\n)\n -ti --rm --device\n=\n/dev/bus/usb -
-privileged -v \n$(pwd)\n:/workspace -w /workspace mynewt/newt:latest /newt \n$@\n\n\n\n\n\n\n\n\nNote 1:\n Remember to point to the correct subdirectory level when invoking \nnewt\n. For example, invoke it using \n../newt\n in the example below.\n\n\nuser@~/dockertest$ ls\nmyproj newt\nuser@~/dockertest$ cd myproj\n\nuser@~/dockertest/myproj$ ../newt version\n\nApache Newt (incubating) version: 0.8.0-b2\n\n\n\n\n\n\n\nNote 2:\n You can upgrade your container by running \ndocker pull mynewt/newt:latest\n when updates are made available.\n\n\n\n\nEnable USB2 Support for Mac or Windows\n\n\nIf you plan on loading your application on an actual device, do the steps below.\n\n\n\n\nInstall VirtualBox extension pack\n\n\nDocker uses a VirtualBox Linux VM to run containers. A free VirtualBox\nextension pack is required to enable USB2 support. Download the \nVirtualBox\n5.0.16 Oracle VM VirtualBox Extension\nPack\n\nand double click to install\n\n\n\n\nEnable USB2 and select your device\
n\n\n\n\n\n\nThe \"default\" VM created by docker-machine must first be stopped before you\n can enable USB2. You have two options:\n\n\n\n\nRun the command \ndocker-machine stop default\n in the terminal window or\n\n\nUse the VirtualBox UI. Right click on \ndefault\n -\n Close -\n Power Off\n\n\n\n\n\n\n\n\nEnable USB2 using the VirtualBox UI. Select the \"default\"\n VM-\nSettings-\nPorts-\nUSB2 to enable USB2. Add your device to the USB Device\n Filters to make the device visible in the docker container. See the image below.\n\n\n\n\n\n\n\n\n\n\nRestart the \"default\" VM. You have two options:\n\n\nRun \ndocker-machine start default\n in the terminal window or \n\n\nUse the VirtualBox UI. Make sure the \"default\" machine is highlighted. Click the green \"Start\" button. Select \"Headless Start\".\n\n\n\n\n\n\n\n\n\n\nNote 3\n: When working with actual hardware, remember that each board has an ID. If you swap boards and do not refresh the USB Device Filter on the Virtual
Box UI, the ID might be stale and the Docker instance may not be able to see the board correctly. For example, you may see an error message like \nError: unable to find CMSIS-DAP device\n when you try to load or run an image on the board. In that case, you need to click on the USB link in VirtualBox UI, remove the existing USB Device Filter (e.g. \"Atmel Corp. EDBG CMSIS-DAP[0101]\") by clicking on the \"Removes selected USB filter\" button, and add a new filter by clicking on the \"Adds new USB filter\" button.",
"title": "Docker Container Option"
},
{
"location": "/os/get_started/docker/#everything-you-need-in-a-docker-container",
- "text": "Docker provides a quick and easy way to get up and running with Mynewt. The\nnewt command line tool and the entire build toolchain is available in a single\ndocker container. The container is all that's needed to run your Mynewt based\napplication in the simulator. Enabling USB2 with your docker installation will\nallow you to load your application on a supported device. The Docker is the only supported option if you are working on a Windows machine. If you are using Mac OS X or Linux, you have the choice of installing a Docker container of tools and toolchains or installing them natively. This chapter describes how to set up the Docker image for all three platforms.",
+ "text": "Docker provides a quick and easy way to get up and running with Mynewt. The\nnewt command line tool and the entire build toolchain is available in a single\ndocker container. The container is all that's needed to run your Mynewt based\napplication in the simulator. Enabling USB2 with your docker installation will\nallow you to load your application on a supported device. Docker is the only supported option if you are working on a Windows machine. If you are using Mac OS X or Linux, you have the choice of installing a Docker container of tools and toolchains or installing them natively. This chapter describes how to set up the Docker image for all three platforms.",
"title": "Everything You Need in a Docker Container"
},
{
"location": "/os/get_started/docker/#install-docker",
- "text": "Install docker for your platform. Mac OS X / Windows / Linux Make sure to double click the Docker Quickstart Terminal application if you're on Mac or Windows.",
+ "text": "Install docker for your platform. Mac OS X / Windows / Linux",
"title": "Install Docker"
},
{
+ "location": "/os/get_started/docker/#mac-and-windows",
+ "text": "Mac and Windows require Docker Toolbox to interact with USB devices. Docker\nfor Mac and Docker for Windows do not support USB. Docker Toolbox uses\nVirtualBox and allows you to map USB devices into docker containers as\ndescribed below. Make sure to double click the Docker Quickstart Terminal application if you're\non Mac or Windows.",
+ "title": "Mac and Windows"
+ },
+ {
+ "location": "/os/get_started/docker/#linux",
+ "text": "The docker daemon listens on a Unix domain socket on Linux. That socket is\nowned by root, which means by default you must be root to start a container.\nMake sure to follow the optional step of adding yourself to the docker group so\nyou can start the newt container as yourself.",
+ "title": "Linux"
+ },
+ {
"location": "/os/get_started/docker/#use-the-newt-wrapper-script",
"text": "Use the newt wrapper script to invoke newt. Create the following file, name it newt , make it executable, and put it in your path. This will allow you to run newt as if it was natively installed. You can now follow the normal tutorials using the newt wrapper script. #!/bin/bash \n\ndocker run -e NEWT_USER= $( id -u ) -e NEWT_GROUP= $( id -g ) -e NEWT_HOST= $( uname ) -ti --rm --device = /dev/bus/usb --privileged -v $(pwd) :/workspace -w /workspace mynewt/newt:latest /newt $@ Note 1: Remember to point to the correct subdirectory level when invoking newt . For example, invoke it using ../newt in the example below. user@~/dockertest$ ls\nmyproj newt\nuser@~/dockertest$ cd myproj user@~/dockertest/myproj$ ../newt version Apache Newt (incubating) version: 0.8.0-b2 Note 2: You can upgrade your container by running docker pull mynewt/newt:latest when updates are made available.",
"title": "Use the newt wrapper script"
@@ -4222,7 +4232,7 @@
},
{
"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 or a console application by entering text input (typically from a keyboard) and reading text output (typically on the computer terminal or monitor). The text written on the console brings some information and 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 \npkg.yml\n file which states that they provide the \nconsole\n API. If a pkg uses this API, it should list \nconsole\n as a requirement.\nFor example, the shell pkg is defined by the following pkg.yml file:\n\n\n pkg.name: libs/shell \n pkg.vers: 0.1\n pkg.dep
s:\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 project requires the full console capability it lists dependency \nlibs/console/full\n in its pkg.yml file. On the other hand, a project may not have a physical console (e.g. a UART port to connect a terminal to) but 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 the \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 pkg that uses full console (but only if SHELL is present to provide a CLI). However, we do not want to use any console I/O capability in this particular bootloader project to keep the size small. We simply use the console stub ins
tead, 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 active one; the output buffer is drained by getting TX completion interrupts from hardware, and more data is added based on these interrupts.\n\nBlocking mode\n is used when we don't want TX completion interrupts. It is used when system crashes, and we still want 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 know that the console is connected and responsive. Whether echoing happens or not can be controlled programmatically.\n\n\nData structures\n\n\nN/A\n\n\nList of Func
tions\n\n\nThe functions available in console are:\n\n\n\n\nconsole_blocking_mode\n\n\nconsole_echo\n\n\nconsole_init\n\n\nconsole_is_init\n\n\nconsole_printf\n\n\nconsole_read\n\n\nconsole_write",
+ "text": "Console\n\n\nThe console is an operating system window where users interact with system programs of the operating system or a console application by entering text input (typically from a keyboard) and reading text output (typically on the computer terminal or monitor). The text written on the console brings some information and 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 \npkg.yml\n file which states that they provide the \nconsole\n API. If a pkg uses this API, it should list \nconsole\n as a requirement.\nFor example, the shell pkg is defined by the following pkg.yml file:\n\n\n pkg.name: libs/shell \n pkg.vers: 0.1\n pkg.dep
s:\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 project requires the full console capability it lists dependency \nlibs/console/full\n in its pkg.yml file. On the other hand, a project may not have a physical console (e.g. a UART port to connect a terminal to) but 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 the \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 pkg that uses full console (but only if SHELL is present to provide a CLI). However, we do not want to use any console I/O capability in this particular bootloader project to keep the size small. We simply use the console stub ins
tead, 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 active one; the output buffer is drained by getting TX completion interrupts from hardware, and more data is added based on these interrupts.\n\nBlocking mode\n is used when we don't want TX completion interrupts. It is used when system crashes, and we still want 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 know that the console is connected and responsive. Whether echoing happens or not can be controlled programmatically.\n\n\nData structures\n\n\nN/A\n\n\nList of Func
tions\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.",
"title": "toc"
},
{
@@ -4242,7 +4252,7 @@
},
{
"location": "/os/modules/console/console/#list-of-functions",
- "text": "The functions available in console are: console_blocking_mode console_echo console_init console_is_init console_printf console_read console_write",
+ "text": "The functions available in console are: Function Description console_blocking_mode Calls the console_blocking_tx function to flush the buffered console output (transmit) queue. console_echo Controls whether echoing is on or off for the console. console_init Initialize the console. console_is_init Returns whether console has been initialized or not. console_printf Writes a formatted message instead of raw output to the console. console_read Copies up the to given number of bytes to the input string. console_write Queues characters to console display over serial port.",
"title": "List of Functions"
},
{
@@ -4432,7 +4442,7 @@
},
{
"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 newtmgr line protocol over serial line. Shell runs on 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, and splits it into tokens. Then it looks for the subsystem to handle this command based on the first token of input.\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\nA few commands are currently available in the shell - \ntasks\n, \nlog\n, and \nstat stat\n. A $ prompt sign will be coming soon!\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. Protocol handler (libs/newtmgr) registers itself using \nshell_nlip_input_register()\n, and shell calls the regis
tered handler 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 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\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\nstat stat\n229881:s0: 1\n\n\n\n\n\nData structures\n\n\nThis data structure is used in holding information about registered command handlers.\n\n\nstruct shell_cmd {\n char *sc_cmd;\n shell_cmd_func_t sc_cmd_func;\n STAILQ_ENTRY(shell_cmd) sc_next;\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 o
f Functions\n\n\n\n\nThe functions available in this OS feature are:\n\n\n\n\nshell_task_init\n\n\nshell_cmd_register\n\n\nshell_nlip_input_register\n\n\nshell_nlip_output",
+ "text": "Shell\n\n\nThe shell is package sitting on top of console, handling 2 jobs: processing console input and implementing newtmgr line protocol over serial line. Shell runs on 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, and splits it into tokens. Then it looks for the subsystem to handle this command based on the first token of input.\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\nA few commands are currently available in the shell - \ntasks\n, \nlog\n, and \nstat stat\n. A $ prompt sign will be coming soon!\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. Protocol handler (libs/newtmgr) registers itself using \nshell_nlip_input_register()\n, and shell calls the regis
tered handler 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 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\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\nstat stat\n229881:s0: 1\n\n\n\n\n\nData structures\n\n\nThis data structure is used in holding information about registered command handlers.\n\n\nstruct shell_cmd {\n char *sc_cmd;\n shell_cmd_func_t sc_cmd_func;\n STAILQ_ENTRY(shell_cmd) sc_next;\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 o
f 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.",
"title": "toc"
},
{
@@ -4452,7 +4462,7 @@
},
{
"location": "/os/modules/shell/shell/#list-of-functions",
- "text": "The functions available in this OS feature are: shell_task_init shell_cmd_register shell_nlip_input_register shell_nlip_output",
+ "text": "The functions available in this OS feature are: Function Description shell_task_init Initializes the shell package. This creates a task for shell, and registers few commands on its own. shell_cmd_register Registers a handler for incoming console commands. shell_nlip_input_register Registers a handler for incoming newtmgr messages. shell_nlip_output Queue outgoing newtmgr message for transmission.",
"title": "List of Functions"
},
{
@@ -4717,7 +4727,7 @@
},
{
"location": "/os/modules/fs/fs/fs/",
- "text": "File System Abstraction\n\n\nMynewt provides a file system abstraction layer (\nfs/fs\n) to allow client code to be file system agnostic. By accessing the file system via the \nfs/fs\n API, client code can perform file system operations without being tied to a particular implementation. When possible, library code should use the \nfs/fs\n API rather than accessing the underlying file system directly.\n\n\nDescription\n\n\nApplications should aim to minimize the amount of code which depends on a particular file system implementation. When possible, only depend on the \nfs/fs\n package. In the simplest case, the only code which needs to know which file system is in use is the code which initializes the file system. In terms of the Mynewt hierarchy, the \napp\n package must depend on a specific file system package, while \nlibrary\n packages should only depend on \nfs/fs\n.\n\n\nThe following example illustrates how file system dependencies should be managed.
In the slinky application, the app is responsible for initializing the file system, so it depends on a concrete file system package called \nfs/nffs\n (Newtron Flash File System). The app explicitly initializes nffs via calls to \nnffs_init()\n, \nnffs_detect()\n and \nnffs_format()\n.\n\n\n# repos/apache-mynewt-core/apps/slinky/pkg.yml\n\npkg.name: repos/apache-mynewt-core/apps/slinky\npkg.deps:\n - fs/nffs\n\n# [...]\n\n\n\n\n\n/* repos/apache-mynewt-core/apps/slinky/src/main.c */\n\n\n\n#include \nnffs/nffs.h\n\n\n\nint\n\n\nmain\n(\nint\n \nargc\n, \nchar\n \n**argv\n)\n{\n \nint\n \nrc\n;\n \nint\n \ncnt\n;\n \nstruct\n \nnffs_area_desc\n \ndescs\n[\nNFFS_AREA_MAX\n];\n\n \nrc\n \n=\n \nnffs_init\n();\n \nassert\n(\nrc\n \n==\n \n0\n);\n\n \ncnt\n \n=\n \nNFFS_AREA_MAX\n;\n \nrc\n \n=\n \nflash_area_to_nffs_desc\n(\nFLASH_AREA_NFFS\n, \ncnt\n, \ndescs\n);\n \nassert\n(\nrc\n \n==\n \n0\n);\n \nif\n (\nnffs_detect\n(\ndescs\n) \n==\n \nFS_ECORRUPT\
n) {\n \nrc\n \n=\n \nnffs_format\n(\ndescs\n);\n \nassert\n(\nrc\n \n==\n \n0\n);\n }\n \n// [...]\n\n}\n\n\n\n\n\nOn the other hand, code which uses the file system after it has been initialized need only depend on \nfs/fs\n. For example, the \nlibs/imgmgr\n package is a library which provides firmware upload and download functionality via the use of a file system. This library is only used after the main app has initialized the file system, and therefore only depends on the \nfs/fs\n package.\n\n\n# repos/apache-mynewt-core/libs/imgmgr/pkg.yml\npkg.name: libs/imgmgr\npkg.deps:\n - fs/fs\n\n# [...]\n\n\n\n\n\nThe \nlibs/imgmgr\n package uses the \nfs/fs\n API for all file system operations.\n\n\nThread Safety\n\n\nAll \nfs/fs\n functions are thread safe.\n\n\nHeader Files\n\n\nAll code which uses the \nfs/fs\n package needs to include the following header:\n\n\n#include \nfs/fs.h\n\n\n\n\n\n\nData Structures\n\n\nAll \nfs/fs\n data structures are opaque to
client code.\n\n\nstruct\n \nfs_file\n;\n\nstruct\n \nfs_dir\n;\n\nstruct\n \nfs_dirent\n;\n\n\n\n\n\nAPI\n\n\nFunctions in \nfs/fs\n that indicate success or failure do so with the following set of return codes:\n\n\n\n\nReturn Codes\n\n\n\n\nThe functions available in this OS feature are:\n\n\n\n\nfs_close\n\n\nfs_closedir\n\n\nfs_dirent_is_dir\n\n\nfs_dirent_name\n\n\nfs_filelen\n\n\nfs_getpos\n\n\nfs_mkdir\n\n\nfs_open\n\n\nfs_opendir\n\n\nfs_read\n\n\nfs_readdir\n\n\nfs_rename\n\n\nfs_seek\n\n\nfs_unlink\n\n\nfs_write\n\n\n\n\nAdditional file system utilities that bundle some of the basic functions above are:\n\n\n\n\nfsutil_read_file\n\n\nfsutil_write_file",
+ "text": "File System Abstraction\n\n\nMynewt provides a file system abstraction layer (\nfs/fs\n) to allow client code to be file system agnostic. By accessing the file system via the \nfs/fs\n API, client code can perform file system operations without being tied to a particular implementation. When possible, library code should use the \nfs/fs\n API rather than accessing the underlying file system directly.\n\n\nDescription\n\n\nApplications should aim to minimize the amount of code which depends on a particular file system implementation. When possible, only depend on the \nfs/fs\n package. In the simplest case, the only code which needs to know which file system is in use is the code which initializes the file system. In terms of the Mynewt hierarchy, the \napp\n package must depend on a specific file system package, while \nlibrary\n packages should only depend on \nfs/fs\n.\n\n\nThe following example illustrates how file system dependencies should be managed.
In the slinky application, the app is responsible for initializing the file system, so it depends on a concrete file system package called \nfs/nffs\n (Newtron Flash File System). The app explicitly initializes nffs via calls to \nnffs_init()\n, \nnffs_detect()\n and \nnffs_format()\n.\n\n\n# repos/apache-mynewt-core/apps/slinky/pkg.yml\n\npkg.name: repos/apache-mynewt-core/apps/slinky\npkg.deps:\n - fs/nffs\n\n# [...]\n\n\n\n\n\n/* repos/apache-mynewt-core/apps/slinky/src/main.c */\n\n\n\n#include \nnffs/nffs.h\n\n\n\nint\n\n\nmain\n(\nint\n \nargc\n, \nchar\n \n**argv\n)\n{\n \nint\n \nrc\n;\n \nint\n \ncnt\n;\n \nstruct\n \nnffs_area_desc\n \ndescs\n[\nNFFS_AREA_MAX\n];\n\n \nrc\n \n=\n \nnffs_init\n();\n \nassert\n(\nrc\n \n==\n \n0\n);\n\n \ncnt\n \n=\n \nNFFS_AREA_MAX\n;\n \nrc\n \n=\n \nflash_area_to_nffs_desc\n(\nFLASH_AREA_NFFS\n, \ncnt\n, \ndescs\n);\n \nassert\n(\nrc\n \n==\n \n0\n);\n \nif\n (\nnffs_detect\n(\ndescs\n) \n==\n \nFS_ECORRUPT\
n) {\n \nrc\n \n=\n \nnffs_format\n(\ndescs\n);\n \nassert\n(\nrc\n \n==\n \n0\n);\n }\n \n// [...]\n\n}\n\n\n\n\n\nOn the other hand, code which uses the file system after it has been initialized need only depend on \nfs/fs\n. For example, the \nlibs/imgmgr\n package is a library which provides firmware upload and download functionality via the use of a file system. This library is only used after the main app has initialized the file system, and therefore only depends on the \nfs/fs\n package.\n\n\n# repos/apache-mynewt-core/libs/imgmgr/pkg.yml\npkg.name: libs/imgmgr\npkg.deps:\n - fs/fs\n\n# [...]\n\n\n\n\n\nThe \nlibs/imgmgr\n package uses the \nfs/fs\n API for all file system operations.\n\n\nThread Safety\n\n\nAll \nfs/fs\n functions are thread safe.\n\n\nHeader Files\n\n\nAll code which uses the \nfs/fs\n package needs to include the following header:\n\n\n#include \nfs/fs.h\n\n\n\n\n\n\nData Structures\n\n\nAll \nfs/fs\n data structures are opaque to
client code.\n\n\nstruct\n \nfs_file\n;\n\nstruct\n \nfs_dir\n;\n\nstruct\n \nfs_dirent\n;\n\n\n\n\n\nAPI\n\n\nFunctions in \nfs/fs\n that indicate success or failure do so with the following set of return codes:\n\n\n\n\nReturn Codes\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\nfs_close\n\n\nCloses the specified file and invalidates the file handle.\n\n\n\n\n\n\nfs_closedir\n\n\nCloses the specified directory handle.\n\n\n\n\n\n\nfs_dirent_is_dir\n\n\nTells you whether the specified directory entry is a sub-directory or a regular file.\n\n\n\n\n\n\nfs_dirent_name\n\n\nRetrieves the filename of the specified directory entry.\n\n\n\n\n\n\nfs_filelen\n\n\nRetrieves the current length of the specified open file.\n\n\n\n\n\n\nfs_getpos\n\n\nRetrieves the current read and write position of the specified open file.\n\n\n\n\n\n\nfs_mkdir\n\n\nCreates the directory represented by the specified path.\n\n\n\n\n\n\nfs
_open\n\n\nOpens a file at the specified path.\n\n\n\n\n\n\nfs_opendir\n\n\nOpens the directory at the specified path.\n\n\n\n\n\n\nfs_read\n\n\nReads data from the specified file.\n\n\n\n\n\n\nfs_readdir\n\n\nReads the next entry in an open directory.\n\n\n\n\n\n\nfs_register\n\n\nRegisters a file system with the abstraction layer.\n\n\n\n\n\n\nfs_rename\n\n\nPerforms a rename and/or move of the specified source path to the specified destination.\n\n\n\n\n\n\nfs_seek\n\n\nPositions a file's read and write pointer at the specified offset.\n\n\n\n\n\n\nfs_unlink\n\n\nUnlinks the file or directory at the specified path.\n\n\n\n\n\n\nfs_write\n\n\nWrites the supplied data to the current offset of the specified file handle.\n\n\n\n\n\n\n\n\nAdditional file system utilities that bundle some of the basic functions above are:\n\n\n\n\n\n\n\n\nFunction\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\nfsutil_read_file\n\n\nOpens a file at the specified path, retrieve data from the file starting from th
e specified offset, and close the file and invalidate the file handle.\n\n\n\n\n\n\nfsutil_write_file\n\n\nOpen a file at the specified path, write the supplied data to the current offset of the specified file handle, and close the file and invalidate the file handle.",
"title": "toc"
},
{
@@ -4747,7 +4757,7 @@
},
{
"location": "/os/modules/fs/fs/fs/#api",
- "text": "Functions in fs/fs that indicate success or failure do so with the following set of return codes: Return Codes The functions available in this OS feature are: fs_close fs_closedir fs_dirent_is_dir fs_dirent_name fs_filelen fs_getpos fs_mkdir fs_open fs_opendir fs_read fs_readdir fs_rename fs_seek fs_unlink fs_write Additional file system utilities that bundle some of the basic functions above are: fsutil_read_file fsutil_write_file",
+ "text": "Functions in fs/fs that indicate success or failure do so with the following set of return codes: Return Codes The functions available in this OS feature are: Function Description fs_close Closes the specified file and invalidates the file handle. fs_closedir Closes the specified directory handle. fs_dirent_is_dir Tells you whether the specified directory entry is a sub-directory or a regular file. fs_dirent_name Retrieves the filename of the specified directory entry. fs_filelen Retrieves the current length of the specified open file. fs_getpos Retrieves the current read and write position of the specified open file. fs_mkdir Creates the directory represented by the specified path. fs_open Opens a file at the specified path. fs_opendir Opens the directory at the specified path. fs_read Reads data from the specified file. fs_readdir Reads the next entry in an open directory. fs_register Registers a fil
e system with the abstraction layer. fs_rename Performs a rename and/or move of the specified source path to the specified destination. fs_seek Positions a file's read and write pointer at the specified offset. fs_unlink Unlinks the file or directory at the specified path. fs_write Writes the supplied data to the current offset of the specified file handle. Additional file system utilities that bundle some of the basic functions above are: Function Description fsutil_read_file Opens a file at the specified path, retrieve data from the file starting from the specified offset, and close the file and invalidate the file handle. fsutil_write_file Open a file at the specified path, write the supplied data to the current offset of the specified file handle, and close the file and invalidate the file handle.",
"title": "API"
},
{
@@ -5367,7 +5377,7 @@
},
{
"location": "/os/modules/fs/nffs/nffs/",
- "text": "Newtron Flash Filesystem (nffs)\n\n\nMynewt includes the Newtron Flash File System (nffs). This file system is designed with two priorities that makes it suitable for embedded use: \n\n\n\n\nMinimal RAM usage\n\n\nReliability\n\n\n\n\nMynewt also provides an abstraction layer API (fs) to allow you to swap out nffs with a different file system of your choice.\n\n\nDescription\n\n\nAreas\n\n\nAt the top level, an nffs disk is partitioned into \nareas\n. An area is a region of disk with the following properties:\n\n\n\n\nAn area can be fully erased without affecting any other areas.\n\n\nWriting to one area does not restrict writes to other areas.\n\n\n\n\nRegarding property 1:\n Generally, flash hardware divides its memory space into \"blocks.\" When erasing flash, entire blocks must be erased in a single operation; partial erases are not possible.\n\n\nRegarding property 2:\n Furthermore, some flash hardware imposes a restriction with regards to writes: writes
within a block must be strictly sequential. For example, if you wish to write to the first 16 bytes of a block, you must write bytes 1 through 15 before writing byte 16. This restriction only applies at the block level; writes to one block have no effect on what parts of other blocks can be written.\n\n\nThus, each area must comprise a discrete number of blocks.\n\n\nInitialization\n\n\nBefore nffs can be used, it must be initialized. There are two means of initializing an nffs file system:\n\n\n\n\nRestore an existing file system via detection.\n\n\nCreate a new file system via formatting.\n\n\n\n\nA typical initialization sequence is the following:\n\n\n\n\nDetect an nffs file system in a specific region of flash.\n\n\nIf no file system was detected, format a new file system in the same flash region.\n\n\n\n\nBoth methods require the user to describe how the flash memory should be divided into nffs areas. This is accomplished with an array of \nstruct nffs_area_desc\n.\n\n\nT
ypically, a product's flash layout is exposed via its BSP-specific \nbsp_flash_dev()\n function. This function retrieves the layout of the specified flash device resident in the BSP. The result of this function can then be converted into the \nstruct nffs_area_desc[]\n that nffs requires. The below example, taken from the slinky project, illustrates the nffs initialization procedure.\n\n\n/*** hw/hal/include/hal/flash_map.h */\n\n\n\n/*\n\n\n * Flash area types\n\n\n */\n\n\n#define FLASH_AREA_BOOTLOADER 0\n\n\n#define FLASH_AREA_IMAGE_0 1\n\n\n#define FLASH_AREA_IMAGE_1 2\n\n\n#define FLASH_AREA_IMAGE_SCRATCH 3\n\n\n#define FLASH_AREA_NFFS 4\n\n\n\n\n\n\n/*** project/slinky/src/main.c */\n\n\n\nint\n\n\nmain\n(\nint\n \nargc\n, \nchar\n \n**argv\n)\n{\n \nint\n \nrc\n;\n \nint\n \ncnt\n;\n\n \n/* NFFS_AREA_MAX is defined in the BSP-specified bsp.h header file. */\n\n \nstruct\n \nnffs_area_desc\n \ndescs\n[\n
NFFS_AREA_MAX\n];\n\n \n/* Initialize nffs\ns internal state. */\n\n \nrc\n \n=\n \nnffs_init\n();\n \nassert\n(\nrc\n \n==\n \n0\n);\n\n \n/* Convert the set of flash blocks we intend to use for nffs into an array\n\n\n * of nffs area descriptors.\n\n\n */\n\n \ncnt\n \n=\n \nNFFS_AREA_MAX\n;\n \nrc\n \n=\n \nflash_area_to_nffs_desc\n(\nFLASH_AREA_NFFS\n, \ncnt\n, \ndescs\n);\n \nassert\n(\nrc\n \n==\n \n0\n);\n\n \n/* Attempt to restore an existing nffs file system from flash. */\n\n \nif\n (\nnffs_detect\n(\ndescs\n) \n==\n \nFS_ECORRUPT\n) {\n \n/* No valid nffs instance detected; format a new one. */\n\n \nrc\n \n=\n \nnffs_format\n(\ndescs\n);\n \nassert\n(\nrc\n \n==\n \n0\n);\n }\n \n/* [ ... ] */\n\n}\n\n\n\n\n\nAfter nffs has been initialized, the application can access the file system via the \nfile system abstraction layer\n.\n\n\nConfiguration\n\n\nThe nffs file system is configured by populating fields in a
global \nstruct nffs_config\n instance. Each field in the structure corresponds to a setting. All configuration must be done prior to calling nffs_init().\n\n\nThe global \nstruct nffs_config\n instance is exposed in \nnffs/nffs.h\n as follows:\n\n\nextern\n \nstruct\n \nnffs_config\n \nnffs_config\n;\n\n\n\n\n\nData Structures\n\n\nThe \nfs/nffs\n package exposes the following data structures:\n\n\n\n\nstruct nffs_area_desc\n\n\nstruct nffs_config\n\n\n\n\nAPI\n\n\nThe functions available in this OS feature are:\n\n\n\n\nnffs_detect\n\n\nnffs_format\n\n\nnffs_init\n\n\n\n\nMiscellaneous measures\n\n\n\n\n\n\nRAM usage:\n\n\n\n\n24 bytes per inode\n\n\n12 bytes per data block\n\n\n36 bytes per inode cache entry\n\n\n32 bytes per data block cache entry\n\n\n\n\n\n\n\n\nMaximum filename size: 256 characters (no null terminator required)\n\n\n\n\nDisallowed filename characters: '/' and '\\0'\n\n\n\n\nInternals\n\n\nnffs implementation details can be found here:\n\n\n\n\nnffs_internal
s\n\n\n\n\nFuture enhancements\n\n\n\n\nError correction.\n\n\nEncryption.\n\n\nCompression.",
+ "text": "Newtron Flash Filesystem (nffs)\n\n\nMynewt includes the Newtron Flash File System (nffs). This file system is designed with two priorities that makes it suitable for embedded use: \n\n\n\n\nMinimal RAM usage\n\n\nReliability\n\n\n\n\nMynewt also provides an abstraction layer API (fs) to allow you to swap out nffs with a different file system of your choice.\n\n\nDescription\n\n\nAreas\n\n\nAt the top level, an nffs disk is partitioned into \nareas\n. An area is a region of disk with the following properties:\n\n\n\n\nAn area can be fully erased without affecting any other areas.\n\n\nWriting to one area does not restrict writes to other areas.\n\n\n\n\nRegarding property 1:\n Generally, flash hardware divides its memory space into \"blocks.\" When erasing flash, entire blocks must be erased in a single operation; partial erases are not possible.\n\n\nRegarding property 2:\n Furthermore, some flash hardware imposes a restriction with regards to writes: writes
within a block must be strictly sequential. For example, if you wish to write to the first 16 bytes of a block, you must write bytes 1 through 15 before writing byte 16. This restriction only applies at the block level; writes to one block have no effect on what parts of other blocks can be written.\n\n\nThus, each area must comprise a discrete number of blocks.\n\n\nInitialization\n\n\nBefore nffs can be used, it must be initialized. There are two means of initializing an nffs file system:\n\n\n\n\nRestore an existing file system via detection.\n\n\nCreate a new file system via formatting.\n\n\n\n\nA typical initialization sequence is the following:\n\n\n\n\nDetect an nffs file system in a specific region of flash.\n\n\nIf no file system was detected, format a new file system in the same flash region.\n\n\n\n\nBoth methods require the user to describe how the flash memory should be divided into nffs areas. This is accomplished with an array of \nstruct nffs_area_desc\n.\n\n\nT
ypically, a product's flash layout is exposed via its BSP-specific \nbsp_flash_dev()\n function. This function retrieves the layout of the specified flash device resident in the BSP. The result of this function can then be converted into the \nstruct nffs_area_desc[]\n that nffs requires. The below example, taken from the slinky project, illustrates the nffs initialization procedure.\n\n\n/*** hw/hal/include/hal/flash_map.h */\n\n\n\n/*\n\n\n * Flash area types\n\n\n */\n\n\n#define FLASH_AREA_BOOTLOADER 0\n\n\n#define FLASH_AREA_IMAGE_0 1\n\n\n#define FLASH_AREA_IMAGE_1 2\n\n\n#define FLASH_AREA_IMAGE_SCRATCH 3\n\n\n#define FLASH_AREA_NFFS 4\n\n\n\n\n\n\n/*** project/slinky/src/main.c */\n\n\n\nint\n\n\nmain\n(\nint\n \nargc\n, \nchar\n \n**argv\n)\n{\n \nint\n \nrc\n;\n \nint\n \ncnt\n;\n\n \n/* NFFS_AREA_MAX is defined in the BSP-specified bsp.h header file. */\n\n \nstruct\n \nnffs_area_desc\n \ndescs\n[\n
NFFS_AREA_MAX\n];\n\n \n/* Initialize nffs\ns internal state. */\n\n \nrc\n \n=\n \nnffs_init\n();\n \nassert\n(\nrc\n \n==\n \n0\n);\n\n \n/* Convert the set of flash blocks we intend to use for nffs into an array\n\n\n * of nffs area descriptors.\n\n\n */\n\n \ncnt\n \n=\n \nNFFS_AREA_MAX\n;\n \nrc\n \n=\n \nflash_area_to_nffs_desc\n(\nFLASH_AREA_NFFS\n, \ncnt\n, \ndescs\n);\n \nassert\n(\nrc\n \n==\n \n0\n);\n\n \n/* Attempt to restore an existing nffs file system from flash. */\n\n \nif\n (\nnffs_detect\n(\ndescs\n) \n==\n \nFS_ECORRUPT\n) {\n \n/* No valid nffs instance detected; format a new one. */\n\n \nrc\n \n=\n \nnffs_format\n(\ndescs\n);\n \nassert\n(\nrc\n \n==\n \n0\n);\n }\n \n/* [ ... ] */\n\n}\n\n\n\n\n\nAfter nffs has been initialized, the application can access the file system via the \nfile system abstraction layer\n.\n\n\nConfiguration\n\n\nThe nffs file system is configured by populating fields in a
global \nstruct nffs_config\n instance. Each field in the structure corresponds to a setting. All configuration must be done prior to calling nffs_init().\n\n\nThe global \nstruct nffs_config\n instance is exposed in \nnffs/nffs.h\n as follows:\n\n\nextern\n \nstruct\n \nnffs_config\n \nnffs_config\n;\n\n\n\n\n\nData Structures\n\n\nThe \nfs/nffs\n package exposes the following data structures:\n\n\n\n\n\n\n\n\nStruct\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\nstruct nffs_area_desc\n\n\nDescriptor for a single nffs area.\n\n\n\n\n\n\nstruct nffs_config\n\n\nConfiguration struct for nffs.\n\n\n\n\n\n\n\n\nAPI\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\nnffs_detect\n\n\nSearches for a valid nffs file system among the specified areas.\n\n\n\n\n\n\nnffs_format\n\n\nErases all the specified areas and initializes them with a clean nffs file system.\n\n\n\n\n\n\nnffs_init\n\n\nInitializes internal nffs memory and data st
ructures.\n\n\n\n\n\n\n\n\nMiscellaneous measures\n\n\n\n\n\n\nRAM usage:\n\n\n\n\n24 bytes per inode\n\n\n12 bytes per data block\n\n\n36 bytes per inode cache entry\n\n\n32 bytes per data block cache entry\n\n\n\n\n\n\n\n\nMaximum filename size: 256 characters (no null terminator required)\n\n\n\n\nDisallowed filename characters: '/' and '\\0'\n\n\n\n\nInternals\n\n\nnffs implementation details can be found here:\n\n\n\n\nnffs_internals\n\n\n\n\nFuture enhancements\n\n\n\n\nError correction.\n\n\nEncryption.\n\n\nCompression.",
"title": "toc"
},
{
@@ -5397,12 +5407,12 @@
},
{
"location": "/os/modules/fs/nffs/nffs/#data-structures",
- "text": "The fs/nffs package exposes the following data structures: struct nffs_area_desc struct nffs_config",
+ "text": "The fs/nffs package exposes the following data structures: Struct Description struct nffs_area_desc Descriptor for a single nffs area. struct nffs_config Configuration struct for nffs.",
"title": "Data Structures"
},
{
"location": "/os/modules/fs/nffs/nffs/#api",
- "text": "The functions available in this OS feature are: nffs_detect nffs_format nffs_init",
+ "text": "The functions available in this OS feature are: Function Description nffs_detect Searches for a valid nffs file system among the specified areas. nffs_format Erases all the specified areas and initializes them with a clean nffs file system. nffs_init Initializes internal nffs memory and data structures.",
"title": "API"
},
{
@@ -5967,7 +5977,7 @@
},
{
"location": "/os/modules/testutil/testutil/",
- "text": "testutil\n\n\nThe testutil package is a test framework that provides facilities for specifying test cases and recording test results.\n\n\nYou would use it to build regression tests for your library.\n\n\nDescription\n\n\nA package may optionally contain a set of test cases. Test cases are not normally compiled and linked when a package is built; they are only included\nwhen the \"test\" identity is specified. All of a package's test code goes in its \nsrc/test\n directory. For example, the nffs package's test code is located in the following directory:\n\n\n * fs/nffs/src/test/\n\n\n\n\n\nThis directory contains the source and header files that implement the nffs test code.\n\n\nThe test code has access to all the header files in the following directories:\n\n\n * src\n * src/arch/\ntarget-arch\n\n * include\n * src/test\n * src/test/arch/\ntarget-arch\n\n * include directories of all package dependencies\n\n\n\n\n\nPackage test code typ
ically depends on the testutil package, described later in this document.\n\n\nSome test cases or test initialization code may be platform-specific. In such cases, the platform-specific function definitions are placed in arch subdirectories within the package test directory.\n\n\nWhile building the test code (i.e., when the \ntest\n identity is specified), the newt tool defines the \nTEST\n macro. This macro is defined during compilation of all C source files in all projects and packages.\n\n\nTests are structured according to the following hierarchy:\n\n\n [test]\n / \\\n [suite] [suite]\n / \\ / \\\n [case] [case] [case] [case]\n\n\n\n\n\nI.e., a test consists of test suites, and a test suite consists of test cases.\n\n\nThe test code uses testutil to define test suites and test cases.\n\n\nRegression test can then be executed using 'newt target test' command, or by including a call to your test suite fr
om \nproject/test/src/test.c\n.\n\n\nExample\n\n\nThis Tutorial\n shows how to create a test suite\nfor a Mynewt package.\n\n\nData structures\n\n\nstruct tu_config {\n int tc_print_results;\n int tc_system_assert;\n\n tu_case_init_fn_t *tc_case_init_cb;\n void *tc_case_init_arg;\n\n tu_case_report_fn_t *tc_case_fail_cb;\n void *tc_case_fail_arg;\n\n tu_case_report_fn_t *tc_case_pass_cb;\n void *tc_case_pass_arg;\n\n tu_suite_init_fn_t *tc_suite_init_cb;\n void *tc_suite_init_arg;\n\n tu_restart_fn_t *tc_restart_cb;\n void *tc_restart_arg;\n};\nextern struct tu_config tu_config;\n\n\n\n\n\nThe global \ntu_config\n struct contains all the testutil package's settings.\nThis should be populated before \ntu_init()\n is called.\n\n\nList of Functions\n\n\n\n\nThe functions, and macros available in \ntestutil\n are:\n\n\n\n\ntu_init\n\n\nTEST_ASSERT\n\n\nTEST_PASS\n\n\nTEST_SUITE\n\n\nTEST_CASE\n\n\nTEST_CASE_DECL\n\n\ntu_restart",
+ "text": "testutil\n\n\nThe testutil package is a test framework that provides facilities for specifying test cases and recording test results.\n\n\nYou would use it to build regression tests for your library.\n\n\nDescription\n\n\nA package may optionally contain a set of test cases. Test cases are not normally compiled and linked when a package is built; they are only included\nwhen the \"test\" identity is specified. All of a package's test code goes in its \nsrc/test\n directory. For example, the nffs package's test code is located in the following directory:\n\n\n * fs/nffs/src/test/\n\n\n\n\n\nThis directory contains the source and header files that implement the nffs test code.\n\n\nThe test code has access to all the header files in the following directories:\n\n\n * src\n * src/arch/\ntarget-arch\n\n * include\n * src/test\n * src/test/arch/\ntarget-arch\n\n * include directories of all package dependencies\n\n\n\n\n\nPackage test code typ
ically depends on the testutil package, described later in this document.\n\n\nSome test cases or test initialization code may be platform-specific. In such cases, the platform-specific function definitions are placed in arch subdirectories within the package test directory.\n\n\nWhile building the test code (i.e., when the \ntest\n identity is specified), the newt tool defines the \nTEST\n macro. This macro is defined during compilation of all C source files in all projects and packages.\n\n\nTests are structured according to the following hierarchy:\n\n\n [test]\n / \\\n [suite] [suite]\n / \\ / \\\n [case] [case] [case] [case]\n\n\n\n\n\nI.e., a test consists of test suites, and a test suite consists of test cases.\n\n\nThe test code uses testutil to define test suites and test cases.\n\n\nRegression test can then be executed using 'newt target test' command, or by including a call to your test suite fr
om \nproject/test/src/test.c\n.\n\n\nExample\n\n\nThis Tutorial\n shows how to create a test suite\nfor a Mynewt package.\n\n\nData structures\n\n\nstruct tu_config {\n int tc_print_results;\n int tc_system_assert;\n\n tu_case_init_fn_t *tc_case_init_cb;\n void *tc_case_init_arg;\n\n tu_case_report_fn_t *tc_case_fail_cb;\n void *tc_case_fail_arg;\n\n tu_case_report_fn_t *tc_case_pass_cb;\n void *tc_case_pass_arg;\n\n tu_suite_init_fn_t *tc_suite_init_cb;\n void *tc_suite_init_arg;\n\n tu_restart_fn_t *tc_restart_cb;\n void *tc_restart_arg;\n};\nextern struct tu_config tu_config;\n\n\n\n\n\nThe global \ntu_config\n struct contains all the testutil package's settings.\nThis should be populated before \ntu_init()\n is called.\n\n\nList of Functions\n\n\n\n\nThe functions, and macros available in \ntestutil\n are:\n\n\n\n\n\n\n\n\nFunction\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\ntu_init\n\n\nInitializes the test framework according to the contents of th
e tu_config struct.\n\n\n\n\n\n\nTEST_ASSERT\n\n\nAsserts that the specified condition is true.\n\n\n\n\n\n\nTEST_PASS\n\n\nReports a success result for the current test.\n\n\n\n\n\n\nTEST_SUITE\n\n\nDeclares a test suite function.\n\n\n\n\n\n\nTEST_CASE\n\n\nDefines a test case function.\n\n\n\n\n\n\nTEST_CASE_DECL\n\n\nDeclares a test case function. his is only required if the test case function exists in a different file than the test suite.\n\n\n\n\n\n\ntu_restart\n\n\nThis function is used when a system reset is necessary to proceed with testing.",
"title": "toc"
},
{
@@ -5992,7 +6002,7 @@
},
{
"location": "/os/modules/testutil/testutil/#list-of-functions",
- "text": "The functions, and macros available in testutil are: tu_init TEST_ASSERT TEST_PASS TEST_SUITE TEST_CASE TEST_CASE_DECL tu_restart",
+ "text": "The functions, and macros available in testutil are: Function Description tu_init Initializes the test framework according to the contents of the tu_config struct. TEST_ASSERT Asserts that the specified condition is true. TEST_PASS Reports a success result for the current test. TEST_SUITE Declares a test suite function. TEST_CASE Defines a test case function. TEST_CASE_DECL Declares a test case function. his is only required if the test case function exists in a different file than the test suite. tu_restart This function is used when a system reset is necessary to proceed with testing.",
"title": "List of Functions"
},
{
@@ -6177,7 +6187,7 @@
},
{
"location": "/os/modules/imgmgr/imgmgr/",
- "text": "Image Manager\n\n\nDescription\n\n\nThis library accepts incoming image management commands from newtmgr and acts on them.\n\n\nImages can be uploaded, present images listed, and system can be told to switch to another image.\n\n\nCurrently the package assumes that there are 2 image slots, one active one and another one in standby. When new image is uploaded, it replaces the one in standby slot. This is the model for scenario when MCU has internal flash only, it executes the code from that flash, and there is enough space to store 2 full images.\n\n\nImage manager interacts with bootloader by telling it to boot to a specific image. At the moment this has to be done by writing a file which contains a version number of the image to boot. Note that image manager itself does not replace the active image.\n\n\nImage manager also can upload files to filesystem as well as download them.\n\n\nNote that commands accessing filesystems (next boot target, file upload/downlo
ad) will not be available unless project includes filesystem implementation.\n\n\nData structures\n\n\nN/A.\n\n\nList of Functions\n\n\n\n\nThe functions available in imgmgr are:\n\n\n\n\nimgmgr_module_init\n\n\nimgr_ver_parse\n\n\nimgr_ver_str",
+ "text": "Image Manager\n\n\nDescription\n\n\nThis library accepts incoming image management commands from newtmgr and acts on them.\n\n\nImages can be uploaded, present images listed, and system can be told to switch to another image.\n\n\nCurrently the package assumes that there are 2 image slots, one active one and another one in standby. When new image is uploaded, it replaces the one in standby slot. This is the model for scenario when MCU has internal flash only, it executes the code from that flash, and there is enough space to store 2 full images.\n\n\nImage manager interacts with bootloader by telling it to boot to a specific image. At the moment this has to be done by writing a file which contains a version number of the image to boot. Note that image manager itself does not replace the active image.\n\n\nImage manager also can upload files to filesystem as well as download them.\n\n\nNote that commands accessing filesystems (next boot target, file upload/downlo
ad) will not be available unless project includes filesystem implementation.\n\n\nData structures\n\n\nN/A.\n\n\nList of Functions\n\n\n\n\nThe functions available in imgmgr are:\n\n\n\n\n\n\n\n\nFunction\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\nimgmgr_module_init\n\n\nRegisters image manager commands with newtmgr.\n\n\n\n\n\n\nimgr_ver_parse\n\n\nParses character string containing specified image version number and writes that to given image_version struct.\n\n\n\n\n\n\nimgr_ver_str\n\n\nTakes version string from specified image_version struct and formats it into a printable string.",
"title": "toc"
},
{
@@ -6197,7 +6207,7 @@
},
{
"location": "/os/modules/imgmgr/imgmgr/#list-of-functions",
- "text": "The functions available in imgmgr are: imgmgr_module_init imgr_ver_parse imgr_ver_str",
+ "text": "The functions available in imgmgr are: Function Description imgmgr_module_init Registers image manager commands with newtmgr. imgr_ver_parse Parses character string containing specified image version number and writes that to given image_version struct. imgr_ver_str Takes version string from specified image_version struct and formats it into a printable string.",
"title": "List of Functions"
},
{
@@ -6317,7 +6327,7 @@
},
{
"location": "/os/modules/elua/elua/",
- "text": "elua\n\n\nDescription\n\n\nThis package contains a Lua interpreter. See http://lua.org for documentation of the language.\n\n\nYou can execute lua scripts either from console with shell or start the execution programmatically.\n\n\nData structures\n\n\nNotes\n\n\nCurrently we don't have language extension modules which would go together with this one, but those should be added.\n\n\nList of Functions\n\n\n\n\nlua_init\n\n\nlua_main",
+ "text": "elua\n\n\nDescription\n\n\nThis package contains a Lua interpreter. See http://lua.org for documentation of the language.\n\n\nYou can execute lua scripts either from console with shell or start the execution programmatically.\n\n\nData structures\n\n\nNotes\n\n\nCurrently we don't have language extension modules which would go together with this one, but those should be added.\n\n\nList of Functions\n\n\n\n\n\n\n\n\nFunction\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\nlua_init\n\n\nRegisters 'lua' command with shell.\n\n\n\n\n\n\nlua_main\n\n\nExecutes lua script in current task's context. Arguments given are passed to lua interpreter.",
"title": "toc"
},
{
@@ -6342,7 +6352,7 @@
},
{
"location": "/os/modules/elua/elua/#list-of-functions",
- "text": "lua_init lua_main",
+ "text": "Function Description lua_init Registers 'lua' command with shell. lua_main Executes lua script in current task's context. Arguments given are passed to lua interpreter.",
"title": "List of Functions"
},
{
@@ -6407,7 +6417,7 @@
},
{
"location": "/os/modules/json/json/",
- "text": "JSON\n\n\nJSON is a data interchange format. The description of this format can be found from IETF RFC 4627.\n\n\nDescription\n\n\nThis package helps in converting between C data types and JSON data objects. It supports both encoding and decoding.\n\n\nData structures\n\n\nEncoding\n\n\n/* Encoding functions */\n\n\ntypedef\n \nint\n (\n*\njson_write_func_t\n)(\nvoid\n \n*buf\n, \nchar\n \n*data\n,\n \nint\n \nlen\n);\n\n\nstruct\n \njson_encoder\n {\n \njson_write_func_t\n \nje_write\n;\n \nvoid\n \n*je_arg\n;\n \nint\n \nje_wr_commas\n:\n1\n;\n \nchar\n \nje_encode_buf\n[\n64\n];\n};\n\n\n\n\n\nHere's the data structure encoder funtions use, and it must be initialized by the caller. The key element is \nje_write\n, which is a function pointer which gets called whenever encoding routine is ready with encoded data. The element \nje_arg\n is passed to \nje_write\n as the first argument. The rest of the structure contents are for internal state
management.\nThis function should collect all the data encoder function generates. It can collect this data to a flat buffer, chain of mbufs or even stream through.\n\n\n/**\n\n\n * For encode. The contents of a JSON value to encode.\n\n\n */\n\n\nstruct\n \njson_value\n {\n \nuint8_t\n \njv_pad1\n;\n \nuint8_t\n \njv_type\n;\n \nuint16_t\n \njv_len\n;\n\n \nunion\n {\n \nuint64_t\n \nu\n;\n \nfloat\n \nfl\n;\n \nchar\n \n*str\n;\n \nstruct\n {\n \nchar\n \n**keys\n;\n \nstruct\n \njson_value\n \n**values\n;\n } \ncomposite\n;\n } \njv_val\n;\n};\n\n\n\n\n\nThis data structure is filled with data to be encoded. It is best to fill this using the macros \nJSON_VALUE_STRING()\n or \nJSON_VALUE_STRINGN()\n when value is string, \nJSON_VALUE_INT()\n when value is an integer, and so forth.\n\n\nDecoding\n\n\n/* when you implement a json buffer, you must implement these functions */\n\n\n\n/* returns the next characte
r in the buffer or \n\\0\n*/\n\n\ntypedef\n \nchar\n (\n*\njson_buffer_read_next_byte_t\n)(\nstruct\n \njson_buffer\n \n*\n);\n\n/* returns the previous character in the buffer or \n\\0\n */\n\n\ntypedef\n \nchar\n (\n*\njson_buffer_read_prev_byte_t\n)(\nstruct\n \njson_buffer\n \n*\n);\n\n/* returns the number of characters read or zero */\n\n\ntypedef\n \nint\n (\n*\njson_buffer_readn_t\n)(\nstruct\n \njson_buffer\n \n*\n, \nchar\n \n*buf\n, \nint\n \nn\n);\n\n\nstruct\n \njson_buffer\n {\n \njson_buffer_readn_t\n \njb_readn\n;\n \njson_buffer_read_next_byte_t\n \njb_read_next\n;\n \njson_buffer_read_prev_byte_t\n \njb_read_prev\n;\n};\n\n\n\n\n\nFunction pointers within this structure are used by decoder when it is reading in more data to decode.\n\n\nstruct\n \njson_attr_t\n {\n \nchar\n \n*attribute\n;\n \njson_type\n \ntype\n;\n \nunion\n {\n \nint\n \n*integer\n;\n \nunsigned\n \nint\n \n*uinteger\n;\n \ndouble\n \n*real\n;\n \nch
ar\n \n*string\n;\n \nbool\n \n*boolean\n;\n \nchar\n \n*character\n;\n \nstruct\n \njson_array_t\n \narray\n;\n \nsize_t\n \noffset\n;\n } \naddr\n;\n \nunion\n {\n \nint\n \ninteger\n;\n \nunsigned\n \nint\n \nuinteger\n;\n \ndouble\n \nreal\n;\n \nbool\n \nboolean\n;\n \nchar\n \ncharacter\n;\n \nchar\n \n*check\n;\n } \ndflt\n;\n \nsize_t\n \nlen\n;\n \nconst\n \nstruct\n \njson_enum_t\n \n*map\n;\n \nbool\n \nnodefault\n;\n};\n\n\n\n\n\nThis structure tells the decoder about a particular name/value pair. Structure must be filled in before calling the decoder routine \njson_read_object()\n.\n\n\n\n\n\n\n\n\nElement\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\nattribute\n\n\nName of the value\n\n\n\n\n\n\ntype\n\n\nThe type of the variable; see enum json_type\n\n\n\n\n\n\naddr\n\n\nContains the address where value should be stored\n\n\n\n\n\n\ndflt\n\n\nDefault value to fill in, if this name is not f
ound\n\n\n\n\n\n\nlen\n\n\nMax number of bytes to read in for value\n\n\n\n\n\n\nnodefault\n\n\nIf set, default value is not copied name\n\n\n\n\n\n\n\n\nList of Functions\n\n\nFunctions for encoding:\n\n\n\n\njson_encode_object_start\n\n\njson_encode_object_key\n\n\njson_encode_object_entry\n\n\njson_encode_object_finish\n\n\n\n\nFunctions for decoding:\n\n\n\n\njson_read_object",
+ "text": "JSON\n\n\nJSON is a data interchange format. The description of this format can be found from IETF RFC 4627.\n\n\nDescription\n\n\nThis package helps in converting between C data types and JSON data objects. It supports both encoding and decoding.\n\n\nData structures\n\n\nEncoding\n\n\n/* Encoding functions */\n\n\ntypedef\n \nint\n (\n*\njson_write_func_t\n)(\nvoid\n \n*buf\n, \nchar\n \n*data\n,\n \nint\n \nlen\n);\n\n\nstruct\n \njson_encoder\n {\n \njson_write_func_t\n \nje_write\n;\n \nvoid\n \n*je_arg\n;\n \nint\n \nje_wr_commas\n:\n1\n;\n \nchar\n \nje_encode_buf\n[\n64\n];\n};\n\n\n\n\n\nHere's the data structure encoder funtions use, and it must be initialized by the caller. The key element is \nje_write\n, which is a function pointer which gets called whenever encoding routine is ready with encoded data. The element \nje_arg\n is passed to \nje_write\n as the first argument. The rest of the structure contents are for internal state
management.\nThis function should collect all the data encoder function generates. It can collect this data to a flat buffer, chain of mbufs or even stream through.\n\n\n/**\n\n\n * For encode. The contents of a JSON value to encode.\n\n\n */\n\n\nstruct\n \njson_value\n {\n \nuint8_t\n \njv_pad1\n;\n \nuint8_t\n \njv_type\n;\n \nuint16_t\n \njv_len\n;\n\n \nunion\n {\n \nuint64_t\n \nu\n;\n \nfloat\n \nfl\n;\n \nchar\n \n*str\n;\n \nstruct\n {\n \nchar\n \n**keys\n;\n \nstruct\n \njson_value\n \n**values\n;\n } \ncomposite\n;\n } \njv_val\n;\n};\n\n\n\n\n\nThis data structure is filled with data to be encoded. It is best to fill this using the macros \nJSON_VALUE_STRING()\n or \nJSON_VALUE_STRINGN()\n when value is string, \nJSON_VALUE_INT()\n when value is an integer, and so forth.\n\n\nDecoding\n\n\n/* when you implement a json buffer, you must implement these functions */\n\n\n\n/* returns the next characte
r in the buffer or \n\\0\n*/\n\n\ntypedef\n \nchar\n (\n*\njson_buffer_read_next_byte_t\n)(\nstruct\n \njson_buffer\n \n*\n);\n\n/* returns the previous character in the buffer or \n\\0\n */\n\n\ntypedef\n \nchar\n (\n*\njson_buffer_read_prev_byte_t\n)(\nstruct\n \njson_buffer\n \n*\n);\n\n/* returns the number of characters read or zero */\n\n\ntypedef\n \nint\n (\n*\njson_buffer_readn_t\n)(\nstruct\n \njson_buffer\n \n*\n, \nchar\n \n*buf\n, \nint\n \nn\n);\n\n\nstruct\n \njson_buffer\n {\n \njson_buffer_readn_t\n \njb_readn\n;\n \njson_buffer_read_next_byte_t\n \njb_read_next\n;\n \njson_buffer_read_prev_byte_t\n \njb_read_prev\n;\n};\n\n\n\n\n\nFunction pointers within this structure are used by decoder when it is reading in more data to decode.\n\n\nstruct\n \njson_attr_t\n {\n \nchar\n \n*attribute\n;\n \njson_type\n \ntype\n;\n \nunion\n {\n \nint\n \n*integer\n;\n \nunsigned\n \nint\n \n*uinteger\n;\n \ndouble\n \n*real\n;\n \nch
ar\n \n*string\n;\n \nbool\n \n*boolean\n;\n \nchar\n \n*character\n;\n \nstruct\n \njson_array_t\n \narray\n;\n \nsize_t\n \noffset\n;\n } \naddr\n;\n \nunion\n {\n \nint\n \ninteger\n;\n \nunsigned\n \nint\n \nuinteger\n;\n \ndouble\n \nreal\n;\n \nbool\n \nboolean\n;\n \nchar\n \ncharacter\n;\n \nchar\n \n*check\n;\n } \ndflt\n;\n \nsize_t\n \nlen\n;\n \nconst\n \nstruct\n \njson_enum_t\n \n*map\n;\n \nbool\n \nnodefault\n;\n};\n\n\n\n\n\nThis structure tells the decoder about a particular name/value pair. Structure must be filled in before calling the decoder routine \njson_read_object()\n.\n\n\n\n\n\n\n\n\nElement\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\nattribute\n\n\nName of the value\n\n\n\n\n\n\ntype\n\n\nThe type of the variable; see enum json_type\n\n\n\n\n\n\naddr\n\n\nContains the address where value should be stored\n\n\n\n\n\n\ndflt\n\n\nDefault value to fill in, if this name is not f
ound\n\n\n\n\n\n\nlen\n\n\nMax number of bytes to read in for value\n\n\n\n\n\n\nnodefault\n\n\nIf set, default value is not copied name\n\n\n\n\n\n\n\n\nList of Functions\n\n\nFunctions for encoding:\n\n\n\n\n\n\n\n\nFunction\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\njson_encode_object_start\n\n\nThis function starts the encoded JSON object.\n\n\n\n\n\n\njson_encode_object_key\n\n\nThis function writes out a name for a field, followed by \":\" character.\n\n\n\n\n\n\njson_encode_object_entry\n\n\nThis function writes out a name for a field, followed by \":\" character, and the value itself.\n\n\n\n\n\n\njson_encode_object_finish\n\n\nThis function finalizes the encoded JSON object.\n\n\n\n\n\n\n\n\nFunctions for decoding:\n\n\n\n\n\n\n\n\nFunction\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\njson_read_object\n\n\nThis function reads in JSON data stream, while looking for name/value pairs described in given attribites.",
"title": "toc"
},
{
@@ -6437,7 +6447,7 @@
},
{
"location": "/os/modules/json/json/#list-of-functions",
- "text": "Functions for encoding: json_encode_object_start json_encode_object_key json_encode_object_entry json_encode_object_finish Functions for decoding: json_read_object",
+ "text": "Functions for encoding: Function Description json_encode_object_start This function starts the encoded JSON object. json_encode_object_key This function writes out a name for a field, followed by \":\" character. json_encode_object_entry This function writes out a name for a field, followed by \":\" character, and the value itself. json_encode_object_finish This function finalizes the encoded JSON object. Functions for decoding: Function Description json_read_object This function reads in JSON data stream, while looking for name/value pairs described in given attribites.",
"title": "List of Functions"
},
{
http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/ae75dc7d/latest/os/get_started/docker/index.html
----------------------------------------------------------------------
diff --git a/latest/os/get_started/docker/index.html b/latest/os/get_started/docker/index.html
index 0ba6e06..7529a32 100644
--- a/latest/os/get_started/docker/index.html
+++ b/latest/os/get_started/docker/index.html
@@ -341,11 +341,22 @@ newt command line tool and the entire build toolchain is available in a single
docker container. The container is all that's needed to run your Mynewt based
application in the simulator. Enabling USB2 with your docker installation will
allow you to load your application on a supported device.</p>
-<p>The Docker is the only supported option if you are working on a Windows machine. If you are using Mac OS X or Linux, you have the choice of installing a Docker container of tools and toolchains or installing them natively. This chapter describes how to set up the Docker image for all three platforms.</p>
+<p>Docker is the only supported option if you are working on a Windows machine. If you are using Mac OS X or Linux, you have the choice of installing a Docker container of tools and toolchains or installing them natively. This chapter describes how to set up the Docker image for all three platforms.</p>
<p><br></p>
<h3 id="install-docker">Install Docker</h3>
-<p>Install docker for your platform. <a href="https://docs.docker.com/mac/">Mac OS X</a> / <a href="https://docs.docker.com/windows/">Windows</a> / <a href="https://docs.docker.com/linux/">Linux</a></p>
-<p>Make sure to double click the Docker Quickstart Terminal application if you're on Mac or Windows.</p>
+<p>Install docker for your platform. <a href="https://www.docker.com/products/docker-toolbox">Mac OS X</a> / <a href="https://www.docker.com/products/docker-toolbox">Windows</a> / <a href="https://docs.docker.com/engine/installation/linux/">Linux</a></p>
+<h4 id="mac-and-windows">Mac and Windows</h4>
+<p>Mac and Windows require Docker Toolbox to interact with USB devices. Docker
+for Mac and Docker for Windows do not support USB. Docker Toolbox uses
+VirtualBox and allows you to map USB devices into docker containers as
+described below.</p>
+<p>Make sure to double click the Docker Quickstart Terminal application if you're
+on Mac or Windows.</p>
+<h4 id="linux">Linux</h4>
+<p>The docker daemon listens on a Unix domain socket on Linux. That socket is
+owned by root, which means by default you must be root to start a container.
+Make sure to follow the optional step of adding yourself to the docker group so
+you can start the newt container as yourself.</p>
<p><br></p>
<h3 id="use-the-newt-wrapper-script">Use the newt wrapper script</h3>
<p>Use the newt wrapper script to invoke newt. Create the following file, name it
http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/ae75dc7d/latest/os/modules/console/console/index.html
----------------------------------------------------------------------
diff --git a/latest/os/modules/console/console/index.html b/latest/os/modules/console/console/index.html
index 939602a..c7ee08f 100644
--- a/latest/os/modules/console/console/index.html
+++ b/latest/os/modules/console/console/index.html
@@ -525,15 +525,44 @@ If project requires the full console capability it lists dependency <code>libs/c
<p>N/A</p>
<h3 id="list-of-functions">List of Functions</h3>
<p>The functions available in console are:</p>
-<ul>
-<li><a href="../console_blocking_mode/">console_blocking_mode</a></li>
-<li><a href="../console_echo/">console_echo</a></li>
-<li><a href="../console_init/">console_init</a></li>
-<li><a href="../console_is_init/">console_is_init</a></li>
-<li><a href="../console_printf/">console_printf</a></li>
-<li><a href="../console_read/">console_read</a></li>
-<li><a href="../console_write/">console_write</a></li>
-</ul>
+<table>
+<thead>
+<tr>
+<th>Function</th>
+<th>Description</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td><a href="../console_blocking_mode/">console_blocking_mode</a></td>
+<td>Calls the <code>console_blocking_tx</code> function to flush the buffered console output (transmit) queue.</td>
+</tr>
+<tr>
+<td><a href="../console_echo/">console_echo</a></td>
+<td>Controls whether echoing is on or off for the console.</td>
+</tr>
+<tr>
+<td><a href="../console_init/">console_init</a></td>
+<td>Initialize the console.</td>
+</tr>
+<tr>
+<td><a href="../console_is_init/">console_is_init</a></td>
+<td>Returns whether console has been initialized or not.</td>
+</tr>
+<tr>
+<td><a href="../console_printf/">console_printf</a></td>
+<td>Writes a formatted message instead of raw output to the console.</td>
+</tr>
+<tr>
+<td><a href="../console_read/">console_read</a></td>
+<td>Copies up the to given number of bytes to the input string.</td>
+</tr>
+<tr>
+<td><a href="../console_write/">console_write</a></td>
+<td>Queues characters to console display over serial port.</td>
+</tr>
+</tbody>
+</table>
<div class="row">
http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/ae75dc7d/latest/os/modules/elua/elua/index.html
----------------------------------------------------------------------
diff --git a/latest/os/modules/elua/elua/index.html b/latest/os/modules/elua/elua/index.html
index cc44f9d..3dfc51a 100644
--- a/latest/os/modules/elua/elua/index.html
+++ b/latest/os/modules/elua/elua/index.html
@@ -489,10 +489,24 @@
<h3 id="notes">Notes</h3>
<p>Currently we don't have language extension modules which would go together with this one, but those should be added.</p>
<h3 id="list-of-functions">List of Functions</h3>
-<ul>
-<li><a href="../lua_init/">lua_init</a></li>
-<li><a href="../lua_main/">lua_main</a></li>
-</ul>
+<table>
+<thead>
+<tr>
+<th>Function</th>
+<th>Description</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td><a href="../lua_init/">lua_init</a></td>
+<td>Registers 'lua' command with shell.</td>
+</tr>
+<tr>
+<td><a href="../lua_main/">lua_main</a></td>
+<td>Executes lua script in current task's context. Arguments given are passed to lua interpreter.</td>
+</tr>
+</tbody>
+</table>
<p><Comments such as these instructions are placed within angle brackets. List all the functions here. Note how the anchors work. You put the text you want to show up as a link within [] and the relevant #heading within (). Note that the header has to have at least 2 words for the anchor to work - that's how it is. "no-highlight" disables syntax highlighting. You can enable it for a particular language by specifying what the language is instead of "no-highlight". Be warned that this highlighting or no-highlighting specification may not show up nicely on Mou.></p>
<div class="row">
http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/ae75dc7d/latest/os/modules/fs/fs/fs/index.html
----------------------------------------------------------------------
diff --git a/latest/os/modules/fs/fs/fs/index.html b/latest/os/modules/fs/fs/fs/index.html
index 0a3d9fe..2ffef55 100644
--- a/latest/os/modules/fs/fs/fs/index.html
+++ b/latest/os/modules/fs/fs/fs/index.html
@@ -610,28 +610,99 @@ pkg.deps:
<li><a href="../fs_return_codes/">Return Codes</a></li>
</ul>
<p>The functions available in this OS feature are:</p>
-<ul>
-<li><a href="../fs_close/">fs_close</a></li>
-<li><a href="../fs_closedir/">fs_closedir</a></li>
-<li><a href="../fs_dirent_is_dir/">fs_dirent_is_dir</a></li>
-<li><a href="../fs_dirent_name/">fs_dirent_name</a></li>
-<li><a href="../fs_filelen/">fs_filelen</a></li>
-<li><a href="../fs_getpos/">fs_getpos</a></li>
-<li><a href="../fs_mkdir/">fs_mkdir</a></li>
-<li><a href="../fs_open/">fs_open</a></li>
-<li><a href="../fs_opendir/">fs_opendir</a></li>
-<li><a href="../fs_read/">fs_read</a></li>
-<li><a href="../fs_readdir/">fs_readdir</a></li>
-<li><a href="../fs_rename/">fs_rename</a></li>
-<li><a href="../fs_seek/">fs_seek</a></li>
-<li><a href="../fs_unlink/">fs_unlink</a></li>
-<li><a href="../fs_write/">fs_write</a></li>
-</ul>
+<table>
+<thead>
+<tr>
+<th>Function</th>
+<th>Description</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td><a href="../fs_close/">fs_close</a></td>
+<td>Closes the specified file and invalidates the file handle.</td>
+</tr>
+<tr>
+<td><a href="../fs_closedir/">fs_closedir</a></td>
+<td>Closes the specified directory handle.</td>
+</tr>
+<tr>
+<td><a href="../fs_dirent_is_dir/">fs_dirent_is_dir</a></td>
+<td>Tells you whether the specified directory entry is a sub-directory or a regular file.</td>
+</tr>
+<tr>
+<td><a href="../fs_dirent_name/">fs_dirent_name</a></td>
+<td>Retrieves the filename of the specified directory entry.</td>
+</tr>
+<tr>
+<td><a href="../fs_filelen/">fs_filelen</a></td>
+<td>Retrieves the current length of the specified open file.</td>
+</tr>
+<tr>
+<td><a href="../fs_getpos/">fs_getpos</a></td>
+<td>Retrieves the current read and write position of the specified open file.</td>
+</tr>
+<tr>
+<td><a href="../fs_mkdir/">fs_mkdir</a></td>
+<td>Creates the directory represented by the specified path.</td>
+</tr>
+<tr>
+<td><a href="../fs_open/">fs_open</a></td>
+<td>Opens a file at the specified path.</td>
+</tr>
+<tr>
+<td><a href="../fs_opendir/">fs_opendir</a></td>
+<td>Opens the directory at the specified path.</td>
+</tr>
+<tr>
+<td><a href="../fs_read/">fs_read</a></td>
+<td>Reads data from the specified file.</td>
+</tr>
+<tr>
+<td><a href="../fs_readdir/">fs_readdir</a></td>
+<td>Reads the next entry in an open directory.</td>
+</tr>
+<tr>
+<td><a href="../fs_register/">fs_register</a></td>
+<td>Registers a file system with the abstraction layer.</td>
+</tr>
+<tr>
+<td><a href="../fs_rename/">fs_rename</a></td>
+<td>Performs a rename and/or move of the specified source path to the specified destination.</td>
+</tr>
+<tr>
+<td><a href="../fs_seek/">fs_seek</a></td>
+<td>Positions a file's read and write pointer at the specified offset.</td>
+</tr>
+<tr>
+<td><a href="../fs_unlink/">fs_unlink</a></td>
+<td>Unlinks the file or directory at the specified path.</td>
+</tr>
+<tr>
+<td><a href="../fs_write/">fs_write</a></td>
+<td>Writes the supplied data to the current offset of the specified file handle.</td>
+</tr>
+</tbody>
+</table>
<p>Additional file system utilities that bundle some of the basic functions above are:</p>
-<ul>
-<li><a href="../fsutil_read_file/">fsutil_read_file</a></li>
-<li><a href="../fsutil_write_file/">fsutil_write_file</a></li>
-</ul>
+<table>
+<thead>
+<tr>
+<th>Function</th>
+<th>Description</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td><a href="../fsutil_read_file/">fsutil_read_file</a></td>
+<td>Opens a file at the specified path, retrieve data from the file starting from the specified offset, and close the file and invalidate the file handle.</td>
+</tr>
+<tr>
+<td><a href="../fsutil_write_file/">fsutil_write_file</a></td>
+<td>Open a file at the specified path, write the supplied data to the current offset of the specified file handle, and close the file and invalidate the file handle.</td>
+</tr>
+</tbody>
+</table>
<div class="row">