You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@nuttx.apache.org by GitBox <gi...@apache.org> on 2020/08/31 00:53:17 UTC
[GitHub] [incubator-nuttx] adamfeuer opened a new pull request #1677: Add Simulator and Drivers guides, and contributing instructions for new users
adamfeuer opened a new pull request #1677:
URL: https://github.com/apache/incubator-nuttx/pull/1677
## Summary
* Adds Simulator and Drivers Guides, and Contributing instructions taken from the [Nuttx Companion](https://nuttx-companion.readthedocs.io/en/latest/) (https://github.com/adamfeuer/nuttx-companion)
* I'm the author of this, and the Companion is already Apache 2.0 Licensed, so this contribution should be ok. 🙂
## Impact
* Adds more documentation for new users
## Testing
* Built docs manually
----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [incubator-nuttx] adamfeuer commented on a change in pull request #1677: Add Simulator and Drivers guides, and contributing instructions for new users
Posted by GitBox <gi...@apache.org>.
adamfeuer commented on a change in pull request #1677:
URL: https://github.com/apache/incubator-nuttx/pull/1677#discussion_r480245407
##########
File path: Documentation/contributing/making-changes.rst
##########
@@ -0,0 +1,256 @@
+.. include:: /substitutions.rst
+.. _making-changes:
+
+Making Changes
+==============
+
+If you want to make changes to NuttX, for your own personal use, or to submit them back to project to improve NuttX,
+that's easy. For the purposes of this guide, you'll need a `GitHub <https://www.github.com>`_ account, since
+the Apache NuttX team uses GitHub. (You could also use git locally, or save your changes to other sites like
+`GitLab <https://about.gitlab.com/>`_ or `BitBucket <https://bitbucket.org>`_, but that's beyond the scope of this
+guide).
+
+Here's how to do it:
+
+#. Set your git user name and email
+
+ .. code-block:: bash
+
+ $ cd nuttx/
+ $ git config --global user.name "Your Name"
+ $ git config --global user.email "yourname@somedomaincom"
+
+#. Sign in to GitHub
+
+ If you don't have a `GitHub <https://www.github.com>`_ account, it's free to
+ sign up.
+ |br|
+ |br|
+
+
+#. Fork the Project
+
+ Visit both these links and hit the Fork button in the upper right of the page:
+
+ * `NuttX <https://github.com/apache/incubator-nuttx/>`_
+ * `NuttX Apps <https://github.com/apache/incubator-nuttx-apps/>`_
+
+
+#. Change the Git Remotes
+
+ The git repositories in your project are currently connected to the official NuttX repositories, but you don't
+ have permission to push software there. But you can push them to your forks, and from there create Pull Requests
+ if you want to send them to the NuttX project.
+
+ First, remove the current remote, ``origin`` (we'll add it back later):
+
+ .. code-block:: bash
+
+ $ cd nuttx/
+ $ # display the remote
+ $ git remote -v
+
+ You should see something like this:
+
+ .. code-block:: bash
+
+ origin https://github.com/apache/incubator-nuttx.git
+
+ Now, on the GitHub web page for your forked ``incubator-nuttx`` project, copy the clone url – get it by hitting the
+ green ``Clone or Download`` button in the upper right. Then do this:
+
+ .. code-block:: bash
+
+ $ git remote rm origin
+ $ git remote add origin <your forked incubator-nuttx project clone url>
+ $ git remote add upstream https://github.com/apache/incubator-nuttx.git
+
+ Do the same for your forked ``incubator-nuttx-apps`` project:
+
+ .. code-block:: bash
+
+ $ cd ../apps
+ $ git remote rm origin
+ $ git remote add origin <your forked incubator-nuttx-apps project clone url>
+ $ git remote add upstream https://github.com/apache/incubator-nuttx-apps.git
+
+
+#. Create a Local Git Branch
+
+ Now you can create local git branches and push them to GitHub:
+
+ .. code-block:: bash
+
+ $ git checkout -b test/my-new-branch
+ $ git push
+
+
+Git Workflow With an Upstream Repository
+----------------------------------------
+
+The main NuttX git repository is called an "upstream" repository - this is because it's the main source of truth, and
+its changes flow downstream to people who've forked that repository, like us.
+
+Working with an upstream repo is a bit more complex, but it's worth it since you can submit fixes and features
+to the main NuttX repos. One of the things you need to do regularly is keep your local repo in sync
+with the upstream. I work with a local branch, make changes, pull new software from the upstream and merge it in,
+maybe doing that several times. Then when everything works, I get my branch ready to do a Pull Request. Here's how:
+
+#. Fetch upstream changes and merge into my local master:
+
+ .. code-block:: bash
+
+ $ git checkout master
+ $ git fetch upstream
+ $ git merge upstream/master
+ $ git push
+
+#. Merge my local master with my local branch:
+
+ .. code-block:: bash
+
+ $ git checkout my-local-branch
+ $ git merge master
+ $ git push
Review comment:
@btashton Will you post the commands for the rebase flow, or point me at a page that specifies them? I'll try the flow and update the instructions.
----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [incubator-nuttx] adamfeuer commented on pull request #1677: Add Simulator and Drivers guides, and contributing instructions for new users
Posted by GitBox <gi...@apache.org>.
adamfeuer commented on pull request #1677:
URL: https://github.com/apache/incubator-nuttx/pull/1677#issuecomment-687438907
@btashton Re: not accepting third party code, really? Not even APL 2.0 code?
----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [incubator-nuttx] v01d commented on a change in pull request #1677: Add Simulator and Drivers guides, and contributing instructions for new users
Posted by GitBox <gi...@apache.org>.
v01d commented on a change in pull request #1677:
URL: https://github.com/apache/incubator-nuttx/pull/1677#discussion_r483852251
##########
File path: Documentation/contributing/making-changes.rst
##########
@@ -202,6 +202,56 @@ squash before submitting the Pull Request:
$ git checkout my-branch
+#. Fetch the upstream code
+
+ .. code-block:: bash
+
+ $ git fetch upstream
+
+#. Rebase onto the upstream code
+
+ * Your favorite text editor will start and shows the commands for the interactive rebasing.
+ * Change the "pick" to "squash" for all the commits you want to squash.
+ * For the series of commits to squash, keep the first one with "pick".
+ * Once you save and exist your editor will start again to merge all the commit messages.
+ * Add a commit message that best describes your change then save and exit.
Review comment:
I think you are confusing interactive with non-interactive rebase. The instruction below is correct but this is non interactive rebase. It simply moves your feature branch to be based on top of master. The text description speaks about interactive rebase which allows you to edit the history, for example for squashing. This should be actually part of the last point where you mention squashing.
----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [incubator-nuttx] adamfeuer commented on a change in pull request #1677: Add Simulator and Drivers guides, and contributing instructions for new users
Posted by GitBox <gi...@apache.org>.
adamfeuer commented on a change in pull request #1677:
URL: https://github.com/apache/incubator-nuttx/pull/1677#discussion_r483852932
##########
File path: Documentation/guides/simulator.rst
##########
@@ -21,50 +23,100 @@ Compiling
There are a lot of simulator configurations available that set you up to test various
operating system features.
+ Here we'll use the ``sim:nsh`` basic NuttX Shell configuration.
+
Review comment:
@v01d Yeah this was a copy paste error, there was some extra stuff there that shouldn't have been there.
----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [incubator-nuttx] v01d commented on a change in pull request #1677: Add Simulator and Drivers guides, and contributing instructions for new users
Posted by GitBox <gi...@apache.org>.
v01d commented on a change in pull request #1677:
URL: https://github.com/apache/incubator-nuttx/pull/1677#discussion_r480214299
##########
File path: Documentation/contributing/making-changes.rst
##########
@@ -0,0 +1,256 @@
+.. include:: /substitutions.rst
+.. _making-changes:
+
+Making Changes
+==============
+
+If you want to make changes to NuttX, for your own personal use, or to submit them back to project to improve NuttX,
+that's easy. For the purposes of this guide, you'll need a `GitHub <https://www.github.com>`_ account, since
+the Apache NuttX team uses GitHub. (You could also use git locally, or save your changes to other sites like
+`GitLab <https://about.gitlab.com/>`_ or `BitBucket <https://bitbucket.org>`_, but that's beyond the scope of this
+guide).
+
+Here's how to do it:
+
+#. Set your git user name and email
+
+ .. code-block:: bash
+
+ $ cd nuttx/
+ $ git config --global user.name "Your Name"
+ $ git config --global user.email "yourname@somedomaincom"
+
+#. Sign in to GitHub
+
+ If you don't have a `GitHub <https://www.github.com>`_ account, it's free to
+ sign up.
+ |br|
+ |br|
+
+
+#. Fork the Project
+
+ Visit both these links and hit the Fork button in the upper right of the page:
+
+ * `NuttX <https://github.com/apache/incubator-nuttx/>`_
+ * `NuttX Apps <https://github.com/apache/incubator-nuttx-apps/>`_
+
+
+#. Change the Git Remotes
+
+ The git repositories in your project are currently connected to the official NuttX repositories, but you don't
+ have permission to push software there. But you can push them to your forks, and from there create Pull Requests
+ if you want to send them to the NuttX project.
+
+ First, remove the current remote, ``origin`` (we'll add it back later):
+
+ .. code-block:: bash
+
+ $ cd nuttx/
+ $ # display the remote
+ $ git remote -v
+
+ You should see something like this:
+
+ .. code-block:: bash
+
+ origin https://github.com/apache/incubator-nuttx.git
+
+ Now, on the GitHub web page for your forked ``incubator-nuttx`` project, copy the clone url – get it by hitting the
+ green ``Clone or Download`` button in the upper right. Then do this:
+
+ .. code-block:: bash
+
+ $ git remote rm origin
+ $ git remote add origin <your forked incubator-nuttx project clone url>
+ $ git remote add upstream https://github.com/apache/incubator-nuttx.git
Review comment:
Yes I think this is confusing. The instructions would be simpler if the user first clones the fork and then adds upstream remote. Also note, that there is set-url to change remote url.
----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [incubator-nuttx] Ouss4 commented on a change in pull request #1677: Add Simulator and Drivers guides, and contributing instructions for new users
Posted by GitBox <gi...@apache.org>.
Ouss4 commented on a change in pull request #1677:
URL: https://github.com/apache/incubator-nuttx/pull/1677#discussion_r480284330
##########
File path: Documentation/contributing/making-changes.rst
##########
@@ -0,0 +1,256 @@
+.. include:: /substitutions.rst
+.. _making-changes:
+
+Making Changes
+==============
+
+If you want to make changes to NuttX, for your own personal use, or to submit them back to project to improve NuttX,
+that's easy. For the purposes of this guide, you'll need a `GitHub <https://www.github.com>`_ account, since
+the Apache NuttX team uses GitHub. (You could also use git locally, or save your changes to other sites like
+`GitLab <https://about.gitlab.com/>`_ or `BitBucket <https://bitbucket.org>`_, but that's beyond the scope of this
+guide).
+
+Here's how to do it:
+
+#. Set your git user name and email
+
+ .. code-block:: bash
+
+ $ cd nuttx/
+ $ git config --global user.name "Your Name"
+ $ git config --global user.email "yourname@somedomaincom"
+
+#. Sign in to GitHub
+
+ If you don't have a `GitHub <https://www.github.com>`_ account, it's free to
+ sign up.
+ |br|
+ |br|
+
+
+#. Fork the Project
+
+ Visit both these links and hit the Fork button in the upper right of the page:
+
+ * `NuttX <https://github.com/apache/incubator-nuttx/>`_
+ * `NuttX Apps <https://github.com/apache/incubator-nuttx-apps/>`_
+
+
+#. Change the Git Remotes
+
+ The git repositories in your project are currently connected to the official NuttX repositories, but you don't
+ have permission to push software there. But you can push them to your forks, and from there create Pull Requests
+ if you want to send them to the NuttX project.
+
+ First, remove the current remote, ``origin`` (we'll add it back later):
+
+ .. code-block:: bash
+
+ $ cd nuttx/
+ $ # display the remote
+ $ git remote -v
+
+ You should see something like this:
+
+ .. code-block:: bash
+
+ origin https://github.com/apache/incubator-nuttx.git
+
+ Now, on the GitHub web page for your forked ``incubator-nuttx`` project, copy the clone url – get it by hitting the
+ green ``Clone or Download`` button in the upper right. Then do this:
+
+ .. code-block:: bash
+
+ $ git remote rm origin
+ $ git remote add origin <your forked incubator-nuttx project clone url>
+ $ git remote add upstream https://github.com/apache/incubator-nuttx.git
+
+ Do the same for your forked ``incubator-nuttx-apps`` project:
+
+ .. code-block:: bash
+
+ $ cd ../apps
+ $ git remote rm origin
+ $ git remote add origin <your forked incubator-nuttx-apps project clone url>
+ $ git remote add upstream https://github.com/apache/incubator-nuttx-apps.git
+
+
+#. Create a Local Git Branch
+
+ Now you can create local git branches and push them to GitHub:
+
+ .. code-block:: bash
+
+ $ git checkout -b test/my-new-branch
+ $ git push
+
+
+Git Workflow With an Upstream Repository
+----------------------------------------
+
+The main NuttX git repository is called an "upstream" repository - this is because it's the main source of truth, and
+its changes flow downstream to people who've forked that repository, like us.
+
+Working with an upstream repo is a bit more complex, but it's worth it since you can submit fixes and features
+to the main NuttX repos. One of the things you need to do regularly is keep your local repo in sync
+with the upstream. I work with a local branch, make changes, pull new software from the upstream and merge it in,
+maybe doing that several times. Then when everything works, I get my branch ready to do a Pull Request. Here's how:
+
+#. Fetch upstream changes and merge into my local master:
+
+ .. code-block:: bash
+
+ $ git checkout master
+ $ git fetch upstream
+ $ git merge upstream/master
+ $ git push
+
+#. Merge my local master with my local branch:
+
+ .. code-block:: bash
+
+ $ git checkout my-local-branch
+ $ git merge master
+ $ git push
Review comment:
> There shouldn't be any work on master on NuttX (much less any rebasing)
Yes, "master" was used just as example.
Ok, now I got you. You are actually doing both the rebasing on top of master and any other interactive rebase operation you want to do at the same time.
I personally don't use both at the same time. I squash or drop commits on the branch and not rebase ontop of master until I'm done.
(and no, I don't use rev-list, there are enough bash/zsh plugins that give the number of commits.)
But I'll concide if you guys find it better this way.
----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [incubator-nuttx] v01d commented on a change in pull request #1677: Add Simulator and Drivers guides, and contributing instructions for new users
Posted by GitBox <gi...@apache.org>.
v01d commented on a change in pull request #1677:
URL: https://github.com/apache/incubator-nuttx/pull/1677#discussion_r480193958
##########
File path: Documentation/guides/simulator.rst
##########
@@ -0,0 +1,145 @@
+.. include:: /substitutions.rst
+.. _simulator:
+
+Simulator
+=========
+
+Apache NuttX has a simulator that can run as a regular program on Linux, Mac, and Windows computers.
+It's useful for debugging operating system features that aren't associated with particular
+device drivers— for instance the TCP/IP stack itself, a web interface or API for your
+application, or other communication protocols. It's also handy for trying out Apache NuttX without
+having a piece of embedded hardware.
+
+This guide assumes you're on Linux. It works on Windows and Mac too— if you know how,
+submit a PR the NuttX Companion to update this guide!
+
+Compiling
+---------
+
+#. Configure the Simulator
+
+ There are a lot of simulator configurations available that set you up to test various
+ operating system features.
+
+ Here we'll use the ``sim:tcpblaster`` configuration because it comes with networking
+ that is ready to use.
+
+ .. code-block:: bash
+
+ $ cd nuttx
+ $ ./tools/configure.sh sim:tcpblaster
+
+#. Compile
+
+ .. code-block:: bash
+
+ $ make clean; make
+
+Running
+-------
+
+#. Give the Simulator Privileges
+
+ On recent Linux distributions, you need to give the ``nuttx`` program the capabilities
+ (similar to permissions) to access the network:
+
+ .. code-block:: bash
+
+ $ sudo setcap cap_net_admin+ep ./nuttx
Review comment:
This would apply to the second example with network so we can put this further below so that it starts with "run the simulator" which is simpler
----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [incubator-nuttx] adamfeuer commented on a change in pull request #1677: Add Simulator and Drivers guides, and contributing instructions for new users
Posted by GitBox <gi...@apache.org>.
adamfeuer commented on a change in pull request #1677:
URL: https://github.com/apache/incubator-nuttx/pull/1677#discussion_r483869828
##########
File path: Documentation/guides/drivers.rst
##########
@@ -0,0 +1,211 @@
+.. include:: /substitutions.rst
+.. _drivers:
+
+Drivers
+=======
+
+Some NuttX boards don't have full support for all the on-chip peripherals. If you need support for this hardware,
+you will either need to port a driver from another chip, or write one yourself. This section discusses how to do that.
+
+Porting a Driver
+----------------
+
+Often support for on-chip peripherals exists in a closely related chip, or even a different family or from a different
+manufacturer. Many chips are made up of different Intellectual Property (IP) blocks that are licensed from vendors like
+Cadence, Synopsys, and others. The IP blocks may be similar enough to use another chip's driver with little
+modification.
+
+* Find a similar driver in NuttX source code:
+
+ * Look at register names listed in the datasheet for the peripheral.
+ * Search the NuttX codebase for the register names (try several different ones).
+ * Note that you'll have to compare the datasheet to the header and code files to see if there are differences; there
+ will usually be some differences between architectures, and they can be significant.
+
+* Find a similar driver in U-Boot source code:
+
+ * Only for inspiration, you can't copy code because of license incompatibility.
+ * But you can debug to see how the driver works.
+ * `U-Boot <https://www.denx.de/wiki/U-Boot>`_ drivers are often easier to understand than BSD Unix drivers because
+ U-Boot is simpler.
+
+* Find a similar driver in Zephyr or BSD Unix (OpenBSD, FreeBSD, NetBSD):
+
+ * If you find one, you can borrow code directly (Apache 2.0 and BSD licenses are compatible).
+
+* Understanding how the driver works
+
+ Here are a couple of techniques that helped me.
+
+ * printf debugging
+
+ * Sprinkle ``custinfo()`` logging statements through your code to see execution paths and look at variables
+ while the code is running. The reason to use ``custinfo()`` as opposed to the other logging shortcuts
+ (``mcinfo()``, etc.) is that you can turn on and off other other logging and still see your custom debug
+ logging. Sometimes it's useful to quiet the flood of logging that comes from a particular debug logging
+ shortcut.
+ * Note that printing info to the console will affect timing.
+ * Keep a file with just your debug settings in it, like this (``debugsettings``):
+
+ .. code-block:: c
+
+ CONFIG_DEBUG_CUSTOM_INFO=y
+ (etc..)
+
+ * Add the settings to the end of your ``.config`` file after running ``make menuconfig`` (that will reorder
+ the file, making it harder to see and change the debug settings if you need to).
+
+ .. code-block:: bash
+
+ $ cat .config debugsettings > .config1 ; mv .config1 .config
+
+ * If you are using interrupts and threads (many things in NuttX run in different threads as a response to interrupts),
+ you can use printf debugging to see overlapping execution.
+
+ * Interrupts - here's how to inspect the C stack frame to see what execution environment is currently running:
+
+ .. code-block:: c
+
+ uint32_t frame = 0; /* MUST be the very first thing in the function */
+ uint32_t p_frame;
+ frame++; /* make sure that frame doesn't get optimized out */
+ p_frame = (uint32_t)(&frame);
+ custinfo("p_frame: %08x\n", p_frame);
+
+ * Threads - here's how to get the thread identifier to see which thread is currently executing:
+
+ .. code-block:: c
+
+ pthread_t thread_id = pthread_self();
+ custinfo("pthread_id: %08x\n", thread_id);
+
+ * stack frame printf
+ * thread printf
+
+ * `GDB — the Gnu Debugger <https://www.gnu.org/software/gdb/>`_
+
+ GDB is a great tool. In this guide we've already used it to load our program and run it. But it can do a lot
+ more. You can single-step through code, examine variables and memory, set breakpoints, and more. I generally use
+ it from the commandline, but have also used it from an IDE like JetBrains' Clion, where it's easier to see the
+ code context.
+
+ One add-on that I found to be essential is the ability to examine blocks of memory, like buffers that NuttX uses
+ for reading and writing to storage media or network adapters. This `Stack Overflow question on using GDB to
+ examine memory <https://stackoverflow.com/a/54784260/431222>`_ includes a GDB command that is very handy. Add
+ this to your ``.gdbinit`` file, and then use the ``xxd`` command to dump memory in an easy-to-read format:
+
+ .. code-block::
+
+ define xxd
+ if $argc < 2
+ set $size = sizeof(*$arg0)
+ else
+ set $size = $arg1
+ end
+ dump binary memory dump.bin $arg0 ((void *)$arg0)+$size
+ eval "shell xxd -o %d dump.bin; rm dump.bin", ((void *)$arg0)
+ end
+ document xxd
+ Dump memory with xxd command (keep the address as offset)
+
+ xxd addr [size]
+ addr -- expression resolvable as an address
+ size -- size (in byte) of memory to dump
+ sizeof(*addr) is used by default end
+
+ Here's a short GDB session that shows what this looks like in practice. Note that the memory location being
+ examined (``0x200aa9eo`` here) is a buffer being passed to ``mmcsd_readsingle``:
+
+ .. code-block::
+
+ Program received signal SIGTRAP, Trace/breakpoint trap.
+ 0x200166e8 in up_idle () at common/arm_idle.c:78
+ 78 }
+ (gdb) b mmcsd_readsingle
+ Breakpoint 1 at 0x2006ea70: file mmcsd/mmcsd_sdio.c, line 1371.
+ (gdb) c
+ Continuing.
+
+ Breakpoint 1, mmcsd_readsingle (priv=0x200aa8c0, buffer=0x200aa9e0 "WRTEST TXT \030", startblock=2432) at mmcsd/mmcsd_sdio.c:1371
+ 1371 finfo("startblock=%d\n", startblock);
+ (gdb) xxd 0x200aa9e0 200
+ 200aa9e0: 5752 5445 5354 2020 5458 5420 1800 0000 WRTEST TXT ....
+ 200aa9f0: 0000 0000 0000 0000 0000 5500 1100 0000 ..........U.....
+ 200aaa00: 5752 5445 5354 3520 5458 5420 1800 0000 WRTEST5 TXT ....
+ 200aaa10: 0000 0000 0000 0000 0000 5800 1500 0000 ..........X.....
+ 200aaa20: e552 5445 5854 3620 5458 5420 1800 0000 .RTEXT6 TXT ....
+ 200aaa30: 0000 0000 0000 0000 0000 5600 1200 0000 ..........V.....
+ 200aaa40: 5752 5445 5354 3620 5458 5420 1800 0000 WRTEST6 TXT ....
+ 200aaa50: 0000 0000 0000 0000 0000 5600 1200 0000 ..........V.....
+ 200aaa60: 0000 0000 0000 0000 0000 0000 0000 0000 ................
+ 200aaa70: 0000 0000 0000 0000 0000 0000 0000 0000 ................
+ 200aaa80: 0000 0000 0000 0000 0000 0000 0000 0000 ................
+ 200aaa90: 0000 0000 0000 0000 0000 0000 0000 0000 ................
+ 200aaaa0: 0000 0000 0000 0000 ........
+
+
+NuttX Drivers as a Reference
+----------------------------
+
+If you're not porting a NuttX driver from another architecture, it still helps to look at other similar NuttX
+drivers, if there are any. For instance, when implementing an Ethernet driver, look at other NuttX Ethernet drivers;
+for an SD Card driver, look at other NuttX Ethernet drivers. Even if the chip-specific code won't be the same, the
+structure to interface with NuttX can be used.
+
+Using Chip Datasheets
+---------------------
+
+To port or write a driver, you'll have to be familiar with the information in the chip datasheet. Definitely find
+the datasheet for your chip, and read the sections relevant to the peripheral you're working with. Doing so ahead
+of time will save a lot of time later.
+
+Another thing that's often helpful is to refer to sample code provided by the manufacturer, or driver code from
+another operating system (like U-Boot, Zephyr, or FreeBSD) while referring to the datasheet — seeing how working
+code implements the necessary algorithms often helps one understand how the driver needs to work.
+
+* How to use a datasheet
+
+ Key pieces of information in System-on-a-Chip (SoC) datasheets are usually:
+
+ * Chip Architecture Diagram — shows how the subsections of the chip (CPU, system bus, peripherals, I/O, etc.) connect
+ to each other.
+ * Memory Map — showing the location of peripheral registers in memory. This info usually goes into a header file.
+ * DMA Engine — if Direct Memory Access (DMA) is used, this may have info on how to use it.
+ * Peripheral — the datasheet usually has a section on how the peripheral works. Key parts of this include:
+
+ * Registers List — name and offset from the base memory address of the peripheral. This needs to go into a header
+ file.
+ * Register Map — what is the size of each register, and what do the bits mean? You will need to create ``#defines``
+ in a header file that your code will use to operate on the registers. Refer to other driver header files for
+ examples.
+
+`Logic analyzers <https://en.wikipedia.org/wiki/Logic_analyzer>`_
+-----------------------------------------------------------------
+
+For drivers that involve input and output (I/O), especially that involve complex protocols like SD Cards, SPI, I2C,
+etc., actually seeing the waveform that goes in and out the chip's pins is extremely helpful. Logic analyzers can
+capture that information and display it graphically, allowing you to see if the driver is doing the right thing
+on the wire.
+
+DMA Debugging
+-------------
+
+* Dump registers before, during, and after transfer. Some NuttX drivers (``sam_sdmmc.c`` or ``imxrt_sdmmc.c`` for
+ example) have built-in code for debugging register states, and can sample registers before, during, and
+ immediately after a DMA transfer, as well as code that can dump the peripheral registers in a nicely-formatted
+ way onto the console device (which can be a serial console, a network console, or memory). Consider using something
+ like this to see what's happening inside the chip if you're trying to debug DMA transfer code.
+* Compare register settings to expected settings determined from the datasheet or from dumping registers from working
+ code in another operating system (U-Boot, Zephyr, FreeBSD, etc.).
+* Use the ``xxd`` GDB tool mentioned above to dump NuttX memory buffers before, during, and after a transfer to see if
+ data is being transferred correctly, if there are over- or under-runs, or to diagnose data being stored in incorrect
+ locations.
+* printf debugging register states can also help here.
+* Remember that logging can change the timing of any algorithms you might be using, so things may start or stop
+ working when logging is added or removed. Definitely test with logging disabled.
+
Review comment:
@btashton Fixed.
----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [incubator-nuttx] btashton commented on a change in pull request #1677: Add Simulator and Drivers guides, and contributing instructions for new users
Posted by GitBox <gi...@apache.org>.
btashton commented on a change in pull request #1677:
URL: https://github.com/apache/incubator-nuttx/pull/1677#discussion_r483873686
##########
File path: Documentation/guides/drivers.rst
##########
@@ -0,0 +1,211 @@
+.. include:: /substitutions.rst
+.. _drivers:
+
+Drivers
+=======
+
+Some NuttX boards don't have full support for all the on-chip peripherals. If you need support for this hardware,
+you will either need to port a driver from another chip, or write one yourself. This section discusses how to do that.
+
+Porting a Driver
+----------------
+
+Often support for on-chip peripherals exists in a closely related chip, or even a different family or from a different
+manufacturer. Many chips are made up of different Intellectual Property (IP) blocks that are licensed from vendors like
+Cadence, Synopsys, and others. The IP blocks may be similar enough to use another chip's driver with little
+modification.
+
+* Find a similar driver in NuttX source code:
+
+ * Look at register names listed in the datasheet for the peripheral.
+ * Search the NuttX codebase for the register names (try several different ones).
+ * Note that you'll have to compare the datasheet to the header and code files to see if there are differences; there
+ will usually be some differences between architectures, and they can be significant.
+
+* Find a similar driver in U-Boot source code:
+
+ * Only for inspiration, you can't copy code because of license incompatibility.
+ * But you can debug to see how the driver works.
+ * `U-Boot <https://www.denx.de/wiki/U-Boot>`_ drivers are often easier to understand than BSD Unix drivers because
+ U-Boot is simpler.
+
+* Find a similar driver in Zephyr or BSD Unix (OpenBSD, FreeBSD, NetBSD):
+
+ * If you find one, you can borrow code directly (Apache 2.0 and BSD licenses are compatible).
Review comment:
It is license compatible, for instance we could decided to include a 3rd party Apache 2.0 compression library and the resulting binary would be under Apache 2.0 but we just cannot say that code is ASF code.
----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [incubator-nuttx] Ouss4 commented on a change in pull request #1677: Add Simulator and Drivers guides, and contributing instructions for new users
Posted by GitBox <gi...@apache.org>.
Ouss4 commented on a change in pull request #1677:
URL: https://github.com/apache/incubator-nuttx/pull/1677#discussion_r479991405
##########
File path: Documentation/contributing/making-changes.rst
##########
@@ -0,0 +1,256 @@
+.. include:: /substitutions.rst
+.. _making-changes:
+
+Making Changes
+==============
+
+If you want to make changes to NuttX, for your own personal use, or to submit them back to project to improve NuttX,
+that's easy. For the purposes of this guide, you'll need a `GitHub <https://www.github.com>`_ account, since
+the Apache NuttX team uses GitHub. (You could also use git locally, or save your changes to other sites like
+`GitLab <https://about.gitlab.com/>`_ or `BitBucket <https://bitbucket.org>`_, but that's beyond the scope of this
+guide).
+
+Here's how to do it:
+
+#. Set your git user name and email
+
+ .. code-block:: bash
+
+ $ cd nuttx/
+ $ git config --global user.name "Your Name"
+ $ git config --global user.email "yourname@somedomaincom"
+
+#. Sign in to GitHub
+
+ If you don't have a `GitHub <https://www.github.com>`_ account, it's free to
+ sign up.
+ |br|
+ |br|
+
+
+#. Fork the Project
+
+ Visit both these links and hit the Fork button in the upper right of the page:
+
+ * `NuttX <https://github.com/apache/incubator-nuttx/>`_
+ * `NuttX Apps <https://github.com/apache/incubator-nuttx-apps/>`_
+
+
+#. Change the Git Remotes
+
+ The git repositories in your project are currently connected to the official NuttX repositories, but you don't
+ have permission to push software there. But you can push them to your forks, and from there create Pull Requests
+ if you want to send them to the NuttX project.
+
+ First, remove the current remote, ``origin`` (we'll add it back later):
+
+ .. code-block:: bash
+
+ $ cd nuttx/
+ $ # display the remote
+ $ git remote -v
+
+ You should see something like this:
+
+ .. code-block:: bash
+
+ origin https://github.com/apache/incubator-nuttx.git
+
+ Now, on the GitHub web page for your forked ``incubator-nuttx`` project, copy the clone url – get it by hitting the
+ green ``Clone or Download`` button in the upper right. Then do this:
+
+ .. code-block:: bash
+
+ $ git remote rm origin
+ $ git remote add origin <your forked incubator-nuttx project clone url>
+ $ git remote add upstream https://github.com/apache/incubator-nuttx.git
+
+ Do the same for your forked ``incubator-nuttx-apps`` project:
+
+ .. code-block:: bash
+
+ $ cd ../apps
+ $ git remote rm origin
+ $ git remote add origin <your forked incubator-nuttx-apps project clone url>
+ $ git remote add upstream https://github.com/apache/incubator-nuttx-apps.git
+
+
+#. Create a Local Git Branch
+
+ Now you can create local git branches and push them to GitHub:
+
+ .. code-block:: bash
+
+ $ git checkout -b test/my-new-branch
+ $ git push
+
+
+Git Workflow With an Upstream Repository
+----------------------------------------
+
+The main NuttX git repository is called an "upstream" repository - this is because it's the main source of truth, and
+its changes flow downstream to people who've forked that repository, like us.
+
+Working with an upstream repo is a bit more complex, but it's worth it since you can submit fixes and features
+to the main NuttX repos. One of the things you need to do regularly is keep your local repo in sync
+with the upstream. I work with a local branch, make changes, pull new software from the upstream and merge it in,
+maybe doing that several times. Then when everything works, I get my branch ready to do a Pull Request. Here's how:
+
+#. Fetch upstream changes and merge into my local master:
+
+ .. code-block:: bash
+
+ $ git checkout master
+ $ git fetch upstream
+ $ git merge upstream/master
+ $ git push
+
+#. Merge my local master with my local branch:
+
+ .. code-block:: bash
+
+ $ git checkout my-local-branch
+ $ git merge master
+ $ git push
+
+#. Make changes and push them to my fork
+
+ .. code-block:: bash
+
+ $ vim my-file.c
+ $ git add my-file.c
+ $ git commit my-file.c
+ $ git push
+
+#. Repeat 1-3 as necessary
+
+#. Run the ``tools/checkpatch.sh`` script on your files
+
+ When your code runs, then you're almost ready to submit it. But first you need to check the code to ensure
+ that it conforms to the NuttX :ref:`contributing/coding_style:C Coding Standard`.
+ The ``tools/checkpatch.sh`` script will do that. Here's the usage info:
+
+ .. code-block:: bash
+
+ $ ./tools/checkpatch.sh -h
+ USAGE: ./tools/checkpatch.sh [options] [list|-]
+
+ Options:
+ -h
+ -c spell check with codespell(install with: pip install codespell
+ -r range check only (used with -p and -g)
+ -p <patch list> (default)
+ -g <commit list>
+ -f <file list>
+ - read standard input mainly used by git pre-commit hook as below:
+ git diff --cached | ./tools/checkpatch.sh -
+
+ Run it against your files and correct all the errors in the code you added, so that
+ ``tools/checkpatch.sh`` reports no errors. Then commit the result.
+ For example:
+
+ .. code-block:: bash
+
+ $ ./tools/checkpatch.sh -f my-file.c
+ arch/arm/src/sama5/hardware/my-file.c:876:82: warning: Long line found
+ $ # fix errors
+ $ vim my-file.c
+ $ # run again
+ $ ./tools/checkpatch.sh -f my-file.c
+
+ If you have made a lot of changes, you can also use this bash commandline to see the errors for all the changed C
+ files in your branch (assumes you are currently on the branch that has the changed files):
+
+ .. code-block:: bash
+
+ $ git diff --name-only master | egrep "\.c|\.h" | xargs echo | xargs ./tools/checkpatch.sh -f | less
+
+ Note that there are some bugs in the ``nxstyle`` program that ``checkpatch.sh`` uses, so
+ it may report a few errors that are not actually errors. The committers will help you
+ find these. (Or view the
+ `nxstyle Issues <https://github.com/apache/incubator-nuttx/issues?q=is%3Aissue+is%3Aopen+nxstyle>`_.)
+ |br|
+ |br|
+
+#. Commit the fixed files
+
+ .. code-block:: bash
+
+ $ git add my-file.c
+ $ git commit my-file.c
+ $ git push
+
+
+Submitting Your Changes to NuttX
+--------------------------------
+
+ Pull requests let you tell others about changes you've pushed to a branch in a repository on GitHub. Once a pull
+ request is opened, you can discuss and review the potential changes with collaborators and add follow-up commits
+ before your changes are merged into the base branch.
+
+ (from GitHub's `About pull requests <https://docs.github.com/en/github/collaborating-with-issues-and-pull-requests/about-pull-requests>`_ page)
+
+Before you do a Pull Request, the NuttX team will usually want all the changes you made in your branch "squashed" into
+a single commit, so that when they review your changes, there's a clean view of the history. If there are changes
+after Pull Request review feedback, they can be separate commits. Here's the easiest way I found to do that initial
+squash before submitting the Pull Request:
+
+#. Check out my branch
+
+ .. code-block:: bash
+
+ $ git checkout my-branch
+
+#. Rename it to ``my-branch-old`` to save it, because we're going to create new clean branch to push:
+
+ .. code-block:: bash
+
+ $ git branch -m my-branch-old
Review comment:
I think interactive rebasing is a better practice to achieve the same.
----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [incubator-nuttx] Ouss4 commented on a change in pull request #1677: Add Simulator and Drivers guides, and contributing instructions for new users
Posted by GitBox <gi...@apache.org>.
Ouss4 commented on a change in pull request #1677:
URL: https://github.com/apache/incubator-nuttx/pull/1677#discussion_r480261018
##########
File path: Documentation/contributing/making-changes.rst
##########
@@ -0,0 +1,256 @@
+.. include:: /substitutions.rst
+.. _making-changes:
+
+Making Changes
+==============
+
+If you want to make changes to NuttX, for your own personal use, or to submit them back to project to improve NuttX,
+that's easy. For the purposes of this guide, you'll need a `GitHub <https://www.github.com>`_ account, since
+the Apache NuttX team uses GitHub. (You could also use git locally, or save your changes to other sites like
+`GitLab <https://about.gitlab.com/>`_ or `BitBucket <https://bitbucket.org>`_, but that's beyond the scope of this
+guide).
+
+Here's how to do it:
+
+#. Set your git user name and email
+
+ .. code-block:: bash
+
+ $ cd nuttx/
+ $ git config --global user.name "Your Name"
+ $ git config --global user.email "yourname@somedomaincom"
+
+#. Sign in to GitHub
+
+ If you don't have a `GitHub <https://www.github.com>`_ account, it's free to
+ sign up.
+ |br|
+ |br|
+
+
+#. Fork the Project
+
+ Visit both these links and hit the Fork button in the upper right of the page:
+
+ * `NuttX <https://github.com/apache/incubator-nuttx/>`_
+ * `NuttX Apps <https://github.com/apache/incubator-nuttx-apps/>`_
+
+
+#. Change the Git Remotes
+
+ The git repositories in your project are currently connected to the official NuttX repositories, but you don't
+ have permission to push software there. But you can push them to your forks, and from there create Pull Requests
+ if you want to send them to the NuttX project.
+
+ First, remove the current remote, ``origin`` (we'll add it back later):
+
+ .. code-block:: bash
+
+ $ cd nuttx/
+ $ # display the remote
+ $ git remote -v
+
+ You should see something like this:
+
+ .. code-block:: bash
+
+ origin https://github.com/apache/incubator-nuttx.git
+
+ Now, on the GitHub web page for your forked ``incubator-nuttx`` project, copy the clone url – get it by hitting the
+ green ``Clone or Download`` button in the upper right. Then do this:
+
+ .. code-block:: bash
+
+ $ git remote rm origin
+ $ git remote add origin <your forked incubator-nuttx project clone url>
+ $ git remote add upstream https://github.com/apache/incubator-nuttx.git
+
+ Do the same for your forked ``incubator-nuttx-apps`` project:
+
+ .. code-block:: bash
+
+ $ cd ../apps
+ $ git remote rm origin
+ $ git remote add origin <your forked incubator-nuttx-apps project clone url>
+ $ git remote add upstream https://github.com/apache/incubator-nuttx-apps.git
+
+
+#. Create a Local Git Branch
+
+ Now you can create local git branches and push them to GitHub:
+
+ .. code-block:: bash
+
+ $ git checkout -b test/my-new-branch
+ $ git push
+
+
+Git Workflow With an Upstream Repository
+----------------------------------------
+
+The main NuttX git repository is called an "upstream" repository - this is because it's the main source of truth, and
+its changes flow downstream to people who've forked that repository, like us.
+
+Working with an upstream repo is a bit more complex, but it's worth it since you can submit fixes and features
+to the main NuttX repos. One of the things you need to do regularly is keep your local repo in sync
+with the upstream. I work with a local branch, make changes, pull new software from the upstream and merge it in,
+maybe doing that several times. Then when everything works, I get my branch ready to do a Pull Request. Here's how:
+
+#. Fetch upstream changes and merge into my local master:
+
+ .. code-block:: bash
+
+ $ git checkout master
+ $ git fetch upstream
+ $ git merge upstream/master
+ $ git push
+
+#. Merge my local master with my local branch:
+
+ .. code-block:: bash
+
+ $ git checkout my-local-branch
+ $ git merge master
+ $ git push
Review comment:
For just rebase, yes, this is how it's explained. But for interactive rebase, I don't see how that would work. I'm trying but can't get it to work. I'm getting "noop" in the rebase "editor".
----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [incubator-nuttx] v01d merged pull request #1677: Add Simulator and Drivers guides, and contributing instructions for new users
Posted by GitBox <gi...@apache.org>.
v01d merged pull request #1677:
URL: https://github.com/apache/incubator-nuttx/pull/1677
----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [incubator-nuttx] v01d commented on pull request #1677: Add Simulator and Drivers guides, and contributing instructions for new users
Posted by GitBox <gi...@apache.org>.
v01d commented on pull request #1677:
URL: https://github.com/apache/incubator-nuttx/pull/1677#issuecomment-687452381
Done!
----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [incubator-nuttx] adamfeuer commented on pull request #1677: Add Simulator and Drivers guides, and contributing instructions for new users
Posted by GitBox <gi...@apache.org>.
adamfeuer commented on pull request #1677:
URL: https://github.com/apache/incubator-nuttx/pull/1677#issuecomment-687396452
@v01d Re: the drivers section, will you suggest a new name for it then?
----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [incubator-nuttx] btashton commented on pull request #1677: Add Simulator and Drivers guides, and contributing instructions for new users
Posted by GitBox <gi...@apache.org>.
btashton commented on pull request #1677:
URL: https://github.com/apache/incubator-nuttx/pull/1677#issuecomment-687441745
> @btashton Re: not accepting third party code, really? Not even APL 2.0 code?
Yes because otherwise we have to carry the copyright for the file as well. See Item 1)
https://www.apache.org/legal/src-headers.html#headers
----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [incubator-nuttx] btashton commented on a change in pull request #1677: Add Simulator and Drivers guides, and contributing instructions for new users
Posted by GitBox <gi...@apache.org>.
btashton commented on a change in pull request #1677:
URL: https://github.com/apache/incubator-nuttx/pull/1677#discussion_r480267094
##########
File path: Documentation/contributing/making-changes.rst
##########
@@ -0,0 +1,256 @@
+.. include:: /substitutions.rst
+.. _making-changes:
+
+Making Changes
+==============
+
+If you want to make changes to NuttX, for your own personal use, or to submit them back to project to improve NuttX,
+that's easy. For the purposes of this guide, you'll need a `GitHub <https://www.github.com>`_ account, since
+the Apache NuttX team uses GitHub. (You could also use git locally, or save your changes to other sites like
+`GitLab <https://about.gitlab.com/>`_ or `BitBucket <https://bitbucket.org>`_, but that's beyond the scope of this
+guide).
+
+Here's how to do it:
+
+#. Set your git user name and email
+
+ .. code-block:: bash
+
+ $ cd nuttx/
+ $ git config --global user.name "Your Name"
+ $ git config --global user.email "yourname@somedomaincom"
+
+#. Sign in to GitHub
+
+ If you don't have a `GitHub <https://www.github.com>`_ account, it's free to
+ sign up.
+ |br|
+ |br|
+
+
+#. Fork the Project
+
+ Visit both these links and hit the Fork button in the upper right of the page:
+
+ * `NuttX <https://github.com/apache/incubator-nuttx/>`_
+ * `NuttX Apps <https://github.com/apache/incubator-nuttx-apps/>`_
+
+
+#. Change the Git Remotes
+
+ The git repositories in your project are currently connected to the official NuttX repositories, but you don't
+ have permission to push software there. But you can push them to your forks, and from there create Pull Requests
+ if you want to send them to the NuttX project.
+
+ First, remove the current remote, ``origin`` (we'll add it back later):
+
+ .. code-block:: bash
+
+ $ cd nuttx/
+ $ # display the remote
+ $ git remote -v
+
+ You should see something like this:
+
+ .. code-block:: bash
+
+ origin https://github.com/apache/incubator-nuttx.git
+
+ Now, on the GitHub web page for your forked ``incubator-nuttx`` project, copy the clone url – get it by hitting the
+ green ``Clone or Download`` button in the upper right. Then do this:
+
+ .. code-block:: bash
+
+ $ git remote rm origin
+ $ git remote add origin <your forked incubator-nuttx project clone url>
+ $ git remote add upstream https://github.com/apache/incubator-nuttx.git
+
+ Do the same for your forked ``incubator-nuttx-apps`` project:
+
+ .. code-block:: bash
+
+ $ cd ../apps
+ $ git remote rm origin
+ $ git remote add origin <your forked incubator-nuttx-apps project clone url>
+ $ git remote add upstream https://github.com/apache/incubator-nuttx-apps.git
+
+
+#. Create a Local Git Branch
+
+ Now you can create local git branches and push them to GitHub:
+
+ .. code-block:: bash
+
+ $ git checkout -b test/my-new-branch
+ $ git push
+
+
+Git Workflow With an Upstream Repository
+----------------------------------------
+
+The main NuttX git repository is called an "upstream" repository - this is because it's the main source of truth, and
+its changes flow downstream to people who've forked that repository, like us.
+
+Working with an upstream repo is a bit more complex, but it's worth it since you can submit fixes and features
+to the main NuttX repos. One of the things you need to do regularly is keep your local repo in sync
+with the upstream. I work with a local branch, make changes, pull new software from the upstream and merge it in,
+maybe doing that several times. Then when everything works, I get my branch ready to do a Pull Request. Here's how:
+
+#. Fetch upstream changes and merge into my local master:
+
+ .. code-block:: bash
+
+ $ git checkout master
+ $ git fetch upstream
+ $ git merge upstream/master
+ $ git push
+
+#. Merge my local master with my local branch:
+
+ .. code-block:: bash
+
+ $ git checkout my-local-branch
+ $ git merge master
+ $ git push
Review comment:
This is what I have done for years so I'm confident that it works. There is no difference in how the ref is resolved interactive or not.
```
git checkout mybranch
git fetch upstream
git rebase upstream/master
```
http://kensheedlo.com/essays/why-you-should-use-a-rebase-workflow/
----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [incubator-nuttx] btashton commented on a change in pull request #1677: Add Simulator and Drivers guides, and contributing instructions for new users
Posted by GitBox <gi...@apache.org>.
btashton commented on a change in pull request #1677:
URL: https://github.com/apache/incubator-nuttx/pull/1677#discussion_r480274417
##########
File path: Documentation/contributing/making-changes.rst
##########
@@ -0,0 +1,256 @@
+.. include:: /substitutions.rst
+.. _making-changes:
+
+Making Changes
+==============
+
+If you want to make changes to NuttX, for your own personal use, or to submit them back to project to improve NuttX,
+that's easy. For the purposes of this guide, you'll need a `GitHub <https://www.github.com>`_ account, since
+the Apache NuttX team uses GitHub. (You could also use git locally, or save your changes to other sites like
+`GitLab <https://about.gitlab.com/>`_ or `BitBucket <https://bitbucket.org>`_, but that's beyond the scope of this
+guide).
+
+Here's how to do it:
+
+#. Set your git user name and email
+
+ .. code-block:: bash
+
+ $ cd nuttx/
+ $ git config --global user.name "Your Name"
+ $ git config --global user.email "yourname@somedomaincom"
+
+#. Sign in to GitHub
+
+ If you don't have a `GitHub <https://www.github.com>`_ account, it's free to
+ sign up.
+ |br|
+ |br|
+
+
+#. Fork the Project
+
+ Visit both these links and hit the Fork button in the upper right of the page:
+
+ * `NuttX <https://github.com/apache/incubator-nuttx/>`_
+ * `NuttX Apps <https://github.com/apache/incubator-nuttx-apps/>`_
+
+
+#. Change the Git Remotes
+
+ The git repositories in your project are currently connected to the official NuttX repositories, but you don't
+ have permission to push software there. But you can push them to your forks, and from there create Pull Requests
+ if you want to send them to the NuttX project.
+
+ First, remove the current remote, ``origin`` (we'll add it back later):
+
+ .. code-block:: bash
+
+ $ cd nuttx/
+ $ # display the remote
+ $ git remote -v
+
+ You should see something like this:
+
+ .. code-block:: bash
+
+ origin https://github.com/apache/incubator-nuttx.git
+
+ Now, on the GitHub web page for your forked ``incubator-nuttx`` project, copy the clone url – get it by hitting the
+ green ``Clone or Download`` button in the upper right. Then do this:
+
+ .. code-block:: bash
+
+ $ git remote rm origin
+ $ git remote add origin <your forked incubator-nuttx project clone url>
+ $ git remote add upstream https://github.com/apache/incubator-nuttx.git
+
+ Do the same for your forked ``incubator-nuttx-apps`` project:
+
+ .. code-block:: bash
+
+ $ cd ../apps
+ $ git remote rm origin
+ $ git remote add origin <your forked incubator-nuttx-apps project clone url>
+ $ git remote add upstream https://github.com/apache/incubator-nuttx-apps.git
+
+
+#. Create a Local Git Branch
+
+ Now you can create local git branches and push them to GitHub:
+
+ .. code-block:: bash
+
+ $ git checkout -b test/my-new-branch
+ $ git push
+
+
+Git Workflow With an Upstream Repository
+----------------------------------------
+
+The main NuttX git repository is called an "upstream" repository - this is because it's the main source of truth, and
+its changes flow downstream to people who've forked that repository, like us.
+
+Working with an upstream repo is a bit more complex, but it's worth it since you can submit fixes and features
+to the main NuttX repos. One of the things you need to do regularly is keep your local repo in sync
+with the upstream. I work with a local branch, make changes, pull new software from the upstream and merge it in,
+maybe doing that several times. Then when everything works, I get my branch ready to do a Pull Request. Here's how:
+
+#. Fetch upstream changes and merge into my local master:
+
+ .. code-block:: bash
+
+ $ git checkout master
+ $ git fetch upstream
+ $ git merge upstream/master
+ $ git push
+
+#. Merge my local master with my local branch:
+
+ .. code-block:: bash
+
+ $ git checkout my-local-branch
+ $ git merge master
+ $ git push
Review comment:
> I said a range _from the HEAD_. I didn't mean that HEAD ~ N is a range. HEAD~N is the Nth commit behind HEAD.
> The current branch's top commit is HEAD.
> When you are "checkedout" to master and you do `git rebase -i master`, that means you are trying to rebase from HEAD to HEAD, thus the "noop".
No you are on your branch and interactive rebase against master. This will show all your commits in the interactive flow.
```
~/nuttx/nuttx on î‚ oldlinks
❯ git rebase -i master
pick e34173ab1e Docs: Update links to old website and wiki
pick af5b2d5cf7 nxstyle: Fix existing long line to match code style
# Rebase 6c227075e7..af5b2d5cf7 onto 6c227075e7 (2 commands)
Successfully rebased and updated refs/heads/oldlinks.
```
----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [incubator-nuttx] v01d commented on pull request #1677: Add Simulator and Drivers guides, and contributing instructions for new users
Posted by GitBox <gi...@apache.org>.
v01d commented on pull request #1677:
URL: https://github.com/apache/incubator-nuttx/pull/1677#issuecomment-687394808
> @v01d Re: the drivers section, it could be rewritten to be a general guide to developing on NuttX. As it is, there is a bunch of driver-specific advice in it. I'd like to leave as is for now, and it can be generalized in a future PR. Do you have objections to that?
I don't think it needs to be rewritten. I simple felt that the content is not specific to developing a driver. Consider that there are various kinds of drivers (character, block, "special"), each having its own requirement on how to implement them. That is what I have in mind when I mentioned to document how to write drivers. As the guide you wrote is more general than that and gives various advice that is also applicable to adding support for a new chip, for example, I think it is good to name it in a more general form.
----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [incubator-nuttx] Ouss4 commented on pull request #1677: Add Simulator and Drivers guides, and contributing instructions for new users
Posted by GitBox <gi...@apache.org>.
Ouss4 commented on pull request #1677:
URL: https://github.com/apache/incubator-nuttx/pull/1677#issuecomment-683859075
> > I'm not sure about the "Contributing" part. The first time we had a massive discussion around that. It was so big that the current workflow is still a draft. What to do with that?
>
> What Adam added I would say is mostly for newcomers to git. There's also the "Development Workflow" section that is closer to the intended workflow that should be followed by contributors. I think that brief document is good to have until the final workflow is defined. It mostly reflects what is already being done and don't want contributors to forget (check style, check license, etc.).
I agree that a short version is better for newcomers, we talked about this before. I was inclined to extract it from the development workflow. The git/github part is pretty complete.
I just wanted to note that we have some duplication here, with somewhat different workflow. (By different I mean different ways of doing the same thing with git)
----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [incubator-nuttx] btashton commented on a change in pull request #1677: Add Simulator and Drivers guides, and contributing instructions for new users
Posted by GitBox <gi...@apache.org>.
btashton commented on a change in pull request #1677:
URL: https://github.com/apache/incubator-nuttx/pull/1677#discussion_r480242716
##########
File path: Documentation/contributing/making-changes.rst
##########
@@ -0,0 +1,256 @@
+.. include:: /substitutions.rst
+.. _making-changes:
+
+Making Changes
+==============
+
+If you want to make changes to NuttX, for your own personal use, or to submit them back to project to improve NuttX,
+that's easy. For the purposes of this guide, you'll need a `GitHub <https://www.github.com>`_ account, since
+the Apache NuttX team uses GitHub. (You could also use git locally, or save your changes to other sites like
+`GitLab <https://about.gitlab.com/>`_ or `BitBucket <https://bitbucket.org>`_, but that's beyond the scope of this
+guide).
+
+Here's how to do it:
+
+#. Set your git user name and email
+
+ .. code-block:: bash
+
+ $ cd nuttx/
+ $ git config --global user.name "Your Name"
+ $ git config --global user.email "yourname@somedomaincom"
+
+#. Sign in to GitHub
+
+ If you don't have a `GitHub <https://www.github.com>`_ account, it's free to
+ sign up.
+ |br|
+ |br|
+
+
+#. Fork the Project
+
+ Visit both these links and hit the Fork button in the upper right of the page:
+
+ * `NuttX <https://github.com/apache/incubator-nuttx/>`_
+ * `NuttX Apps <https://github.com/apache/incubator-nuttx-apps/>`_
+
+
+#. Change the Git Remotes
+
+ The git repositories in your project are currently connected to the official NuttX repositories, but you don't
+ have permission to push software there. But you can push them to your forks, and from there create Pull Requests
+ if you want to send them to the NuttX project.
+
+ First, remove the current remote, ``origin`` (we'll add it back later):
+
+ .. code-block:: bash
+
+ $ cd nuttx/
+ $ # display the remote
+ $ git remote -v
+
+ You should see something like this:
+
+ .. code-block:: bash
+
+ origin https://github.com/apache/incubator-nuttx.git
+
+ Now, on the GitHub web page for your forked ``incubator-nuttx`` project, copy the clone url – get it by hitting the
+ green ``Clone or Download`` button in the upper right. Then do this:
+
+ .. code-block:: bash
+
+ $ git remote rm origin
+ $ git remote add origin <your forked incubator-nuttx project clone url>
+ $ git remote add upstream https://github.com/apache/incubator-nuttx.git
+
+ Do the same for your forked ``incubator-nuttx-apps`` project:
+
+ .. code-block:: bash
+
+ $ cd ../apps
+ $ git remote rm origin
+ $ git remote add origin <your forked incubator-nuttx-apps project clone url>
+ $ git remote add upstream https://github.com/apache/incubator-nuttx-apps.git
+
+
+#. Create a Local Git Branch
+
+ Now you can create local git branches and push them to GitHub:
+
+ .. code-block:: bash
+
+ $ git checkout -b test/my-new-branch
+ $ git push
+
+
+Git Workflow With an Upstream Repository
+----------------------------------------
+
+The main NuttX git repository is called an "upstream" repository - this is because it's the main source of truth, and
+its changes flow downstream to people who've forked that repository, like us.
+
+Working with an upstream repo is a bit more complex, but it's worth it since you can submit fixes and features
+to the main NuttX repos. One of the things you need to do regularly is keep your local repo in sync
+with the upstream. I work with a local branch, make changes, pull new software from the upstream and merge it in,
+maybe doing that several times. Then when everything works, I get my branch ready to do a Pull Request. Here's how:
+
+#. Fetch upstream changes and merge into my local master:
+
+ .. code-block:: bash
+
+ $ git checkout master
+ $ git fetch upstream
+ $ git merge upstream/master
+ $ git push
+
+#. Merge my local master with my local branch:
+
+ .. code-block:: bash
+
+ $ git checkout my-local-branch
+ $ git merge master
+ $ git push
Review comment:
Rebase is much better for this.
I was wondering why we show
`git rev-list` you can just supply the upstream branch to `git rebase`. We also list the super long form option for force. No one is going to type that.
----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [incubator-nuttx] Ouss4 commented on a change in pull request #1677: Add Simulator and Drivers guides, and contributing instructions for new users
Posted by GitBox <gi...@apache.org>.
Ouss4 commented on a change in pull request #1677:
URL: https://github.com/apache/incubator-nuttx/pull/1677#discussion_r480228124
##########
File path: Documentation/contributing/making-changes.rst
##########
@@ -0,0 +1,256 @@
+.. include:: /substitutions.rst
+.. _making-changes:
+
+Making Changes
+==============
+
+If you want to make changes to NuttX, for your own personal use, or to submit them back to project to improve NuttX,
+that's easy. For the purposes of this guide, you'll need a `GitHub <https://www.github.com>`_ account, since
+the Apache NuttX team uses GitHub. (You could also use git locally, or save your changes to other sites like
+`GitLab <https://about.gitlab.com/>`_ or `BitBucket <https://bitbucket.org>`_, but that's beyond the scope of this
+guide).
+
+Here's how to do it:
+
+#. Set your git user name and email
+
+ .. code-block:: bash
+
+ $ cd nuttx/
+ $ git config --global user.name "Your Name"
+ $ git config --global user.email "yourname@somedomaincom"
+
+#. Sign in to GitHub
+
+ If you don't have a `GitHub <https://www.github.com>`_ account, it's free to
+ sign up.
+ |br|
+ |br|
+
+
+#. Fork the Project
+
+ Visit both these links and hit the Fork button in the upper right of the page:
+
+ * `NuttX <https://github.com/apache/incubator-nuttx/>`_
+ * `NuttX Apps <https://github.com/apache/incubator-nuttx-apps/>`_
+
+
+#. Change the Git Remotes
+
+ The git repositories in your project are currently connected to the official NuttX repositories, but you don't
+ have permission to push software there. But you can push them to your forks, and from there create Pull Requests
+ if you want to send them to the NuttX project.
+
+ First, remove the current remote, ``origin`` (we'll add it back later):
+
+ .. code-block:: bash
+
+ $ cd nuttx/
+ $ # display the remote
+ $ git remote -v
+
+ You should see something like this:
+
+ .. code-block:: bash
+
+ origin https://github.com/apache/incubator-nuttx.git
+
+ Now, on the GitHub web page for your forked ``incubator-nuttx`` project, copy the clone url – get it by hitting the
+ green ``Clone or Download`` button in the upper right. Then do this:
+
+ .. code-block:: bash
+
+ $ git remote rm origin
+ $ git remote add origin <your forked incubator-nuttx project clone url>
+ $ git remote add upstream https://github.com/apache/incubator-nuttx.git
Review comment:
BTW, where is git clone mentioned? I can't find it.
> Also note, that there is set-url to change remote url.
and `git remove rename` to change the name of the remove and leave the url as is.
----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [incubator-nuttx] Ouss4 commented on a change in pull request #1677: Add Simulator and Drivers guides, and contributing instructions for new users
Posted by GitBox <gi...@apache.org>.
Ouss4 commented on a change in pull request #1677:
URL: https://github.com/apache/incubator-nuttx/pull/1677#discussion_r480238426
##########
File path: Documentation/contributing/making-changes.rst
##########
@@ -0,0 +1,256 @@
+.. include:: /substitutions.rst
+.. _making-changes:
+
+Making Changes
+==============
+
+If you want to make changes to NuttX, for your own personal use, or to submit them back to project to improve NuttX,
+that's easy. For the purposes of this guide, you'll need a `GitHub <https://www.github.com>`_ account, since
+the Apache NuttX team uses GitHub. (You could also use git locally, or save your changes to other sites like
+`GitLab <https://about.gitlab.com/>`_ or `BitBucket <https://bitbucket.org>`_, but that's beyond the scope of this
+guide).
+
+Here's how to do it:
+
+#. Set your git user name and email
+
+ .. code-block:: bash
+
+ $ cd nuttx/
+ $ git config --global user.name "Your Name"
+ $ git config --global user.email "yourname@somedomaincom"
+
+#. Sign in to GitHub
+
+ If you don't have a `GitHub <https://www.github.com>`_ account, it's free to
+ sign up.
+ |br|
+ |br|
+
+
+#. Fork the Project
+
+ Visit both these links and hit the Fork button in the upper right of the page:
+
+ * `NuttX <https://github.com/apache/incubator-nuttx/>`_
+ * `NuttX Apps <https://github.com/apache/incubator-nuttx-apps/>`_
+
+
+#. Change the Git Remotes
+
+ The git repositories in your project are currently connected to the official NuttX repositories, but you don't
+ have permission to push software there. But you can push them to your forks, and from there create Pull Requests
+ if you want to send them to the NuttX project.
+
+ First, remove the current remote, ``origin`` (we'll add it back later):
+
+ .. code-block:: bash
+
+ $ cd nuttx/
+ $ # display the remote
+ $ git remote -v
+
+ You should see something like this:
+
+ .. code-block:: bash
+
+ origin https://github.com/apache/incubator-nuttx.git
+
+ Now, on the GitHub web page for your forked ``incubator-nuttx`` project, copy the clone url – get it by hitting the
+ green ``Clone or Download`` button in the upper right. Then do this:
+
+ .. code-block:: bash
+
+ $ git remote rm origin
+ $ git remote add origin <your forked incubator-nuttx project clone url>
+ $ git remote add upstream https://github.com/apache/incubator-nuttx.git
+
+ Do the same for your forked ``incubator-nuttx-apps`` project:
+
+ .. code-block:: bash
+
+ $ cd ../apps
+ $ git remote rm origin
+ $ git remote add origin <your forked incubator-nuttx-apps project clone url>
+ $ git remote add upstream https://github.com/apache/incubator-nuttx-apps.git
+
+
+#. Create a Local Git Branch
+
+ Now you can create local git branches and push them to GitHub:
+
+ .. code-block:: bash
+
+ $ git checkout -b test/my-new-branch
+ $ git push
+
+
+Git Workflow With an Upstream Repository
+----------------------------------------
+
+The main NuttX git repository is called an "upstream" repository - this is because it's the main source of truth, and
+its changes flow downstream to people who've forked that repository, like us.
+
+Working with an upstream repo is a bit more complex, but it's worth it since you can submit fixes and features
+to the main NuttX repos. One of the things you need to do regularly is keep your local repo in sync
+with the upstream. I work with a local branch, make changes, pull new software from the upstream and merge it in,
+maybe doing that several times. Then when everything works, I get my branch ready to do a Pull Request. Here's how:
+
+#. Fetch upstream changes and merge into my local master:
+
+ .. code-block:: bash
+
+ $ git checkout master
+ $ git fetch upstream
+ $ git merge upstream/master
+ $ git push
+
+#. Merge my local master with my local branch:
+
+ .. code-block:: bash
+
+ $ git checkout my-local-branch
+ $ git merge master
+ $ git push
Review comment:
They are [here](https://cwiki.apache.org/confluence/display/NUTTX/Code+Contribution+Workflow#CodeContributionWorkflow-BeforeSubmittingYourChanges) with some explanation.
I can provide any other explanation if necessary.
----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [incubator-nuttx] adamfeuer commented on a change in pull request #1677: Add Simulator and Drivers guides, and contributing instructions for new users
Posted by GitBox <gi...@apache.org>.
adamfeuer commented on a change in pull request #1677:
URL: https://github.com/apache/incubator-nuttx/pull/1677#discussion_r483850466
##########
File path: Documentation/contributing/making-changes.rst
##########
@@ -0,0 +1,256 @@
+.. include:: /substitutions.rst
+.. _making-changes:
+
+Making Changes
+==============
+
+If you want to make changes to NuttX, for your own personal use, or to submit them back to project to improve NuttX,
+that's easy. For the purposes of this guide, you'll need a `GitHub <https://www.github.com>`_ account, since
+the Apache NuttX team uses GitHub. (You could also use git locally, or save your changes to other sites like
+`GitLab <https://about.gitlab.com/>`_ or `BitBucket <https://bitbucket.org>`_, but that's beyond the scope of this
+guide).
+
+Here's how to do it:
+
+#. Set your git user name and email
+
+ .. code-block:: bash
+
+ $ cd nuttx/
+ $ git config --global user.name "Your Name"
+ $ git config --global user.email "yourname@somedomaincom"
+
+#. Sign in to GitHub
+
+ If you don't have a `GitHub <https://www.github.com>`_ account, it's free to
+ sign up.
+ |br|
+ |br|
+
+
+#. Fork the Project
+
+ Visit both these links and hit the Fork button in the upper right of the page:
+
+ * `NuttX <https://github.com/apache/incubator-nuttx/>`_
+ * `NuttX Apps <https://github.com/apache/incubator-nuttx-apps/>`_
+
+
+#. Change the Git Remotes
+
+ The git repositories in your project are currently connected to the official NuttX repositories, but you don't
+ have permission to push software there. But you can push them to your forks, and from there create Pull Requests
+ if you want to send them to the NuttX project.
+
+ First, remove the current remote, ``origin`` (we'll add it back later):
+
+ .. code-block:: bash
+
+ $ cd nuttx/
+ $ # display the remote
+ $ git remote -v
+
+ You should see something like this:
+
+ .. code-block:: bash
+
+ origin https://github.com/apache/incubator-nuttx.git
+
+ Now, on the GitHub web page for your forked ``incubator-nuttx`` project, copy the clone url – get it by hitting the
+ green ``Clone or Download`` button in the upper right. Then do this:
+
+ .. code-block:: bash
+
+ $ git remote rm origin
+ $ git remote add origin <your forked incubator-nuttx project clone url>
+ $ git remote add upstream https://github.com/apache/incubator-nuttx.git
Review comment:
@Ouss4 @v01d The remotes instructions were this way because they came from some other docs that had you cloning the repos directly, without forking. I changed the instructions as you suggest, to fork, clone, and add the upstream repo.
----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [incubator-nuttx] adamfeuer commented on pull request #1677: Add Simulator and Drivers guides, and contributing instructions for new users
Posted by GitBox <gi...@apache.org>.
adamfeuer commented on pull request #1677:
URL: https://github.com/apache/incubator-nuttx/pull/1677#issuecomment-687415918
@v01d @btashton If this is good to merge – "good enough for now work-in-progress" let me know, and I will... uh... rebase and force push 🙂 🙂 🙂
Or if you have more improvements let me know that too.
----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [incubator-nuttx] adamfeuer commented on a change in pull request #1677: Add Simulator and Drivers guides, and contributing instructions for new users
Posted by GitBox <gi...@apache.org>.
adamfeuer commented on a change in pull request #1677:
URL: https://github.com/apache/incubator-nuttx/pull/1677#discussion_r483872860
##########
File path: Documentation/guides/drivers.rst
##########
@@ -0,0 +1,211 @@
+.. include:: /substitutions.rst
+.. _drivers:
+
+Drivers
+=======
+
+Some NuttX boards don't have full support for all the on-chip peripherals. If you need support for this hardware,
+you will either need to port a driver from another chip, or write one yourself. This section discusses how to do that.
+
+Porting a Driver
+----------------
+
+Often support for on-chip peripherals exists in a closely related chip, or even a different family or from a different
+manufacturer. Many chips are made up of different Intellectual Property (IP) blocks that are licensed from vendors like
+Cadence, Synopsys, and others. The IP blocks may be similar enough to use another chip's driver with little
+modification.
+
+* Find a similar driver in NuttX source code:
+
+ * Look at register names listed in the datasheet for the peripheral.
+ * Search the NuttX codebase for the register names (try several different ones).
+ * Note that you'll have to compare the datasheet to the header and code files to see if there are differences; there
+ will usually be some differences between architectures, and they can be significant.
+
+* Find a similar driver in U-Boot source code:
+
+ * Only for inspiration, you can't copy code because of license incompatibility.
+ * But you can debug to see how the driver works.
+ * `U-Boot <https://www.denx.de/wiki/U-Boot>`_ drivers are often easier to understand than BSD Unix drivers because
+ U-Boot is simpler.
+
+* Find a similar driver in Zephyr or BSD Unix (OpenBSD, FreeBSD, NetBSD):
+
+ * If you find one, you can borrow code directly (Apache 2.0 and BSD licenses are compatible).
Review comment:
@btashton I'll take this section out then. But then what good is having compatible open source licenses then? It seems like that negates a huge benefit of projects collaborating and exchanging code.
----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [incubator-nuttx] Ouss4 commented on a change in pull request #1677: Add Simulator and Drivers guides, and contributing instructions for new users
Posted by GitBox <gi...@apache.org>.
Ouss4 commented on a change in pull request #1677:
URL: https://github.com/apache/incubator-nuttx/pull/1677#discussion_r479991405
##########
File path: Documentation/contributing/making-changes.rst
##########
@@ -0,0 +1,256 @@
+.. include:: /substitutions.rst
+.. _making-changes:
+
+Making Changes
+==============
+
+If you want to make changes to NuttX, for your own personal use, or to submit them back to project to improve NuttX,
+that's easy. For the purposes of this guide, you'll need a `GitHub <https://www.github.com>`_ account, since
+the Apache NuttX team uses GitHub. (You could also use git locally, or save your changes to other sites like
+`GitLab <https://about.gitlab.com/>`_ or `BitBucket <https://bitbucket.org>`_, but that's beyond the scope of this
+guide).
+
+Here's how to do it:
+
+#. Set your git user name and email
+
+ .. code-block:: bash
+
+ $ cd nuttx/
+ $ git config --global user.name "Your Name"
+ $ git config --global user.email "yourname@somedomaincom"
+
+#. Sign in to GitHub
+
+ If you don't have a `GitHub <https://www.github.com>`_ account, it's free to
+ sign up.
+ |br|
+ |br|
+
+
+#. Fork the Project
+
+ Visit both these links and hit the Fork button in the upper right of the page:
+
+ * `NuttX <https://github.com/apache/incubator-nuttx/>`_
+ * `NuttX Apps <https://github.com/apache/incubator-nuttx-apps/>`_
+
+
+#. Change the Git Remotes
+
+ The git repositories in your project are currently connected to the official NuttX repositories, but you don't
+ have permission to push software there. But you can push them to your forks, and from there create Pull Requests
+ if you want to send them to the NuttX project.
+
+ First, remove the current remote, ``origin`` (we'll add it back later):
+
+ .. code-block:: bash
+
+ $ cd nuttx/
+ $ # display the remote
+ $ git remote -v
+
+ You should see something like this:
+
+ .. code-block:: bash
+
+ origin https://github.com/apache/incubator-nuttx.git
+
+ Now, on the GitHub web page for your forked ``incubator-nuttx`` project, copy the clone url – get it by hitting the
+ green ``Clone or Download`` button in the upper right. Then do this:
+
+ .. code-block:: bash
+
+ $ git remote rm origin
+ $ git remote add origin <your forked incubator-nuttx project clone url>
+ $ git remote add upstream https://github.com/apache/incubator-nuttx.git
+
+ Do the same for your forked ``incubator-nuttx-apps`` project:
+
+ .. code-block:: bash
+
+ $ cd ../apps
+ $ git remote rm origin
+ $ git remote add origin <your forked incubator-nuttx-apps project clone url>
+ $ git remote add upstream https://github.com/apache/incubator-nuttx-apps.git
+
+
+#. Create a Local Git Branch
+
+ Now you can create local git branches and push them to GitHub:
+
+ .. code-block:: bash
+
+ $ git checkout -b test/my-new-branch
+ $ git push
+
+
+Git Workflow With an Upstream Repository
+----------------------------------------
+
+The main NuttX git repository is called an "upstream" repository - this is because it's the main source of truth, and
+its changes flow downstream to people who've forked that repository, like us.
+
+Working with an upstream repo is a bit more complex, but it's worth it since you can submit fixes and features
+to the main NuttX repos. One of the things you need to do regularly is keep your local repo in sync
+with the upstream. I work with a local branch, make changes, pull new software from the upstream and merge it in,
+maybe doing that several times. Then when everything works, I get my branch ready to do a Pull Request. Here's how:
+
+#. Fetch upstream changes and merge into my local master:
+
+ .. code-block:: bash
+
+ $ git checkout master
+ $ git fetch upstream
+ $ git merge upstream/master
+ $ git push
+
+#. Merge my local master with my local branch:
+
+ .. code-block:: bash
+
+ $ git checkout my-local-branch
+ $ git merge master
+ $ git push
+
+#. Make changes and push them to my fork
+
+ .. code-block:: bash
+
+ $ vim my-file.c
+ $ git add my-file.c
+ $ git commit my-file.c
+ $ git push
+
+#. Repeat 1-3 as necessary
+
+#. Run the ``tools/checkpatch.sh`` script on your files
+
+ When your code runs, then you're almost ready to submit it. But first you need to check the code to ensure
+ that it conforms to the NuttX :ref:`contributing/coding_style:C Coding Standard`.
+ The ``tools/checkpatch.sh`` script will do that. Here's the usage info:
+
+ .. code-block:: bash
+
+ $ ./tools/checkpatch.sh -h
+ USAGE: ./tools/checkpatch.sh [options] [list|-]
+
+ Options:
+ -h
+ -c spell check with codespell(install with: pip install codespell
+ -r range check only (used with -p and -g)
+ -p <patch list> (default)
+ -g <commit list>
+ -f <file list>
+ - read standard input mainly used by git pre-commit hook as below:
+ git diff --cached | ./tools/checkpatch.sh -
+
+ Run it against your files and correct all the errors in the code you added, so that
+ ``tools/checkpatch.sh`` reports no errors. Then commit the result.
+ For example:
+
+ .. code-block:: bash
+
+ $ ./tools/checkpatch.sh -f my-file.c
+ arch/arm/src/sama5/hardware/my-file.c:876:82: warning: Long line found
+ $ # fix errors
+ $ vim my-file.c
+ $ # run again
+ $ ./tools/checkpatch.sh -f my-file.c
+
+ If you have made a lot of changes, you can also use this bash commandline to see the errors for all the changed C
+ files in your branch (assumes you are currently on the branch that has the changed files):
+
+ .. code-block:: bash
+
+ $ git diff --name-only master | egrep "\.c|\.h" | xargs echo | xargs ./tools/checkpatch.sh -f | less
+
+ Note that there are some bugs in the ``nxstyle`` program that ``checkpatch.sh`` uses, so
+ it may report a few errors that are not actually errors. The committers will help you
+ find these. (Or view the
+ `nxstyle Issues <https://github.com/apache/incubator-nuttx/issues?q=is%3Aissue+is%3Aopen+nxstyle>`_.)
+ |br|
+ |br|
+
+#. Commit the fixed files
+
+ .. code-block:: bash
+
+ $ git add my-file.c
+ $ git commit my-file.c
+ $ git push
+
+
+Submitting Your Changes to NuttX
+--------------------------------
+
+ Pull requests let you tell others about changes you've pushed to a branch in a repository on GitHub. Once a pull
+ request is opened, you can discuss and review the potential changes with collaborators and add follow-up commits
+ before your changes are merged into the base branch.
+
+ (from GitHub's `About pull requests <https://docs.github.com/en/github/collaborating-with-issues-and-pull-requests/about-pull-requests>`_ page)
+
+Before you do a Pull Request, the NuttX team will usually want all the changes you made in your branch "squashed" into
+a single commit, so that when they review your changes, there's a clean view of the history. If there are changes
+after Pull Request review feedback, they can be separate commits. Here's the easiest way I found to do that initial
+squash before submitting the Pull Request:
+
+#. Check out my branch
+
+ .. code-block:: bash
+
+ $ git checkout my-branch
+
+#. Rename it to ``my-branch-old`` to save it, because we're going to create new clean branch to push:
+
+ .. code-block:: bash
+
+ $ git branch -m my-branch-old
Review comment:
I think interactive rebasing is a better practice to achieve same.
----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [incubator-nuttx] Ouss4 commented on a change in pull request #1677: Add Simulator and Drivers guides, and contributing instructions for new users
Posted by GitBox <gi...@apache.org>.
Ouss4 commented on a change in pull request #1677:
URL: https://github.com/apache/incubator-nuttx/pull/1677#discussion_r480269447
##########
File path: Documentation/contributing/making-changes.rst
##########
@@ -0,0 +1,256 @@
+.. include:: /substitutions.rst
+.. _making-changes:
+
+Making Changes
+==============
+
+If you want to make changes to NuttX, for your own personal use, or to submit them back to project to improve NuttX,
+that's easy. For the purposes of this guide, you'll need a `GitHub <https://www.github.com>`_ account, since
+the Apache NuttX team uses GitHub. (You could also use git locally, or save your changes to other sites like
+`GitLab <https://about.gitlab.com/>`_ or `BitBucket <https://bitbucket.org>`_, but that's beyond the scope of this
+guide).
+
+Here's how to do it:
+
+#. Set your git user name and email
+
+ .. code-block:: bash
+
+ $ cd nuttx/
+ $ git config --global user.name "Your Name"
+ $ git config --global user.email "yourname@somedomaincom"
+
+#. Sign in to GitHub
+
+ If you don't have a `GitHub <https://www.github.com>`_ account, it's free to
+ sign up.
+ |br|
+ |br|
+
+
+#. Fork the Project
+
+ Visit both these links and hit the Fork button in the upper right of the page:
+
+ * `NuttX <https://github.com/apache/incubator-nuttx/>`_
+ * `NuttX Apps <https://github.com/apache/incubator-nuttx-apps/>`_
+
+
+#. Change the Git Remotes
+
+ The git repositories in your project are currently connected to the official NuttX repositories, but you don't
+ have permission to push software there. But you can push them to your forks, and from there create Pull Requests
+ if you want to send them to the NuttX project.
+
+ First, remove the current remote, ``origin`` (we'll add it back later):
+
+ .. code-block:: bash
+
+ $ cd nuttx/
+ $ # display the remote
+ $ git remote -v
+
+ You should see something like this:
+
+ .. code-block:: bash
+
+ origin https://github.com/apache/incubator-nuttx.git
+
+ Now, on the GitHub web page for your forked ``incubator-nuttx`` project, copy the clone url – get it by hitting the
+ green ``Clone or Download`` button in the upper right. Then do this:
+
+ .. code-block:: bash
+
+ $ git remote rm origin
+ $ git remote add origin <your forked incubator-nuttx project clone url>
+ $ git remote add upstream https://github.com/apache/incubator-nuttx.git
+
+ Do the same for your forked ``incubator-nuttx-apps`` project:
+
+ .. code-block:: bash
+
+ $ cd ../apps
+ $ git remote rm origin
+ $ git remote add origin <your forked incubator-nuttx-apps project clone url>
+ $ git remote add upstream https://github.com/apache/incubator-nuttx-apps.git
+
+
+#. Create a Local Git Branch
+
+ Now you can create local git branches and push them to GitHub:
+
+ .. code-block:: bash
+
+ $ git checkout -b test/my-new-branch
+ $ git push
+
+
+Git Workflow With an Upstream Repository
+----------------------------------------
+
+The main NuttX git repository is called an "upstream" repository - this is because it's the main source of truth, and
+its changes flow downstream to people who've forked that repository, like us.
+
+Working with an upstream repo is a bit more complex, but it's worth it since you can submit fixes and features
+to the main NuttX repos. One of the things you need to do regularly is keep your local repo in sync
+with the upstream. I work with a local branch, make changes, pull new software from the upstream and merge it in,
+maybe doing that several times. Then when everything works, I get my branch ready to do a Pull Request. Here's how:
+
+#. Fetch upstream changes and merge into my local master:
+
+ .. code-block:: bash
+
+ $ git checkout master
+ $ git fetch upstream
+ $ git merge upstream/master
+ $ git push
+
+#. Merge my local master with my local branch:
+
+ .. code-block:: bash
+
+ $ git checkout my-local-branch
+ $ git merge master
+ $ git push
Review comment:
I think we are not talking about the same thing.
For the "just" rebase part, we agree. You just supply the branch name. You rebase one branch ontop of the other.
Interactive rebasing is used to change commits within the same branch. In the doc's example (here or in Confluence) is used to squash some commits. It can also be used to delete, change or re-word (change description of) commits.
To do so, we need a range of commits from the HEAD of the branch, thus the HEAD~N.
----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [incubator-nuttx] btashton commented on a change in pull request #1677: Add Simulator and Drivers guides, and contributing instructions for new users
Posted by GitBox <gi...@apache.org>.
btashton commented on a change in pull request #1677:
URL: https://github.com/apache/incubator-nuttx/pull/1677#discussion_r483862842
##########
File path: Documentation/guides/drivers.rst
##########
@@ -0,0 +1,211 @@
+.. include:: /substitutions.rst
+.. _drivers:
+
+Drivers
+=======
+
+Some NuttX boards don't have full support for all the on-chip peripherals. If you need support for this hardware,
+you will either need to port a driver from another chip, or write one yourself. This section discusses how to do that.
+
+Porting a Driver
+----------------
+
+Often support for on-chip peripherals exists in a closely related chip, or even a different family or from a different
+manufacturer. Many chips are made up of different Intellectual Property (IP) blocks that are licensed from vendors like
+Cadence, Synopsys, and others. The IP blocks may be similar enough to use another chip's driver with little
+modification.
+
+* Find a similar driver in NuttX source code:
+
+ * Look at register names listed in the datasheet for the peripheral.
+ * Search the NuttX codebase for the register names (try several different ones).
+ * Note that you'll have to compare the datasheet to the header and code files to see if there are differences; there
+ will usually be some differences between architectures, and they can be significant.
+
+* Find a similar driver in U-Boot source code:
+
+ * Only for inspiration, you can't copy code because of license incompatibility.
+ * But you can debug to see how the driver works.
+ * `U-Boot <https://www.denx.de/wiki/U-Boot>`_ drivers are often easier to understand than BSD Unix drivers because
+ U-Boot is simpler.
+
+* Find a similar driver in Zephyr or BSD Unix (OpenBSD, FreeBSD, NetBSD):
+
+ * If you find one, you can borrow code directly (Apache 2.0 and BSD licenses are compatible).
Review comment:
I think we are trying to keep all 3rd party code out.
----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [incubator-nuttx] v01d commented on a change in pull request #1677: Add Simulator and Drivers guides, and contributing instructions for new users
Posted by GitBox <gi...@apache.org>.
v01d commented on a change in pull request #1677:
URL: https://github.com/apache/incubator-nuttx/pull/1677#discussion_r480250263
##########
File path: Documentation/contributing/making-changes.rst
##########
@@ -0,0 +1,256 @@
+.. include:: /substitutions.rst
+.. _making-changes:
+
+Making Changes
+==============
+
+If you want to make changes to NuttX, for your own personal use, or to submit them back to project to improve NuttX,
+that's easy. For the purposes of this guide, you'll need a `GitHub <https://www.github.com>`_ account, since
+the Apache NuttX team uses GitHub. (You could also use git locally, or save your changes to other sites like
+`GitLab <https://about.gitlab.com/>`_ or `BitBucket <https://bitbucket.org>`_, but that's beyond the scope of this
+guide).
+
+Here's how to do it:
+
+#. Set your git user name and email
+
+ .. code-block:: bash
+
+ $ cd nuttx/
+ $ git config --global user.name "Your Name"
+ $ git config --global user.email "yourname@somedomaincom"
+
+#. Sign in to GitHub
+
+ If you don't have a `GitHub <https://www.github.com>`_ account, it's free to
+ sign up.
+ |br|
+ |br|
+
+
+#. Fork the Project
+
+ Visit both these links and hit the Fork button in the upper right of the page:
+
+ * `NuttX <https://github.com/apache/incubator-nuttx/>`_
+ * `NuttX Apps <https://github.com/apache/incubator-nuttx-apps/>`_
+
+
+#. Change the Git Remotes
+
+ The git repositories in your project are currently connected to the official NuttX repositories, but you don't
+ have permission to push software there. But you can push them to your forks, and from there create Pull Requests
+ if you want to send them to the NuttX project.
+
+ First, remove the current remote, ``origin`` (we'll add it back later):
+
+ .. code-block:: bash
+
+ $ cd nuttx/
+ $ # display the remote
+ $ git remote -v
+
+ You should see something like this:
+
+ .. code-block:: bash
+
+ origin https://github.com/apache/incubator-nuttx.git
+
+ Now, on the GitHub web page for your forked ``incubator-nuttx`` project, copy the clone url – get it by hitting the
+ green ``Clone or Download`` button in the upper right. Then do this:
+
+ .. code-block:: bash
+
+ $ git remote rm origin
+ $ git remote add origin <your forked incubator-nuttx project clone url>
+ $ git remote add upstream https://github.com/apache/incubator-nuttx.git
+
+ Do the same for your forked ``incubator-nuttx-apps`` project:
+
+ .. code-block:: bash
+
+ $ cd ../apps
+ $ git remote rm origin
+ $ git remote add origin <your forked incubator-nuttx-apps project clone url>
+ $ git remote add upstream https://github.com/apache/incubator-nuttx-apps.git
+
+
+#. Create a Local Git Branch
+
+ Now you can create local git branches and push them to GitHub:
+
+ .. code-block:: bash
+
+ $ git checkout -b test/my-new-branch
+ $ git push
+
+
+Git Workflow With an Upstream Repository
+----------------------------------------
+
+The main NuttX git repository is called an "upstream" repository - this is because it's the main source of truth, and
+its changes flow downstream to people who've forked that repository, like us.
+
+Working with an upstream repo is a bit more complex, but it's worth it since you can submit fixes and features
+to the main NuttX repos. One of the things you need to do regularly is keep your local repo in sync
+with the upstream. I work with a local branch, make changes, pull new software from the upstream and merge it in,
+maybe doing that several times. Then when everything works, I get my branch ready to do a Pull Request. Here's how:
+
+#. Fetch upstream changes and merge into my local master:
+
+ .. code-block:: bash
+
+ $ git checkout master
+ $ git fetch upstream
+ $ git merge upstream/master
+ $ git push
+
+#. Merge my local master with my local branch:
+
+ .. code-block:: bash
+
+ $ git checkout my-local-branch
+ $ git merge master
+ $ git push
Review comment:
While this is not something for external contributors, but for maintainers (I think having a separate maintainers guide would be good later), I have this set for my nuttx repos:
<pre>
❯ git remote -v
fork git@github.com:v01d/incubator-nuttx (fetch)
fork git@github.com:v01d/incubator-nuttx (push)
origin https://github.com/apache/incubator-nuttx (fetch)
origin no_push (push)
</pre>
(note origin in my case is upstream)
----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [incubator-nuttx] v01d commented on a change in pull request #1677: Add Simulator and Drivers guides, and contributing instructions for new users
Posted by GitBox <gi...@apache.org>.
v01d commented on a change in pull request #1677:
URL: https://github.com/apache/incubator-nuttx/pull/1677#discussion_r480191281
##########
File path: Documentation/contributing/making-changes.rst
##########
@@ -0,0 +1,256 @@
+.. include:: /substitutions.rst
+.. _making-changes:
+
+Making Changes
Review comment:
Maybe this should be called "Git Primer" or something similar?
----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [incubator-nuttx] v01d commented on pull request #1677: Add Simulator and Drivers guides, and contributing instructions for new users
Posted by GitBox <gi...@apache.org>.
v01d commented on pull request #1677:
URL: https://github.com/apache/incubator-nuttx/pull/1677#issuecomment-683821003
> I'm not sure about the "Contributing" part. The first time we had a massive discussion around that. It was so big that the current workflow is still a draft. What to do with that?
What Adam added I would say is mostly for newcomers to git. There's also the "Development Workflow" section that is closer to the intended workflow that should be followed by contributors. I think that brief document is good to have until the final workflow is defined. It mostly reflects what is already being done and don't want contributors to forget (check style, check license, etc.).
----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [incubator-nuttx] adamfeuer commented on a change in pull request #1677: Add Simulator and Drivers guides, and contributing instructions for new users
Posted by GitBox <gi...@apache.org>.
adamfeuer commented on a change in pull request #1677:
URL: https://github.com/apache/incubator-nuttx/pull/1677#discussion_r483830685
##########
File path: Documentation/contributing/making-changes.rst
##########
@@ -0,0 +1,256 @@
+.. include:: /substitutions.rst
+.. _making-changes:
+
+Making Changes
Review comment:
@v01d What about "Making Changes Using Git"? I just want to make sure people know this is about tracking the changes they make.
##########
File path: Documentation/guides/simulator.rst
##########
@@ -0,0 +1,145 @@
+.. include:: /substitutions.rst
+.. _simulator:
+
+Simulator
+=========
+
+Apache NuttX has a simulator that can run as a regular program on Linux, Mac, and Windows computers.
+It's useful for debugging operating system features that aren't associated with particular
+device drivers— for instance the TCP/IP stack itself, a web interface or API for your
+application, or other communication protocols. It's also handy for trying out Apache NuttX without
+having a piece of embedded hardware.
+
+This guide assumes you're on Linux. It works on Windows and Mac too— if you know how,
+submit a PR the NuttX Companion to update this guide!
Review comment:
@v01d will fix
----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [incubator-nuttx] adamfeuer commented on a change in pull request #1677: Add Simulator and Drivers guides, and contributing instructions for new users
Posted by GitBox <gi...@apache.org>.
adamfeuer commented on a change in pull request #1677:
URL: https://github.com/apache/incubator-nuttx/pull/1677#discussion_r483826664
##########
File path: Documentation/contributing/making-changes.rst
##########
@@ -0,0 +1,256 @@
+.. include:: /substitutions.rst
+.. _making-changes:
+
+Making Changes
+==============
+
+If you want to make changes to NuttX, for your own personal use, or to submit them back to project to improve NuttX,
+that's easy. For the purposes of this guide, you'll need a `GitHub <https://www.github.com>`_ account, since
+the Apache NuttX team uses GitHub. (You could also use git locally, or save your changes to other sites like
+`GitLab <https://about.gitlab.com/>`_ or `BitBucket <https://bitbucket.org>`_, but that's beyond the scope of this
+guide).
+
+Here's how to do it:
+
+#. Set your git user name and email
+
+ .. code-block:: bash
+
+ $ cd nuttx/
+ $ git config --global user.name "Your Name"
+ $ git config --global user.email "yourname@somedomaincom"
+
+#. Sign in to GitHub
+
+ If you don't have a `GitHub <https://www.github.com>`_ account, it's free to
+ sign up.
+ |br|
+ |br|
+
+
+#. Fork the Project
+
+ Visit both these links and hit the Fork button in the upper right of the page:
+
+ * `NuttX <https://github.com/apache/incubator-nuttx/>`_
+ * `NuttX Apps <https://github.com/apache/incubator-nuttx-apps/>`_
+
+
+#. Change the Git Remotes
+
+ The git repositories in your project are currently connected to the official NuttX repositories, but you don't
+ have permission to push software there. But you can push them to your forks, and from there create Pull Requests
+ if you want to send them to the NuttX project.
+
+ First, remove the current remote, ``origin`` (we'll add it back later):
+
+ .. code-block:: bash
+
+ $ cd nuttx/
+ $ # display the remote
+ $ git remote -v
+
+ You should see something like this:
+
+ .. code-block:: bash
+
+ origin https://github.com/apache/incubator-nuttx.git
+
+ Now, on the GitHub web page for your forked ``incubator-nuttx`` project, copy the clone url – get it by hitting the
+ green ``Clone or Download`` button in the upper right. Then do this:
+
+ .. code-block:: bash
+
+ $ git remote rm origin
+ $ git remote add origin <your forked incubator-nuttx project clone url>
+ $ git remote add upstream https://github.com/apache/incubator-nuttx.git
+
+ Do the same for your forked ``incubator-nuttx-apps`` project:
+
+ .. code-block:: bash
+
+ $ cd ../apps
+ $ git remote rm origin
+ $ git remote add origin <your forked incubator-nuttx-apps project clone url>
+ $ git remote add upstream https://github.com/apache/incubator-nuttx-apps.git
+
+
+#. Create a Local Git Branch
+
+ Now you can create local git branches and push them to GitHub:
+
+ .. code-block:: bash
+
+ $ git checkout -b test/my-new-branch
+ $ git push
+
+
+Git Workflow With an Upstream Repository
+----------------------------------------
+
+The main NuttX git repository is called an "upstream" repository - this is because it's the main source of truth, and
+its changes flow downstream to people who've forked that repository, like us.
+
+Working with an upstream repo is a bit more complex, but it's worth it since you can submit fixes and features
+to the main NuttX repos. One of the things you need to do regularly is keep your local repo in sync
+with the upstream. I work with a local branch, make changes, pull new software from the upstream and merge it in,
+maybe doing that several times. Then when everything works, I get my branch ready to do a Pull Request. Here's how:
+
+#. Fetch upstream changes and merge into my local master:
+
+ .. code-block:: bash
+
+ $ git checkout master
+ $ git fetch upstream
+ $ git merge upstream/master
+ $ git push
+
+#. Merge my local master with my local branch:
+
+ .. code-block:: bash
+
+ $ git checkout my-local-branch
+ $ git merge master
+ $ git push
+
+#. Make changes and push them to my fork
+
+ .. code-block:: bash
+
+ $ vim my-file.c
+ $ git add my-file.c
+ $ git commit my-file.c
+ $ git push
+
+#. Repeat 1-3 as necessary
+
+#. Run the ``tools/checkpatch.sh`` script on your files
+
+ When your code runs, then you're almost ready to submit it. But first you need to check the code to ensure
+ that it conforms to the NuttX :ref:`contributing/coding_style:C Coding Standard`.
+ The ``tools/checkpatch.sh`` script will do that. Here's the usage info:
+
+ .. code-block:: bash
+
+ $ ./tools/checkpatch.sh -h
+ USAGE: ./tools/checkpatch.sh [options] [list|-]
+
+ Options:
+ -h
+ -c spell check with codespell(install with: pip install codespell
+ -r range check only (used with -p and -g)
+ -p <patch list> (default)
+ -g <commit list>
+ -f <file list>
+ - read standard input mainly used by git pre-commit hook as below:
+ git diff --cached | ./tools/checkpatch.sh -
+
+ Run it against your files and correct all the errors in the code you added, so that
+ ``tools/checkpatch.sh`` reports no errors. Then commit the result.
+ For example:
+
+ .. code-block:: bash
+
+ $ ./tools/checkpatch.sh -f my-file.c
+ arch/arm/src/sama5/hardware/my-file.c:876:82: warning: Long line found
+ $ # fix errors
+ $ vim my-file.c
+ $ # run again
+ $ ./tools/checkpatch.sh -f my-file.c
+
+ If you have made a lot of changes, you can also use this bash commandline to see the errors for all the changed C
+ files in your branch (assumes you are currently on the branch that has the changed files):
+
+ .. code-block:: bash
+
+ $ git diff --name-only master | egrep "\.c|\.h" | xargs echo | xargs ./tools/checkpatch.sh -f | less
+
+ Note that there are some bugs in the ``nxstyle`` program that ``checkpatch.sh`` uses, so
+ it may report a few errors that are not actually errors. The committers will help you
+ find these. (Or view the
+ `nxstyle Issues <https://github.com/apache/incubator-nuttx/issues?q=is%3Aissue+is%3Aopen+nxstyle>`_.)
+ |br|
+ |br|
+
+#. Commit the fixed files
+
+ .. code-block:: bash
+
+ $ git add my-file.c
+ $ git commit my-file.c
+ $ git push
+
+
+Submitting Your Changes to NuttX
+--------------------------------
+
+ Pull requests let you tell others about changes you've pushed to a branch in a repository on GitHub. Once a pull
+ request is opened, you can discuss and review the potential changes with collaborators and add follow-up commits
+ before your changes are merged into the base branch.
+
+ (from GitHub's `About pull requests <https://docs.github.com/en/github/collaborating-with-issues-and-pull-requests/about-pull-requests>`_ page)
+
+Before you do a Pull Request, the NuttX team will usually want all the changes you made in your branch "squashed" into
+a single commit, so that when they review your changes, there's a clean view of the history. If there are changes
+after Pull Request review feedback, they can be separate commits. Here's the easiest way I found to do that initial
+squash before submitting the Pull Request:
+
+#. Check out my branch
+
+ .. code-block:: bash
+
+ $ git checkout my-branch
+
+#. Rename it to ``my-branch-old`` to save it, because we're going to create new clean branch to push:
+
+ .. code-block:: bash
+
+ $ git branch -m my-branch-old
+
+#. Create a new clean branch with the same name you were using before the last step:
+
+ .. code-block:: bash
+
+ $ git checkout master
+ $ git checkout -b my-branch
+
+#. Merge your saved old branch into the new one, telling git to "squash" all your commits into one (note this will
+ not commit the result; the changed files will be in your staging area, ready to be committed):
+
+ .. code-block:: bash
+
+ $ git merge --squash my-branch-old
+
+#. Commit the result
+
+ .. code-block:: bash
+
+ $ git commit
+
+#. Force-push your new clean branch to the remote— this will overwrite all your previous changes in that branch:
+
+ .. code-block:: bash
+
+ $ git push -f --set-upstream origin my-branch
+
+#. Create a GitHub Pull Request
+
+ A Pull Request is how you ask your upstream to review and merge your changes.
+
+ Here's `GitHub's instructions for creating a Pull Request <https://help.github.com/en/github/collaborating-with-issues-and-pull-requests/creating-a-pull-request>`_.
+
+ |br|
+
+#. Get Pull Request feedback and implement changes
+
+ Get suggestions for improvements from reviewers, make changes, and push them to the branch. Once the reviewers are
+ happy, they may suggest squashing and merging again to make a single commit. In this case you would repeat steps
+ 1 through 6.
+
+Git Resources
+-------------
+
+* `Git Cheat Sheet (by GitHub) <https://github.github.com/training-kit/downloads/github-git-cheat-sheet.pdf>`_
+* `Git Book (online) <https://git-scm.com/book/en/v2>`_
+* `NuttX Code Contribution Workflow <https://cwiki.apache.org/confluence/display/NUTTX/Code+Contribution+Workflow>`_ –
Review comment:
@v01d I'd like to leave this here, so that people can see the full workflow that the developers are using. It's just a link for people to get more detail. Do you have objections to that?
----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [incubator-nuttx] v01d commented on pull request #1677: Add Simulator and Drivers guides, and contributing instructions for new users
Posted by GitBox <gi...@apache.org>.
v01d commented on pull request #1677:
URL: https://github.com/apache/incubator-nuttx/pull/1677#issuecomment-683842087
This looks good Adam. I only have two general comments:
* the "drivers" document reads more like a general guide for developing NuttX than working specifically on a driver. I had in mind to eventually have a guideline for how to write the different kinds of drivers somewhere. So I believe this document could be better named something like "Tips for working on NuttX" or similar (maybe you think of a better name).
----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [incubator-nuttx] btashton commented on a change in pull request #1677: Add Simulator and Drivers guides, and contributing instructions for new users
Posted by GitBox <gi...@apache.org>.
btashton commented on a change in pull request #1677:
URL: https://github.com/apache/incubator-nuttx/pull/1677#discussion_r483854655
##########
File path: Documentation/contributing/making-changes.rst
##########
@@ -0,0 +1,256 @@
+.. include:: /substitutions.rst
+.. _making-changes:
+
+Making Changes
+==============
+
+If you want to make changes to NuttX, for your own personal use, or to submit them back to project to improve NuttX,
+that's easy. For the purposes of this guide, you'll need a `GitHub <https://www.github.com>`_ account, since
+the Apache NuttX team uses GitHub. (You could also use git locally, or save your changes to other sites like
+`GitLab <https://about.gitlab.com/>`_ or `BitBucket <https://bitbucket.org>`_, but that's beyond the scope of this
+guide).
+
+Here's how to do it:
+
+#. Set your git user name and email
+
+ .. code-block:: bash
+
+ $ cd nuttx/
+ $ git config --global user.name "Your Name"
+ $ git config --global user.email "yourname@somedomaincom"
+
+#. Sign in to GitHub
+
+ If you don't have a `GitHub <https://www.github.com>`_ account, it's free to
+ sign up.
+ |br|
+ |br|
+
+
+#. Fork the Project
+
+ Visit both these links and hit the Fork button in the upper right of the page:
+
+ * `NuttX <https://github.com/apache/incubator-nuttx/>`_
+ * `NuttX Apps <https://github.com/apache/incubator-nuttx-apps/>`_
+
+
+#. Change the Git Remotes
+
+ The git repositories in your project are currently connected to the official NuttX repositories, but you don't
+ have permission to push software there. But you can push them to your forks, and from there create Pull Requests
+ if you want to send them to the NuttX project.
+
+ First, remove the current remote, ``origin`` (we'll add it back later):
+
+ .. code-block:: bash
+
+ $ cd nuttx/
+ $ # display the remote
+ $ git remote -v
+
+ You should see something like this:
+
+ .. code-block:: bash
+
+ origin https://github.com/apache/incubator-nuttx.git
+
+ Now, on the GitHub web page for your forked ``incubator-nuttx`` project, copy the clone url – get it by hitting the
+ green ``Clone or Download`` button in the upper right. Then do this:
+
+ .. code-block:: bash
+
+ $ git remote rm origin
+ $ git remote add origin <your forked incubator-nuttx project clone url>
+ $ git remote add upstream https://github.com/apache/incubator-nuttx.git
+
+ Do the same for your forked ``incubator-nuttx-apps`` project:
+
+ .. code-block:: bash
+
+ $ cd ../apps
+ $ git remote rm origin
+ $ git remote add origin <your forked incubator-nuttx-apps project clone url>
+ $ git remote add upstream https://github.com/apache/incubator-nuttx-apps.git
+
+
+#. Create a Local Git Branch
+
+ Now you can create local git branches and push them to GitHub:
+
+ .. code-block:: bash
+
+ $ git checkout -b test/my-new-branch
+ $ git push
+
+
+Git Workflow With an Upstream Repository
+----------------------------------------
+
+The main NuttX git repository is called an "upstream" repository - this is because it's the main source of truth, and
+its changes flow downstream to people who've forked that repository, like us.
+
+Working with an upstream repo is a bit more complex, but it's worth it since you can submit fixes and features
+to the main NuttX repos. One of the things you need to do regularly is keep your local repo in sync
+with the upstream. I work with a local branch, make changes, pull new software from the upstream and merge it in,
+maybe doing that several times. Then when everything works, I get my branch ready to do a Pull Request. Here's how:
+
+#. Fetch upstream changes and merge into my local master:
+
+ .. code-block:: bash
+
+ $ git checkout master
+ $ git fetch upstream
+ $ git merge upstream/master
+ $ git push
+
+#. Merge my local master with my local branch:
+
+ .. code-block:: bash
+
+ $ git checkout my-local-branch
+ $ git merge master
+ $ git push
Review comment:
I would like to drop it because we get people doing the merge where there might have been a change causing a merge commit and have to ask them to rebase.
Rebase is also the system that the CI system uses for a "merge" so it would be best to keep inline with that.
----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [incubator-nuttx] v01d commented on a change in pull request #1677: Add Simulator and Drivers guides, and contributing instructions for new users
Posted by GitBox <gi...@apache.org>.
v01d commented on a change in pull request #1677:
URL: https://github.com/apache/incubator-nuttx/pull/1677#discussion_r480275112
##########
File path: Documentation/contributing/making-changes.rst
##########
@@ -0,0 +1,256 @@
+.. include:: /substitutions.rst
+.. _making-changes:
+
+Making Changes
+==============
+
+If you want to make changes to NuttX, for your own personal use, or to submit them back to project to improve NuttX,
+that's easy. For the purposes of this guide, you'll need a `GitHub <https://www.github.com>`_ account, since
+the Apache NuttX team uses GitHub. (You could also use git locally, or save your changes to other sites like
+`GitLab <https://about.gitlab.com/>`_ or `BitBucket <https://bitbucket.org>`_, but that's beyond the scope of this
+guide).
+
+Here's how to do it:
+
+#. Set your git user name and email
+
+ .. code-block:: bash
+
+ $ cd nuttx/
+ $ git config --global user.name "Your Name"
+ $ git config --global user.email "yourname@somedomaincom"
+
+#. Sign in to GitHub
+
+ If you don't have a `GitHub <https://www.github.com>`_ account, it's free to
+ sign up.
+ |br|
+ |br|
+
+
+#. Fork the Project
+
+ Visit both these links and hit the Fork button in the upper right of the page:
+
+ * `NuttX <https://github.com/apache/incubator-nuttx/>`_
+ * `NuttX Apps <https://github.com/apache/incubator-nuttx-apps/>`_
+
+
+#. Change the Git Remotes
+
+ The git repositories in your project are currently connected to the official NuttX repositories, but you don't
+ have permission to push software there. But you can push them to your forks, and from there create Pull Requests
+ if you want to send them to the NuttX project.
+
+ First, remove the current remote, ``origin`` (we'll add it back later):
+
+ .. code-block:: bash
+
+ $ cd nuttx/
+ $ # display the remote
+ $ git remote -v
+
+ You should see something like this:
+
+ .. code-block:: bash
+
+ origin https://github.com/apache/incubator-nuttx.git
+
+ Now, on the GitHub web page for your forked ``incubator-nuttx`` project, copy the clone url – get it by hitting the
+ green ``Clone or Download`` button in the upper right. Then do this:
+
+ .. code-block:: bash
+
+ $ git remote rm origin
+ $ git remote add origin <your forked incubator-nuttx project clone url>
+ $ git remote add upstream https://github.com/apache/incubator-nuttx.git
+
+ Do the same for your forked ``incubator-nuttx-apps`` project:
+
+ .. code-block:: bash
+
+ $ cd ../apps
+ $ git remote rm origin
+ $ git remote add origin <your forked incubator-nuttx-apps project clone url>
+ $ git remote add upstream https://github.com/apache/incubator-nuttx-apps.git
+
+
+#. Create a Local Git Branch
+
+ Now you can create local git branches and push them to GitHub:
+
+ .. code-block:: bash
+
+ $ git checkout -b test/my-new-branch
+ $ git push
+
+
+Git Workflow With an Upstream Repository
+----------------------------------------
+
+The main NuttX git repository is called an "upstream" repository - this is because it's the main source of truth, and
+its changes flow downstream to people who've forked that repository, like us.
+
+Working with an upstream repo is a bit more complex, but it's worth it since you can submit fixes and features
+to the main NuttX repos. One of the things you need to do regularly is keep your local repo in sync
+with the upstream. I work with a local branch, make changes, pull new software from the upstream and merge it in,
+maybe doing that several times. Then when everything works, I get my branch ready to do a Pull Request. Here's how:
+
+#. Fetch upstream changes and merge into my local master:
+
+ .. code-block:: bash
+
+ $ git checkout master
+ $ git fetch upstream
+ $ git merge upstream/master
+ $ git push
+
+#. Merge my local master with my local branch:
+
+ .. code-block:: bash
+
+ $ git checkout my-local-branch
+ $ git merge master
+ $ git push
Review comment:
> I said a range _from the HEAD_. I didn't mean that HEAD ~ N is a range. HEAD~N is the Nth commit behind HEAD.
> The current branch's top commit is HEAD.
> When you are "checkedout" to master and you do `git rebase -i master`, that means you are trying to rebase from HEAD to HEAD, thus the "noop".
I understand, but the instructions are for a feature branch, not for master. So master is assumed to be the branch point of the feature branch. There shouldn't be any work on master on NuttX (much less any rebasing)
----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [incubator-nuttx] v01d edited a comment on pull request #1677: Add Simulator and Drivers guides, and contributing instructions for new users
Posted by GitBox <gi...@apache.org>.
v01d edited a comment on pull request #1677:
URL: https://github.com/apache/incubator-nuttx/pull/1677#issuecomment-683842087
This looks good Adam. I only have one general comment: the "drivers" document reads more like a general guide for developing NuttX than working specifically on a driver. I had in mind to eventually have a guideline for how to write the different kinds of drivers somewhere. So I believe this document could be better named something like "Tips for working on NuttX" or similar (maybe you think of a better name).
----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [incubator-nuttx] v01d commented on pull request #1677: Add Simulator and Drivers guides, and contributing instructions for new users
Posted by GitBox <gi...@apache.org>.
v01d commented on pull request #1677:
URL: https://github.com/apache/incubator-nuttx/pull/1677#issuecomment-683864228
Could you point out what are these differences? Maybe we can include something here
----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [incubator-nuttx] adamfeuer commented on a change in pull request #1677: Add Simulator and Drivers guides, and contributing instructions for new users
Posted by GitBox <gi...@apache.org>.
adamfeuer commented on a change in pull request #1677:
URL: https://github.com/apache/incubator-nuttx/pull/1677#discussion_r483861652
##########
File path: Documentation/contributing/making-changes.rst
##########
@@ -0,0 +1,256 @@
+.. include:: /substitutions.rst
+.. _making-changes:
+
+Making Changes
+==============
+
+If you want to make changes to NuttX, for your own personal use, or to submit them back to project to improve NuttX,
+that's easy. For the purposes of this guide, you'll need a `GitHub <https://www.github.com>`_ account, since
+the Apache NuttX team uses GitHub. (You could also use git locally, or save your changes to other sites like
+`GitLab <https://about.gitlab.com/>`_ or `BitBucket <https://bitbucket.org>`_, but that's beyond the scope of this
+guide).
+
+Here's how to do it:
+
+#. Set your git user name and email
+
+ .. code-block:: bash
+
+ $ cd nuttx/
+ $ git config --global user.name "Your Name"
+ $ git config --global user.email "yourname@somedomaincom"
+
+#. Sign in to GitHub
+
+ If you don't have a `GitHub <https://www.github.com>`_ account, it's free to
+ sign up.
+ |br|
+ |br|
+
+
+#. Fork the Project
+
+ Visit both these links and hit the Fork button in the upper right of the page:
+
+ * `NuttX <https://github.com/apache/incubator-nuttx/>`_
+ * `NuttX Apps <https://github.com/apache/incubator-nuttx-apps/>`_
+
+
+#. Change the Git Remotes
+
+ The git repositories in your project are currently connected to the official NuttX repositories, but you don't
+ have permission to push software there. But you can push them to your forks, and from there create Pull Requests
+ if you want to send them to the NuttX project.
+
+ First, remove the current remote, ``origin`` (we'll add it back later):
+
+ .. code-block:: bash
+
+ $ cd nuttx/
+ $ # display the remote
+ $ git remote -v
+
+ You should see something like this:
+
+ .. code-block:: bash
+
+ origin https://github.com/apache/incubator-nuttx.git
+
+ Now, on the GitHub web page for your forked ``incubator-nuttx`` project, copy the clone url – get it by hitting the
+ green ``Clone or Download`` button in the upper right. Then do this:
+
+ .. code-block:: bash
+
+ $ git remote rm origin
+ $ git remote add origin <your forked incubator-nuttx project clone url>
+ $ git remote add upstream https://github.com/apache/incubator-nuttx.git
+
+ Do the same for your forked ``incubator-nuttx-apps`` project:
+
+ .. code-block:: bash
+
+ $ cd ../apps
+ $ git remote rm origin
+ $ git remote add origin <your forked incubator-nuttx-apps project clone url>
+ $ git remote add upstream https://github.com/apache/incubator-nuttx-apps.git
+
+
+#. Create a Local Git Branch
+
+ Now you can create local git branches and push them to GitHub:
+
+ .. code-block:: bash
+
+ $ git checkout -b test/my-new-branch
+ $ git push
+
+
+Git Workflow With an Upstream Repository
+----------------------------------------
+
+The main NuttX git repository is called an "upstream" repository - this is because it's the main source of truth, and
+its changes flow downstream to people who've forked that repository, like us.
+
+Working with an upstream repo is a bit more complex, but it's worth it since you can submit fixes and features
+to the main NuttX repos. One of the things you need to do regularly is keep your local repo in sync
+with the upstream. I work with a local branch, make changes, pull new software from the upstream and merge it in,
+maybe doing that several times. Then when everything works, I get my branch ready to do a Pull Request. Here's how:
+
+#. Fetch upstream changes and merge into my local master:
+
+ .. code-block:: bash
+
+ $ git checkout master
+ $ git fetch upstream
+ $ git merge upstream/master
+ $ git push
+
+#. Merge my local master with my local branch:
+
+ .. code-block:: bash
+
+ $ git checkout my-local-branch
+ $ git merge master
+ $ git push
Review comment:
@btashton I removed the alternative flow. I guess I personally need to switch to this flow too. 🙂
----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [incubator-nuttx] adamfeuer commented on a change in pull request #1677: Add Simulator and Drivers guides, and contributing instructions for new users
Posted by GitBox <gi...@apache.org>.
adamfeuer commented on a change in pull request #1677:
URL: https://github.com/apache/incubator-nuttx/pull/1677#discussion_r483869933
##########
File path: Documentation/guides/drivers.rst
##########
@@ -0,0 +1,211 @@
+.. include:: /substitutions.rst
+.. _drivers:
+
+Drivers
+=======
+
+Some NuttX boards don't have full support for all the on-chip peripherals. If you need support for this hardware,
+you will either need to port a driver from another chip, or write one yourself. This section discusses how to do that.
+
+Porting a Driver
+----------------
+
+Often support for on-chip peripherals exists in a closely related chip, or even a different family or from a different
+manufacturer. Many chips are made up of different Intellectual Property (IP) blocks that are licensed from vendors like
+Cadence, Synopsys, and others. The IP blocks may be similar enough to use another chip's driver with little
+modification.
+
+* Find a similar driver in NuttX source code:
+
+ * Look at register names listed in the datasheet for the peripheral.
+ * Search the NuttX codebase for the register names (try several different ones).
+ * Note that you'll have to compare the datasheet to the header and code files to see if there are differences; there
+ will usually be some differences between architectures, and they can be significant.
+
+* Find a similar driver in U-Boot source code:
+
+ * Only for inspiration, you can't copy code because of license incompatibility.
+ * But you can debug to see how the driver works.
+ * `U-Boot <https://www.denx.de/wiki/U-Boot>`_ drivers are often easier to understand than BSD Unix drivers because
+ U-Boot is simpler.
+
+* Find a similar driver in Zephyr or BSD Unix (OpenBSD, FreeBSD, NetBSD):
+
+ * If you find one, you can borrow code directly (Apache 2.0 and BSD licenses are compatible).
+
+* Understanding how the driver works
+
+ Here are a couple of techniques that helped me.
+
+ * printf debugging
+
+ * Sprinkle ``custinfo()`` logging statements through your code to see execution paths and look at variables
+ while the code is running. The reason to use ``custinfo()`` as opposed to the other logging shortcuts
+ (``mcinfo()``, etc.) is that you can turn on and off other other logging and still see your custom debug
+ logging. Sometimes it's useful to quiet the flood of logging that comes from a particular debug logging
+ shortcut.
+ * Note that printing info to the console will affect timing.
+ * Keep a file with just your debug settings in it, like this (``debugsettings``):
+
+ .. code-block:: c
+
+ CONFIG_DEBUG_CUSTOM_INFO=y
+ (etc..)
+
+ * Add the settings to the end of your ``.config`` file after running ``make menuconfig`` (that will reorder
+ the file, making it harder to see and change the debug settings if you need to).
+
+ .. code-block:: bash
+
+ $ cat .config debugsettings > .config1 ; mv .config1 .config
+
+ * If you are using interrupts and threads (many things in NuttX run in different threads as a response to interrupts),
+ you can use printf debugging to see overlapping execution.
+
+ * Interrupts - here's how to inspect the C stack frame to see what execution environment is currently running:
+
+ .. code-block:: c
+
+ uint32_t frame = 0; /* MUST be the very first thing in the function */
+ uint32_t p_frame;
+ frame++; /* make sure that frame doesn't get optimized out */
+ p_frame = (uint32_t)(&frame);
+ custinfo("p_frame: %08x\n", p_frame);
+
+ * Threads - here's how to get the thread identifier to see which thread is currently executing:
+
+ .. code-block:: c
+
+ pthread_t thread_id = pthread_self();
+ custinfo("pthread_id: %08x\n", thread_id);
+
+ * stack frame printf
+ * thread printf
+
+ * `GDB — the Gnu Debugger <https://www.gnu.org/software/gdb/>`_
+
+ GDB is a great tool. In this guide we've already used it to load our program and run it. But it can do a lot
+ more. You can single-step through code, examine variables and memory, set breakpoints, and more. I generally use
+ it from the commandline, but have also used it from an IDE like JetBrains' Clion, where it's easier to see the
+ code context.
+
+ One add-on that I found to be essential is the ability to examine blocks of memory, like buffers that NuttX uses
+ for reading and writing to storage media or network adapters. This `Stack Overflow question on using GDB to
+ examine memory <https://stackoverflow.com/a/54784260/431222>`_ includes a GDB command that is very handy. Add
+ this to your ``.gdbinit`` file, and then use the ``xxd`` command to dump memory in an easy-to-read format:
+
+ .. code-block::
+
+ define xxd
+ if $argc < 2
+ set $size = sizeof(*$arg0)
+ else
+ set $size = $arg1
+ end
+ dump binary memory dump.bin $arg0 ((void *)$arg0)+$size
+ eval "shell xxd -o %d dump.bin; rm dump.bin", ((void *)$arg0)
+ end
+ document xxd
+ Dump memory with xxd command (keep the address as offset)
+
+ xxd addr [size]
+ addr -- expression resolvable as an address
+ size -- size (in byte) of memory to dump
+ sizeof(*addr) is used by default end
+
+ Here's a short GDB session that shows what this looks like in practice. Note that the memory location being
+ examined (``0x200aa9eo`` here) is a buffer being passed to ``mmcsd_readsingle``:
+
+ .. code-block::
+
+ Program received signal SIGTRAP, Trace/breakpoint trap.
+ 0x200166e8 in up_idle () at common/arm_idle.c:78
+ 78 }
+ (gdb) b mmcsd_readsingle
+ Breakpoint 1 at 0x2006ea70: file mmcsd/mmcsd_sdio.c, line 1371.
+ (gdb) c
+ Continuing.
+
+ Breakpoint 1, mmcsd_readsingle (priv=0x200aa8c0, buffer=0x200aa9e0 "WRTEST TXT \030", startblock=2432) at mmcsd/mmcsd_sdio.c:1371
+ 1371 finfo("startblock=%d\n", startblock);
+ (gdb) xxd 0x200aa9e0 200
+ 200aa9e0: 5752 5445 5354 2020 5458 5420 1800 0000 WRTEST TXT ....
+ 200aa9f0: 0000 0000 0000 0000 0000 5500 1100 0000 ..........U.....
+ 200aaa00: 5752 5445 5354 3520 5458 5420 1800 0000 WRTEST5 TXT ....
+ 200aaa10: 0000 0000 0000 0000 0000 5800 1500 0000 ..........X.....
+ 200aaa20: e552 5445 5854 3620 5458 5420 1800 0000 .RTEXT6 TXT ....
+ 200aaa30: 0000 0000 0000 0000 0000 5600 1200 0000 ..........V.....
+ 200aaa40: 5752 5445 5354 3620 5458 5420 1800 0000 WRTEST6 TXT ....
+ 200aaa50: 0000 0000 0000 0000 0000 5600 1200 0000 ..........V.....
+ 200aaa60: 0000 0000 0000 0000 0000 0000 0000 0000 ................
+ 200aaa70: 0000 0000 0000 0000 0000 0000 0000 0000 ................
+ 200aaa80: 0000 0000 0000 0000 0000 0000 0000 0000 ................
+ 200aaa90: 0000 0000 0000 0000 0000 0000 0000 0000 ................
+ 200aaaa0: 0000 0000 0000 0000 ........
+
+
+NuttX Drivers as a Reference
+----------------------------
+
+If you're not porting a NuttX driver from another architecture, it still helps to look at other similar NuttX
+drivers, if there are any. For instance, when implementing an Ethernet driver, look at other NuttX Ethernet drivers;
+for an SD Card driver, look at other NuttX Ethernet drivers. Even if the chip-specific code won't be the same, the
+structure to interface with NuttX can be used.
+
+Using Chip Datasheets
+---------------------
+
+To port or write a driver, you'll have to be familiar with the information in the chip datasheet. Definitely find
+the datasheet for your chip, and read the sections relevant to the peripheral you're working with. Doing so ahead
+of time will save a lot of time later.
+
+Another thing that's often helpful is to refer to sample code provided by the manufacturer, or driver code from
+another operating system (like U-Boot, Zephyr, or FreeBSD) while referring to the datasheet — seeing how working
+code implements the necessary algorithms often helps one understand how the driver needs to work.
+
+* How to use a datasheet
+
+ Key pieces of information in System-on-a-Chip (SoC) datasheets are usually:
+
+ * Chip Architecture Diagram — shows how the subsections of the chip (CPU, system bus, peripherals, I/O, etc.) connect
+ to each other.
+ * Memory Map — showing the location of peripheral registers in memory. This info usually goes into a header file.
+ * DMA Engine — if Direct Memory Access (DMA) is used, this may have info on how to use it.
+ * Peripheral — the datasheet usually has a section on how the peripheral works. Key parts of this include:
+
+ * Registers List — name and offset from the base memory address of the peripheral. This needs to go into a header
+ file.
+ * Register Map — what is the size of each register, and what do the bits mean? You will need to create ``#defines``
+ in a header file that your code will use to operate on the registers. Refer to other driver header files for
+ examples.
+
+`Logic analyzers <https://en.wikipedia.org/wiki/Logic_analyzer>`_
Review comment:
@btashton I moved the link into the paragraph, and left the header as plain text.
----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [incubator-nuttx] btashton commented on a change in pull request #1677: Add Simulator and Drivers guides, and contributing instructions for new users
Posted by GitBox <gi...@apache.org>.
btashton commented on a change in pull request #1677:
URL: https://github.com/apache/incubator-nuttx/pull/1677#discussion_r480257575
##########
File path: Documentation/contributing/making-changes.rst
##########
@@ -0,0 +1,256 @@
+.. include:: /substitutions.rst
+.. _making-changes:
+
+Making Changes
+==============
+
+If you want to make changes to NuttX, for your own personal use, or to submit them back to project to improve NuttX,
+that's easy. For the purposes of this guide, you'll need a `GitHub <https://www.github.com>`_ account, since
+the Apache NuttX team uses GitHub. (You could also use git locally, or save your changes to other sites like
+`GitLab <https://about.gitlab.com/>`_ or `BitBucket <https://bitbucket.org>`_, but that's beyond the scope of this
+guide).
+
+Here's how to do it:
+
+#. Set your git user name and email
+
+ .. code-block:: bash
+
+ $ cd nuttx/
+ $ git config --global user.name "Your Name"
+ $ git config --global user.email "yourname@somedomaincom"
+
+#. Sign in to GitHub
+
+ If you don't have a `GitHub <https://www.github.com>`_ account, it's free to
+ sign up.
+ |br|
+ |br|
+
+
+#. Fork the Project
+
+ Visit both these links and hit the Fork button in the upper right of the page:
+
+ * `NuttX <https://github.com/apache/incubator-nuttx/>`_
+ * `NuttX Apps <https://github.com/apache/incubator-nuttx-apps/>`_
+
+
+#. Change the Git Remotes
+
+ The git repositories in your project are currently connected to the official NuttX repositories, but you don't
+ have permission to push software there. But you can push them to your forks, and from there create Pull Requests
+ if you want to send them to the NuttX project.
+
+ First, remove the current remote, ``origin`` (we'll add it back later):
+
+ .. code-block:: bash
+
+ $ cd nuttx/
+ $ # display the remote
+ $ git remote -v
+
+ You should see something like this:
+
+ .. code-block:: bash
+
+ origin https://github.com/apache/incubator-nuttx.git
+
+ Now, on the GitHub web page for your forked ``incubator-nuttx`` project, copy the clone url – get it by hitting the
+ green ``Clone or Download`` button in the upper right. Then do this:
+
+ .. code-block:: bash
+
+ $ git remote rm origin
+ $ git remote add origin <your forked incubator-nuttx project clone url>
+ $ git remote add upstream https://github.com/apache/incubator-nuttx.git
+
+ Do the same for your forked ``incubator-nuttx-apps`` project:
+
+ .. code-block:: bash
+
+ $ cd ../apps
+ $ git remote rm origin
+ $ git remote add origin <your forked incubator-nuttx-apps project clone url>
+ $ git remote add upstream https://github.com/apache/incubator-nuttx-apps.git
+
+
+#. Create a Local Git Branch
+
+ Now you can create local git branches and push them to GitHub:
+
+ .. code-block:: bash
+
+ $ git checkout -b test/my-new-branch
+ $ git push
+
+
+Git Workflow With an Upstream Repository
+----------------------------------------
+
+The main NuttX git repository is called an "upstream" repository - this is because it's the main source of truth, and
+its changes flow downstream to people who've forked that repository, like us.
+
+Working with an upstream repo is a bit more complex, but it's worth it since you can submit fixes and features
+to the main NuttX repos. One of the things you need to do regularly is keep your local repo in sync
+with the upstream. I work with a local branch, make changes, pull new software from the upstream and merge it in,
+maybe doing that several times. Then when everything works, I get my branch ready to do a Pull Request. Here's how:
+
+#. Fetch upstream changes and merge into my local master:
+
+ .. code-block:: bash
+
+ $ git checkout master
+ $ git fetch upstream
+ $ git merge upstream/master
+ $ git push
+
+#. Merge my local master with my local branch:
+
+ .. code-block:: bash
+
+ $ git checkout my-local-branch
+ $ git merge master
+ $ git push
Review comment:
> >I was wondering why we show
> git rev-list
>
> rev-list or any other count gives the number of commits the branch has. That number is then used for interactive (-i) rebasing.
>
You don't need to do that you just supply the branch as the argument to rebase (or interactive rebase).
----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [incubator-nuttx] btashton commented on a change in pull request #1677: Add Simulator and Drivers guides, and contributing instructions for new users
Posted by GitBox <gi...@apache.org>.
btashton commented on a change in pull request #1677:
URL: https://github.com/apache/incubator-nuttx/pull/1677#discussion_r483864477
##########
File path: Documentation/guides/drivers.rst
##########
@@ -0,0 +1,211 @@
+.. include:: /substitutions.rst
+.. _drivers:
+
+Drivers
+=======
+
+Some NuttX boards don't have full support for all the on-chip peripherals. If you need support for this hardware,
+you will either need to port a driver from another chip, or write one yourself. This section discusses how to do that.
+
+Porting a Driver
+----------------
+
+Often support for on-chip peripherals exists in a closely related chip, or even a different family or from a different
+manufacturer. Many chips are made up of different Intellectual Property (IP) blocks that are licensed from vendors like
+Cadence, Synopsys, and others. The IP blocks may be similar enough to use another chip's driver with little
+modification.
+
+* Find a similar driver in NuttX source code:
+
+ * Look at register names listed in the datasheet for the peripheral.
+ * Search the NuttX codebase for the register names (try several different ones).
+ * Note that you'll have to compare the datasheet to the header and code files to see if there are differences; there
+ will usually be some differences between architectures, and they can be significant.
+
+* Find a similar driver in U-Boot source code:
+
+ * Only for inspiration, you can't copy code because of license incompatibility.
+ * But you can debug to see how the driver works.
+ * `U-Boot <https://www.denx.de/wiki/U-Boot>`_ drivers are often easier to understand than BSD Unix drivers because
+ U-Boot is simpler.
+
+* Find a similar driver in Zephyr or BSD Unix (OpenBSD, FreeBSD, NetBSD):
+
+ * If you find one, you can borrow code directly (Apache 2.0 and BSD licenses are compatible).
Review comment:
Yes otherwise it cannot carry ASF header it must retain the original one. So it is Apache 2.0 compatible, but it still must refer to the third party license unless there is a SGA.
----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [incubator-nuttx] Ouss4 commented on a change in pull request #1677: Add Simulator and Drivers guides, and contributing instructions for new users
Posted by GitBox <gi...@apache.org>.
Ouss4 commented on a change in pull request #1677:
URL: https://github.com/apache/incubator-nuttx/pull/1677#discussion_r480273344
##########
File path: Documentation/contributing/making-changes.rst
##########
@@ -0,0 +1,256 @@
+.. include:: /substitutions.rst
+.. _making-changes:
+
+Making Changes
+==============
+
+If you want to make changes to NuttX, for your own personal use, or to submit them back to project to improve NuttX,
+that's easy. For the purposes of this guide, you'll need a `GitHub <https://www.github.com>`_ account, since
+the Apache NuttX team uses GitHub. (You could also use git locally, or save your changes to other sites like
+`GitLab <https://about.gitlab.com/>`_ or `BitBucket <https://bitbucket.org>`_, but that's beyond the scope of this
+guide).
+
+Here's how to do it:
+
+#. Set your git user name and email
+
+ .. code-block:: bash
+
+ $ cd nuttx/
+ $ git config --global user.name "Your Name"
+ $ git config --global user.email "yourname@somedomaincom"
+
+#. Sign in to GitHub
+
+ If you don't have a `GitHub <https://www.github.com>`_ account, it's free to
+ sign up.
+ |br|
+ |br|
+
+
+#. Fork the Project
+
+ Visit both these links and hit the Fork button in the upper right of the page:
+
+ * `NuttX <https://github.com/apache/incubator-nuttx/>`_
+ * `NuttX Apps <https://github.com/apache/incubator-nuttx-apps/>`_
+
+
+#. Change the Git Remotes
+
+ The git repositories in your project are currently connected to the official NuttX repositories, but you don't
+ have permission to push software there. But you can push them to your forks, and from there create Pull Requests
+ if you want to send them to the NuttX project.
+
+ First, remove the current remote, ``origin`` (we'll add it back later):
+
+ .. code-block:: bash
+
+ $ cd nuttx/
+ $ # display the remote
+ $ git remote -v
+
+ You should see something like this:
+
+ .. code-block:: bash
+
+ origin https://github.com/apache/incubator-nuttx.git
+
+ Now, on the GitHub web page for your forked ``incubator-nuttx`` project, copy the clone url – get it by hitting the
+ green ``Clone or Download`` button in the upper right. Then do this:
+
+ .. code-block:: bash
+
+ $ git remote rm origin
+ $ git remote add origin <your forked incubator-nuttx project clone url>
+ $ git remote add upstream https://github.com/apache/incubator-nuttx.git
+
+ Do the same for your forked ``incubator-nuttx-apps`` project:
+
+ .. code-block:: bash
+
+ $ cd ../apps
+ $ git remote rm origin
+ $ git remote add origin <your forked incubator-nuttx-apps project clone url>
+ $ git remote add upstream https://github.com/apache/incubator-nuttx-apps.git
+
+
+#. Create a Local Git Branch
+
+ Now you can create local git branches and push them to GitHub:
+
+ .. code-block:: bash
+
+ $ git checkout -b test/my-new-branch
+ $ git push
+
+
+Git Workflow With an Upstream Repository
+----------------------------------------
+
+The main NuttX git repository is called an "upstream" repository - this is because it's the main source of truth, and
+its changes flow downstream to people who've forked that repository, like us.
+
+Working with an upstream repo is a bit more complex, but it's worth it since you can submit fixes and features
+to the main NuttX repos. One of the things you need to do regularly is keep your local repo in sync
+with the upstream. I work with a local branch, make changes, pull new software from the upstream and merge it in,
+maybe doing that several times. Then when everything works, I get my branch ready to do a Pull Request. Here's how:
+
+#. Fetch upstream changes and merge into my local master:
+
+ .. code-block:: bash
+
+ $ git checkout master
+ $ git fetch upstream
+ $ git merge upstream/master
+ $ git push
+
+#. Merge my local master with my local branch:
+
+ .. code-block:: bash
+
+ $ git checkout my-local-branch
+ $ git merge master
+ $ git push
Review comment:
I said a range _from the HEAD_. I didn't mean that HEAD ~ N is a range. HEAD~N is the Nth commit behind HEAD.
The current branch's top commit is HEAD.
When you are "checkedout" to master and you do `git rebase -i master`, that means you are trying to rebase from HEAD to HEAD, thus the "noop".
----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [incubator-nuttx] v01d commented on pull request #1677: Add Simulator and Drivers guides, and contributing instructions for new users
Posted by GitBox <gi...@apache.org>.
v01d commented on pull request #1677:
URL: https://github.com/apache/incubator-nuttx/pull/1677#issuecomment-687404973
> @v01d Re: the drivers section, will you suggest a new name for it then?
Mmm... I looked at the drivers.rst again and I realize that you simply use "drivers" in a more general way than I was considering.
Let's leave it as is. We can iterate this as the rest of the documentation matures.
----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [incubator-nuttx] v01d commented on a change in pull request #1677: Add Simulator and Drivers guides, and contributing instructions for new users
Posted by GitBox <gi...@apache.org>.
v01d commented on a change in pull request #1677:
URL: https://github.com/apache/incubator-nuttx/pull/1677#discussion_r483828058
##########
File path: Documentation/contributing/making-changes.rst
##########
@@ -0,0 +1,256 @@
+.. include:: /substitutions.rst
+.. _making-changes:
+
+Making Changes
+==============
+
+If you want to make changes to NuttX, for your own personal use, or to submit them back to project to improve NuttX,
+that's easy. For the purposes of this guide, you'll need a `GitHub <https://www.github.com>`_ account, since
+the Apache NuttX team uses GitHub. (You could also use git locally, or save your changes to other sites like
+`GitLab <https://about.gitlab.com/>`_ or `BitBucket <https://bitbucket.org>`_, but that's beyond the scope of this
+guide).
+
+Here's how to do it:
+
+#. Set your git user name and email
+
+ .. code-block:: bash
+
+ $ cd nuttx/
+ $ git config --global user.name "Your Name"
+ $ git config --global user.email "yourname@somedomaincom"
+
+#. Sign in to GitHub
+
+ If you don't have a `GitHub <https://www.github.com>`_ account, it's free to
+ sign up.
+ |br|
+ |br|
+
+
+#. Fork the Project
+
+ Visit both these links and hit the Fork button in the upper right of the page:
+
+ * `NuttX <https://github.com/apache/incubator-nuttx/>`_
+ * `NuttX Apps <https://github.com/apache/incubator-nuttx-apps/>`_
+
+
+#. Change the Git Remotes
+
+ The git repositories in your project are currently connected to the official NuttX repositories, but you don't
+ have permission to push software there. But you can push them to your forks, and from there create Pull Requests
+ if you want to send them to the NuttX project.
+
+ First, remove the current remote, ``origin`` (we'll add it back later):
+
+ .. code-block:: bash
+
+ $ cd nuttx/
+ $ # display the remote
+ $ git remote -v
+
+ You should see something like this:
+
+ .. code-block:: bash
+
+ origin https://github.com/apache/incubator-nuttx.git
+
+ Now, on the GitHub web page for your forked ``incubator-nuttx`` project, copy the clone url – get it by hitting the
+ green ``Clone or Download`` button in the upper right. Then do this:
+
+ .. code-block:: bash
+
+ $ git remote rm origin
+ $ git remote add origin <your forked incubator-nuttx project clone url>
+ $ git remote add upstream https://github.com/apache/incubator-nuttx.git
+
+ Do the same for your forked ``incubator-nuttx-apps`` project:
+
+ .. code-block:: bash
+
+ $ cd ../apps
+ $ git remote rm origin
+ $ git remote add origin <your forked incubator-nuttx-apps project clone url>
+ $ git remote add upstream https://github.com/apache/incubator-nuttx-apps.git
+
+
+#. Create a Local Git Branch
+
+ Now you can create local git branches and push them to GitHub:
+
+ .. code-block:: bash
+
+ $ git checkout -b test/my-new-branch
+ $ git push
+
+
+Git Workflow With an Upstream Repository
+----------------------------------------
+
+The main NuttX git repository is called an "upstream" repository - this is because it's the main source of truth, and
+its changes flow downstream to people who've forked that repository, like us.
+
+Working with an upstream repo is a bit more complex, but it's worth it since you can submit fixes and features
+to the main NuttX repos. One of the things you need to do regularly is keep your local repo in sync
+with the upstream. I work with a local branch, make changes, pull new software from the upstream and merge it in,
+maybe doing that several times. Then when everything works, I get my branch ready to do a Pull Request. Here's how:
+
+#. Fetch upstream changes and merge into my local master:
+
+ .. code-block:: bash
+
+ $ git checkout master
+ $ git fetch upstream
+ $ git merge upstream/master
+ $ git push
+
+#. Merge my local master with my local branch:
+
+ .. code-block:: bash
+
+ $ git checkout my-local-branch
+ $ git merge master
+ $ git push
+
+#. Make changes and push them to my fork
+
+ .. code-block:: bash
+
+ $ vim my-file.c
+ $ git add my-file.c
+ $ git commit my-file.c
+ $ git push
+
+#. Repeat 1-3 as necessary
+
+#. Run the ``tools/checkpatch.sh`` script on your files
+
+ When your code runs, then you're almost ready to submit it. But first you need to check the code to ensure
+ that it conforms to the NuttX :ref:`contributing/coding_style:C Coding Standard`.
+ The ``tools/checkpatch.sh`` script will do that. Here's the usage info:
+
+ .. code-block:: bash
+
+ $ ./tools/checkpatch.sh -h
+ USAGE: ./tools/checkpatch.sh [options] [list|-]
+
+ Options:
+ -h
+ -c spell check with codespell(install with: pip install codespell
+ -r range check only (used with -p and -g)
+ -p <patch list> (default)
+ -g <commit list>
+ -f <file list>
+ - read standard input mainly used by git pre-commit hook as below:
+ git diff --cached | ./tools/checkpatch.sh -
+
+ Run it against your files and correct all the errors in the code you added, so that
+ ``tools/checkpatch.sh`` reports no errors. Then commit the result.
+ For example:
+
+ .. code-block:: bash
+
+ $ ./tools/checkpatch.sh -f my-file.c
+ arch/arm/src/sama5/hardware/my-file.c:876:82: warning: Long line found
+ $ # fix errors
+ $ vim my-file.c
+ $ # run again
+ $ ./tools/checkpatch.sh -f my-file.c
+
+ If you have made a lot of changes, you can also use this bash commandline to see the errors for all the changed C
+ files in your branch (assumes you are currently on the branch that has the changed files):
+
+ .. code-block:: bash
+
+ $ git diff --name-only master | egrep "\.c|\.h" | xargs echo | xargs ./tools/checkpatch.sh -f | less
+
+ Note that there are some bugs in the ``nxstyle`` program that ``checkpatch.sh`` uses, so
+ it may report a few errors that are not actually errors. The committers will help you
+ find these. (Or view the
+ `nxstyle Issues <https://github.com/apache/incubator-nuttx/issues?q=is%3Aissue+is%3Aopen+nxstyle>`_.)
+ |br|
+ |br|
+
+#. Commit the fixed files
+
+ .. code-block:: bash
+
+ $ git add my-file.c
+ $ git commit my-file.c
+ $ git push
+
+
+Submitting Your Changes to NuttX
+--------------------------------
+
+ Pull requests let you tell others about changes you've pushed to a branch in a repository on GitHub. Once a pull
+ request is opened, you can discuss and review the potential changes with collaborators and add follow-up commits
+ before your changes are merged into the base branch.
+
+ (from GitHub's `About pull requests <https://docs.github.com/en/github/collaborating-with-issues-and-pull-requests/about-pull-requests>`_ page)
+
+Before you do a Pull Request, the NuttX team will usually want all the changes you made in your branch "squashed" into
+a single commit, so that when they review your changes, there's a clean view of the history. If there are changes
+after Pull Request review feedback, they can be separate commits. Here's the easiest way I found to do that initial
+squash before submitting the Pull Request:
+
+#. Check out my branch
+
+ .. code-block:: bash
+
+ $ git checkout my-branch
+
+#. Rename it to ``my-branch-old`` to save it, because we're going to create new clean branch to push:
+
+ .. code-block:: bash
+
+ $ git branch -m my-branch-old
+
+#. Create a new clean branch with the same name you were using before the last step:
+
+ .. code-block:: bash
+
+ $ git checkout master
+ $ git checkout -b my-branch
+
+#. Merge your saved old branch into the new one, telling git to "squash" all your commits into one (note this will
+ not commit the result; the changed files will be in your staging area, ready to be committed):
+
+ .. code-block:: bash
+
+ $ git merge --squash my-branch-old
+
+#. Commit the result
+
+ .. code-block:: bash
+
+ $ git commit
+
+#. Force-push your new clean branch to the remote— this will overwrite all your previous changes in that branch:
+
+ .. code-block:: bash
+
+ $ git push -f --set-upstream origin my-branch
+
+#. Create a GitHub Pull Request
+
+ A Pull Request is how you ask your upstream to review and merge your changes.
+
+ Here's `GitHub's instructions for creating a Pull Request <https://help.github.com/en/github/collaborating-with-issues-and-pull-requests/creating-a-pull-request>`_.
+
+ |br|
+
+#. Get Pull Request feedback and implement changes
+
+ Get suggestions for improvements from reviewers, make changes, and push them to the branch. Once the reviewers are
+ happy, they may suggest squashing and merging again to make a single commit. In this case you would repeat steps
+ 1 through 6.
+
+Git Resources
+-------------
+
+* `Git Cheat Sheet (by GitHub) <https://github.github.com/training-kit/downloads/github-git-cheat-sheet.pdf>`_
+* `Git Book (online) <https://git-scm.com/book/en/v2>`_
+* `NuttX Code Contribution Workflow <https://cwiki.apache.org/confluence/display/NUTTX/Code+Contribution+Workflow>`_ –
Review comment:
I'm not sure if the document in the wiki is really ready for "public consumption". If you want to leave the link, maybe add a text before like "Contribution Workflow Internal Draft:". I would like to avoid confusion for new users.
----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [incubator-nuttx] v01d commented on a change in pull request #1677: Add Simulator and Drivers guides, and contributing instructions for new users
Posted by GitBox <gi...@apache.org>.
v01d commented on a change in pull request #1677:
URL: https://github.com/apache/incubator-nuttx/pull/1677#discussion_r480173634
##########
File path: Documentation/contributing/making-changes.rst
##########
@@ -0,0 +1,256 @@
+.. include:: /substitutions.rst
+.. _making-changes:
+
+Making Changes
+==============
+
+If you want to make changes to NuttX, for your own personal use, or to submit them back to project to improve NuttX,
+that's easy. For the purposes of this guide, you'll need a `GitHub <https://www.github.com>`_ account, since
+the Apache NuttX team uses GitHub. (You could also use git locally, or save your changes to other sites like
+`GitLab <https://about.gitlab.com/>`_ or `BitBucket <https://bitbucket.org>`_, but that's beyond the scope of this
+guide).
+
+Here's how to do it:
+
+#. Set your git user name and email
+
+ .. code-block:: bash
+
+ $ cd nuttx/
+ $ git config --global user.name "Your Name"
+ $ git config --global user.email "yourname@somedomaincom"
+
+#. Sign in to GitHub
+
+ If you don't have a `GitHub <https://www.github.com>`_ account, it's free to
+ sign up.
+ |br|
+ |br|
+
+
+#. Fork the Project
+
+ Visit both these links and hit the Fork button in the upper right of the page:
+
+ * `NuttX <https://github.com/apache/incubator-nuttx/>`_
+ * `NuttX Apps <https://github.com/apache/incubator-nuttx-apps/>`_
+
+
+#. Change the Git Remotes
+
+ The git repositories in your project are currently connected to the official NuttX repositories, but you don't
+ have permission to push software there. But you can push them to your forks, and from there create Pull Requests
+ if you want to send them to the NuttX project.
+
+ First, remove the current remote, ``origin`` (we'll add it back later):
+
+ .. code-block:: bash
+
+ $ cd nuttx/
+ $ # display the remote
+ $ git remote -v
+
+ You should see something like this:
+
+ .. code-block:: bash
+
+ origin https://github.com/apache/incubator-nuttx.git
+
+ Now, on the GitHub web page for your forked ``incubator-nuttx`` project, copy the clone url – get it by hitting the
+ green ``Clone or Download`` button in the upper right. Then do this:
+
+ .. code-block:: bash
+
+ $ git remote rm origin
+ $ git remote add origin <your forked incubator-nuttx project clone url>
+ $ git remote add upstream https://github.com/apache/incubator-nuttx.git
+
+ Do the same for your forked ``incubator-nuttx-apps`` project:
+
+ .. code-block:: bash
+
+ $ cd ../apps
+ $ git remote rm origin
+ $ git remote add origin <your forked incubator-nuttx-apps project clone url>
+ $ git remote add upstream https://github.com/apache/incubator-nuttx-apps.git
+
+
+#. Create a Local Git Branch
+
+ Now you can create local git branches and push them to GitHub:
+
+ .. code-block:: bash
+
+ $ git checkout -b test/my-new-branch
+ $ git push
+
+
+Git Workflow With an Upstream Repository
+----------------------------------------
+
+The main NuttX git repository is called an "upstream" repository - this is because it's the main source of truth, and
+its changes flow downstream to people who've forked that repository, like us.
+
+Working with an upstream repo is a bit more complex, but it's worth it since you can submit fixes and features
+to the main NuttX repos. One of the things you need to do regularly is keep your local repo in sync
+with the upstream. I work with a local branch, make changes, pull new software from the upstream and merge it in,
+maybe doing that several times. Then when everything works, I get my branch ready to do a Pull Request. Here's how:
+
+#. Fetch upstream changes and merge into my local master:
+
+ .. code-block:: bash
+
+ $ git checkout master
+ $ git fetch upstream
+ $ git merge upstream/master
+ $ git push
+
+#. Merge my local master with my local branch:
+
+ .. code-block:: bash
+
+ $ git checkout my-local-branch
+ $ git merge master
+ $ git push
+
+#. Make changes and push them to my fork
+
+ .. code-block:: bash
+
+ $ vim my-file.c
+ $ git add my-file.c
+ $ git commit my-file.c
+ $ git push
+
+#. Repeat 1-3 as necessary
+
+#. Run the ``tools/checkpatch.sh`` script on your files
+
+ When your code runs, then you're almost ready to submit it. But first you need to check the code to ensure
+ that it conforms to the NuttX :ref:`contributing/coding_style:C Coding Standard`.
+ The ``tools/checkpatch.sh`` script will do that. Here's the usage info:
+
+ .. code-block:: bash
+
+ $ ./tools/checkpatch.sh -h
+ USAGE: ./tools/checkpatch.sh [options] [list|-]
+
+ Options:
+ -h
+ -c spell check with codespell(install with: pip install codespell
+ -r range check only (used with -p and -g)
+ -p <patch list> (default)
+ -g <commit list>
+ -f <file list>
+ - read standard input mainly used by git pre-commit hook as below:
+ git diff --cached | ./tools/checkpatch.sh -
+
+ Run it against your files and correct all the errors in the code you added, so that
+ ``tools/checkpatch.sh`` reports no errors. Then commit the result.
+ For example:
+
+ .. code-block:: bash
+
+ $ ./tools/checkpatch.sh -f my-file.c
+ arch/arm/src/sama5/hardware/my-file.c:876:82: warning: Long line found
+ $ # fix errors
+ $ vim my-file.c
+ $ # run again
+ $ ./tools/checkpatch.sh -f my-file.c
+
+ If you have made a lot of changes, you can also use this bash commandline to see the errors for all the changed C
+ files in your branch (assumes you are currently on the branch that has the changed files):
+
+ .. code-block:: bash
+
+ $ git diff --name-only master | egrep "\.c|\.h" | xargs echo | xargs ./tools/checkpatch.sh -f | less
+
+ Note that there are some bugs in the ``nxstyle`` program that ``checkpatch.sh`` uses, so
+ it may report a few errors that are not actually errors. The committers will help you
+ find these. (Or view the
+ `nxstyle Issues <https://github.com/apache/incubator-nuttx/issues?q=is%3Aissue+is%3Aopen+nxstyle>`_.)
+ |br|
+ |br|
+
+#. Commit the fixed files
+
+ .. code-block:: bash
+
+ $ git add my-file.c
+ $ git commit my-file.c
+ $ git push
+
+
+Submitting Your Changes to NuttX
+--------------------------------
+
+ Pull requests let you tell others about changes you've pushed to a branch in a repository on GitHub. Once a pull
+ request is opened, you can discuss and review the potential changes with collaborators and add follow-up commits
+ before your changes are merged into the base branch.
+
+ (from GitHub's `About pull requests <https://docs.github.com/en/github/collaborating-with-issues-and-pull-requests/about-pull-requests>`_ page)
+
+Before you do a Pull Request, the NuttX team will usually want all the changes you made in your branch "squashed" into
+a single commit, so that when they review your changes, there's a clean view of the history. If there are changes
+after Pull Request review feedback, they can be separate commits. Here's the easiest way I found to do that initial
+squash before submitting the Pull Request:
+
+#. Check out my branch
+
+ .. code-block:: bash
+
+ $ git checkout my-branch
+
+#. Rename it to ``my-branch-old`` to save it, because we're going to create new clean branch to push:
+
+ .. code-block:: bash
+
+ $ git branch -m my-branch-old
+
+#. Create a new clean branch with the same name you were using before the last step:
+
+ .. code-block:: bash
+
+ $ git checkout master
+ $ git checkout -b my-branch
+
+#. Merge your saved old branch into the new one, telling git to "squash" all your commits into one (note this will
+ not commit the result; the changed files will be in your staging area, ready to be committed):
+
+ .. code-block:: bash
+
+ $ git merge --squash my-branch-old
+
+#. Commit the result
+
+ .. code-block:: bash
+
+ $ git commit
+
+#. Force-push your new clean branch to the remote— this will overwrite all your previous changes in that branch:
+
+ .. code-block:: bash
+
+ $ git push -f --set-upstream origin my-branch
+
+#. Create a GitHub Pull Request
+
+ A Pull Request is how you ask your upstream to review and merge your changes.
+
+ Here's `GitHub's instructions for creating a Pull Request <https://help.github.com/en/github/collaborating-with-issues-and-pull-requests/creating-a-pull-request>`_.
+
+ |br|
+
+#. Get Pull Request feedback and implement changes
+
+ Get suggestions for improvements from reviewers, make changes, and push them to the branch. Once the reviewers are
+ happy, they may suggest squashing and merging again to make a single commit. In this case you would repeat steps
+ 1 through 6.
+
+Git Resources
+-------------
+
+* `Git Cheat Sheet (by GitHub) <https://github.github.com/training-kit/downloads/github-git-cheat-sheet.pdf>`_
+* `Git Book (online) <https://git-scm.com/book/en/v2>`_
+* `NuttX Code Contribution Workflow <https://cwiki.apache.org/confluence/display/NUTTX/Code+Contribution+Workflow>`_ –
Review comment:
I'm not sure if we should point to the wiki here. Once the workflow is established it should be part of this documentation. For now I think the very brief "workflow" section of the docs is enough until we do so.
----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [incubator-nuttx] Ouss4 commented on a change in pull request #1677: Add Simulator and Drivers guides, and contributing instructions for new users
Posted by GitBox <gi...@apache.org>.
Ouss4 commented on a change in pull request #1677:
URL: https://github.com/apache/incubator-nuttx/pull/1677#discussion_r480228124
##########
File path: Documentation/contributing/making-changes.rst
##########
@@ -0,0 +1,256 @@
+.. include:: /substitutions.rst
+.. _making-changes:
+
+Making Changes
+==============
+
+If you want to make changes to NuttX, for your own personal use, or to submit them back to project to improve NuttX,
+that's easy. For the purposes of this guide, you'll need a `GitHub <https://www.github.com>`_ account, since
+the Apache NuttX team uses GitHub. (You could also use git locally, or save your changes to other sites like
+`GitLab <https://about.gitlab.com/>`_ or `BitBucket <https://bitbucket.org>`_, but that's beyond the scope of this
+guide).
+
+Here's how to do it:
+
+#. Set your git user name and email
+
+ .. code-block:: bash
+
+ $ cd nuttx/
+ $ git config --global user.name "Your Name"
+ $ git config --global user.email "yourname@somedomaincom"
+
+#. Sign in to GitHub
+
+ If you don't have a `GitHub <https://www.github.com>`_ account, it's free to
+ sign up.
+ |br|
+ |br|
+
+
+#. Fork the Project
+
+ Visit both these links and hit the Fork button in the upper right of the page:
+
+ * `NuttX <https://github.com/apache/incubator-nuttx/>`_
+ * `NuttX Apps <https://github.com/apache/incubator-nuttx-apps/>`_
+
+
+#. Change the Git Remotes
+
+ The git repositories in your project are currently connected to the official NuttX repositories, but you don't
+ have permission to push software there. But you can push them to your forks, and from there create Pull Requests
+ if you want to send them to the NuttX project.
+
+ First, remove the current remote, ``origin`` (we'll add it back later):
+
+ .. code-block:: bash
+
+ $ cd nuttx/
+ $ # display the remote
+ $ git remote -v
+
+ You should see something like this:
+
+ .. code-block:: bash
+
+ origin https://github.com/apache/incubator-nuttx.git
+
+ Now, on the GitHub web page for your forked ``incubator-nuttx`` project, copy the clone url – get it by hitting the
+ green ``Clone or Download`` button in the upper right. Then do this:
+
+ .. code-block:: bash
+
+ $ git remote rm origin
+ $ git remote add origin <your forked incubator-nuttx project clone url>
+ $ git remote add upstream https://github.com/apache/incubator-nuttx.git
Review comment:
BTW, where is git clone mentioned? I can't find it.
> Also note, that there is set-url to change remote url.
and `git remote rename` to change the name of the remove and leave the url as is.
----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [incubator-nuttx] btashton commented on a change in pull request #1677: Add Simulator and Drivers guides, and contributing instructions for new users
Posted by GitBox <gi...@apache.org>.
btashton commented on a change in pull request #1677:
URL: https://github.com/apache/incubator-nuttx/pull/1677#discussion_r480274417
##########
File path: Documentation/contributing/making-changes.rst
##########
@@ -0,0 +1,256 @@
+.. include:: /substitutions.rst
+.. _making-changes:
+
+Making Changes
+==============
+
+If you want to make changes to NuttX, for your own personal use, or to submit them back to project to improve NuttX,
+that's easy. For the purposes of this guide, you'll need a `GitHub <https://www.github.com>`_ account, since
+the Apache NuttX team uses GitHub. (You could also use git locally, or save your changes to other sites like
+`GitLab <https://about.gitlab.com/>`_ or `BitBucket <https://bitbucket.org>`_, but that's beyond the scope of this
+guide).
+
+Here's how to do it:
+
+#. Set your git user name and email
+
+ .. code-block:: bash
+
+ $ cd nuttx/
+ $ git config --global user.name "Your Name"
+ $ git config --global user.email "yourname@somedomaincom"
+
+#. Sign in to GitHub
+
+ If you don't have a `GitHub <https://www.github.com>`_ account, it's free to
+ sign up.
+ |br|
+ |br|
+
+
+#. Fork the Project
+
+ Visit both these links and hit the Fork button in the upper right of the page:
+
+ * `NuttX <https://github.com/apache/incubator-nuttx/>`_
+ * `NuttX Apps <https://github.com/apache/incubator-nuttx-apps/>`_
+
+
+#. Change the Git Remotes
+
+ The git repositories in your project are currently connected to the official NuttX repositories, but you don't
+ have permission to push software there. But you can push them to your forks, and from there create Pull Requests
+ if you want to send them to the NuttX project.
+
+ First, remove the current remote, ``origin`` (we'll add it back later):
+
+ .. code-block:: bash
+
+ $ cd nuttx/
+ $ # display the remote
+ $ git remote -v
+
+ You should see something like this:
+
+ .. code-block:: bash
+
+ origin https://github.com/apache/incubator-nuttx.git
+
+ Now, on the GitHub web page for your forked ``incubator-nuttx`` project, copy the clone url – get it by hitting the
+ green ``Clone or Download`` button in the upper right. Then do this:
+
+ .. code-block:: bash
+
+ $ git remote rm origin
+ $ git remote add origin <your forked incubator-nuttx project clone url>
+ $ git remote add upstream https://github.com/apache/incubator-nuttx.git
+
+ Do the same for your forked ``incubator-nuttx-apps`` project:
+
+ .. code-block:: bash
+
+ $ cd ../apps
+ $ git remote rm origin
+ $ git remote add origin <your forked incubator-nuttx-apps project clone url>
+ $ git remote add upstream https://github.com/apache/incubator-nuttx-apps.git
+
+
+#. Create a Local Git Branch
+
+ Now you can create local git branches and push them to GitHub:
+
+ .. code-block:: bash
+
+ $ git checkout -b test/my-new-branch
+ $ git push
+
+
+Git Workflow With an Upstream Repository
+----------------------------------------
+
+The main NuttX git repository is called an "upstream" repository - this is because it's the main source of truth, and
+its changes flow downstream to people who've forked that repository, like us.
+
+Working with an upstream repo is a bit more complex, but it's worth it since you can submit fixes and features
+to the main NuttX repos. One of the things you need to do regularly is keep your local repo in sync
+with the upstream. I work with a local branch, make changes, pull new software from the upstream and merge it in,
+maybe doing that several times. Then when everything works, I get my branch ready to do a Pull Request. Here's how:
+
+#. Fetch upstream changes and merge into my local master:
+
+ .. code-block:: bash
+
+ $ git checkout master
+ $ git fetch upstream
+ $ git merge upstream/master
+ $ git push
+
+#. Merge my local master with my local branch:
+
+ .. code-block:: bash
+
+ $ git checkout my-local-branch
+ $ git merge master
+ $ git push
Review comment:
> I said a range _from the HEAD_. I didn't mean that HEAD ~ N is a range. HEAD~N is the Nth commit behind HEAD.
> The current branch's top commit is HEAD.
> When you are "checkedout" to master and you do `git rebase -i master`, that means you are trying to rebase from HEAD to HEAD, thus the "noop".
No you are on your branch and interactive rebase against master. This will show all your commits in the interactive flow.
----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [incubator-nuttx] v01d commented on a change in pull request #1677: Add Simulator and Drivers guides, and contributing instructions for new users
Posted by GitBox <gi...@apache.org>.
v01d commented on a change in pull request #1677:
URL: https://github.com/apache/incubator-nuttx/pull/1677#discussion_r480271048
##########
File path: Documentation/contributing/making-changes.rst
##########
@@ -0,0 +1,256 @@
+.. include:: /substitutions.rst
+.. _making-changes:
+
+Making Changes
+==============
+
+If you want to make changes to NuttX, for your own personal use, or to submit them back to project to improve NuttX,
+that's easy. For the purposes of this guide, you'll need a `GitHub <https://www.github.com>`_ account, since
+the Apache NuttX team uses GitHub. (You could also use git locally, or save your changes to other sites like
+`GitLab <https://about.gitlab.com/>`_ or `BitBucket <https://bitbucket.org>`_, but that's beyond the scope of this
+guide).
+
+Here's how to do it:
+
+#. Set your git user name and email
+
+ .. code-block:: bash
+
+ $ cd nuttx/
+ $ git config --global user.name "Your Name"
+ $ git config --global user.email "yourname@somedomaincom"
+
+#. Sign in to GitHub
+
+ If you don't have a `GitHub <https://www.github.com>`_ account, it's free to
+ sign up.
+ |br|
+ |br|
+
+
+#. Fork the Project
+
+ Visit both these links and hit the Fork button in the upper right of the page:
+
+ * `NuttX <https://github.com/apache/incubator-nuttx/>`_
+ * `NuttX Apps <https://github.com/apache/incubator-nuttx-apps/>`_
+
+
+#. Change the Git Remotes
+
+ The git repositories in your project are currently connected to the official NuttX repositories, but you don't
+ have permission to push software there. But you can push them to your forks, and from there create Pull Requests
+ if you want to send them to the NuttX project.
+
+ First, remove the current remote, ``origin`` (we'll add it back later):
+
+ .. code-block:: bash
+
+ $ cd nuttx/
+ $ # display the remote
+ $ git remote -v
+
+ You should see something like this:
+
+ .. code-block:: bash
+
+ origin https://github.com/apache/incubator-nuttx.git
+
+ Now, on the GitHub web page for your forked ``incubator-nuttx`` project, copy the clone url – get it by hitting the
+ green ``Clone or Download`` button in the upper right. Then do this:
+
+ .. code-block:: bash
+
+ $ git remote rm origin
+ $ git remote add origin <your forked incubator-nuttx project clone url>
+ $ git remote add upstream https://github.com/apache/incubator-nuttx.git
+
+ Do the same for your forked ``incubator-nuttx-apps`` project:
+
+ .. code-block:: bash
+
+ $ cd ../apps
+ $ git remote rm origin
+ $ git remote add origin <your forked incubator-nuttx-apps project clone url>
+ $ git remote add upstream https://github.com/apache/incubator-nuttx-apps.git
+
+
+#. Create a Local Git Branch
+
+ Now you can create local git branches and push them to GitHub:
+
+ .. code-block:: bash
+
+ $ git checkout -b test/my-new-branch
+ $ git push
+
+
+Git Workflow With an Upstream Repository
+----------------------------------------
+
+The main NuttX git repository is called an "upstream" repository - this is because it's the main source of truth, and
+its changes flow downstream to people who've forked that repository, like us.
+
+Working with an upstream repo is a bit more complex, but it's worth it since you can submit fixes and features
+to the main NuttX repos. One of the things you need to do regularly is keep your local repo in sync
+with the upstream. I work with a local branch, make changes, pull new software from the upstream and merge it in,
+maybe doing that several times. Then when everything works, I get my branch ready to do a Pull Request. Here's how:
+
+#. Fetch upstream changes and merge into my local master:
+
+ .. code-block:: bash
+
+ $ git checkout master
+ $ git fetch upstream
+ $ git merge upstream/master
+ $ git push
+
+#. Merge my local master with my local branch:
+
+ .. code-block:: bash
+
+ $ git checkout my-local-branch
+ $ git merge master
+ $ git push
Review comment:
`git rebase -i master` works the same. HEAD~N is just another way to reference a commit (it is not a range)
----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [incubator-nuttx] v01d commented on a change in pull request #1677: Add Simulator and Drivers guides, and contributing instructions for new users
Posted by GitBox <gi...@apache.org>.
v01d commented on a change in pull request #1677:
URL: https://github.com/apache/incubator-nuttx/pull/1677#discussion_r483851010
##########
File path: Documentation/guides/simulator.rst
##########
@@ -21,50 +23,100 @@ Compiling
There are a lot of simulator configurations available that set you up to test various
operating system features.
+ Here we'll use the ``sim:nsh`` basic NuttX Shell configuration.
+
Review comment:
Shouldn't there be a command line example below?
----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [incubator-nuttx] adamfeuer commented on a change in pull request #1677: Add Simulator and Drivers guides, and contributing instructions for new users
Posted by GitBox <gi...@apache.org>.
adamfeuer commented on a change in pull request #1677:
URL: https://github.com/apache/incubator-nuttx/pull/1677#discussion_r480232497
##########
File path: Documentation/contributing/making-changes.rst
##########
@@ -0,0 +1,256 @@
+.. include:: /substitutions.rst
+.. _making-changes:
+
+Making Changes
+==============
+
+If you want to make changes to NuttX, for your own personal use, or to submit them back to project to improve NuttX,
+that's easy. For the purposes of this guide, you'll need a `GitHub <https://www.github.com>`_ account, since
+the Apache NuttX team uses GitHub. (You could also use git locally, or save your changes to other sites like
+`GitLab <https://about.gitlab.com/>`_ or `BitBucket <https://bitbucket.org>`_, but that's beyond the scope of this
+guide).
+
+Here's how to do it:
+
+#. Set your git user name and email
+
+ .. code-block:: bash
+
+ $ cd nuttx/
+ $ git config --global user.name "Your Name"
+ $ git config --global user.email "yourname@somedomaincom"
+
+#. Sign in to GitHub
+
+ If you don't have a `GitHub <https://www.github.com>`_ account, it's free to
+ sign up.
+ |br|
+ |br|
+
+
+#. Fork the Project
+
+ Visit both these links and hit the Fork button in the upper right of the page:
+
+ * `NuttX <https://github.com/apache/incubator-nuttx/>`_
+ * `NuttX Apps <https://github.com/apache/incubator-nuttx-apps/>`_
+
+
+#. Change the Git Remotes
+
+ The git repositories in your project are currently connected to the official NuttX repositories, but you don't
+ have permission to push software there. But you can push them to your forks, and from there create Pull Requests
+ if you want to send them to the NuttX project.
+
+ First, remove the current remote, ``origin`` (we'll add it back later):
+
+ .. code-block:: bash
+
+ $ cd nuttx/
+ $ # display the remote
+ $ git remote -v
+
+ You should see something like this:
+
+ .. code-block:: bash
+
+ origin https://github.com/apache/incubator-nuttx.git
+
+ Now, on the GitHub web page for your forked ``incubator-nuttx`` project, copy the clone url – get it by hitting the
+ green ``Clone or Download`` button in the upper right. Then do this:
+
+ .. code-block:: bash
+
+ $ git remote rm origin
+ $ git remote add origin <your forked incubator-nuttx project clone url>
+ $ git remote add upstream https://github.com/apache/incubator-nuttx.git
+
+ Do the same for your forked ``incubator-nuttx-apps`` project:
+
+ .. code-block:: bash
+
+ $ cd ../apps
+ $ git remote rm origin
+ $ git remote add origin <your forked incubator-nuttx-apps project clone url>
+ $ git remote add upstream https://github.com/apache/incubator-nuttx-apps.git
+
+
+#. Create a Local Git Branch
+
+ Now you can create local git branches and push them to GitHub:
+
+ .. code-block:: bash
+
+ $ git checkout -b test/my-new-branch
+ $ git push
+
+
+Git Workflow With an Upstream Repository
+----------------------------------------
+
+The main NuttX git repository is called an "upstream" repository - this is because it's the main source of truth, and
+its changes flow downstream to people who've forked that repository, like us.
+
+Working with an upstream repo is a bit more complex, but it's worth it since you can submit fixes and features
+to the main NuttX repos. One of the things you need to do regularly is keep your local repo in sync
+with the upstream. I work with a local branch, make changes, pull new software from the upstream and merge it in,
+maybe doing that several times. Then when everything works, I get my branch ready to do a Pull Request. Here's how:
+
+#. Fetch upstream changes and merge into my local master:
+
+ .. code-block:: bash
+
+ $ git checkout master
+ $ git fetch upstream
+ $ git merge upstream/master
+ $ git push
+
+#. Merge my local master with my local branch:
+
+ .. code-block:: bash
+
+ $ git checkout my-local-branch
+ $ git merge master
+ $ git push
Review comment:
@Ouss4 Will you post the commands for the rebase flow that you are proposing?
----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [incubator-nuttx] adamfeuer commented on a change in pull request #1677: Add Simulator and Drivers guides, and contributing instructions for new users
Posted by GitBox <gi...@apache.org>.
adamfeuer commented on a change in pull request #1677:
URL: https://github.com/apache/incubator-nuttx/pull/1677#discussion_r483839878
##########
File path: Documentation/guides/simulator.rst
##########
@@ -0,0 +1,145 @@
+.. include:: /substitutions.rst
+.. _simulator:
+
+Simulator
+=========
+
+Apache NuttX has a simulator that can run as a regular program on Linux, Mac, and Windows computers.
+It's useful for debugging operating system features that aren't associated with particular
+device drivers— for instance the TCP/IP stack itself, a web interface or API for your
+application, or other communication protocols. It's also handy for trying out Apache NuttX without
+having a piece of embedded hardware.
+
+This guide assumes you're on Linux. It works on Windows and Mac too— if you know how,
+submit a PR the NuttX Companion to update this guide!
+
+Compiling
+---------
+
+#. Configure the Simulator
+
+ There are a lot of simulator configurations available that set you up to test various
+ operating system features.
+
+ Here we'll use the ``sim:tcpblaster`` configuration because it comes with networking
+ that is ready to use.
+
+ .. code-block:: bash
+
+ $ cd nuttx
+ $ ./tools/configure.sh sim:tcpblaster
Review comment:
@v01d will do that, ad will have the network as a second example.
----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [incubator-nuttx] Ouss4 commented on a change in pull request #1677: Add Simulator and Drivers guides, and contributing instructions for new users
Posted by GitBox <gi...@apache.org>.
Ouss4 commented on a change in pull request #1677:
URL: https://github.com/apache/incubator-nuttx/pull/1677#discussion_r480273344
##########
File path: Documentation/contributing/making-changes.rst
##########
@@ -0,0 +1,256 @@
+.. include:: /substitutions.rst
+.. _making-changes:
+
+Making Changes
+==============
+
+If you want to make changes to NuttX, for your own personal use, or to submit them back to project to improve NuttX,
+that's easy. For the purposes of this guide, you'll need a `GitHub <https://www.github.com>`_ account, since
+the Apache NuttX team uses GitHub. (You could also use git locally, or save your changes to other sites like
+`GitLab <https://about.gitlab.com/>`_ or `BitBucket <https://bitbucket.org>`_, but that's beyond the scope of this
+guide).
+
+Here's how to do it:
+
+#. Set your git user name and email
+
+ .. code-block:: bash
+
+ $ cd nuttx/
+ $ git config --global user.name "Your Name"
+ $ git config --global user.email "yourname@somedomaincom"
+
+#. Sign in to GitHub
+
+ If you don't have a `GitHub <https://www.github.com>`_ account, it's free to
+ sign up.
+ |br|
+ |br|
+
+
+#. Fork the Project
+
+ Visit both these links and hit the Fork button in the upper right of the page:
+
+ * `NuttX <https://github.com/apache/incubator-nuttx/>`_
+ * `NuttX Apps <https://github.com/apache/incubator-nuttx-apps/>`_
+
+
+#. Change the Git Remotes
+
+ The git repositories in your project are currently connected to the official NuttX repositories, but you don't
+ have permission to push software there. But you can push them to your forks, and from there create Pull Requests
+ if you want to send them to the NuttX project.
+
+ First, remove the current remote, ``origin`` (we'll add it back later):
+
+ .. code-block:: bash
+
+ $ cd nuttx/
+ $ # display the remote
+ $ git remote -v
+
+ You should see something like this:
+
+ .. code-block:: bash
+
+ origin https://github.com/apache/incubator-nuttx.git
+
+ Now, on the GitHub web page for your forked ``incubator-nuttx`` project, copy the clone url – get it by hitting the
+ green ``Clone or Download`` button in the upper right. Then do this:
+
+ .. code-block:: bash
+
+ $ git remote rm origin
+ $ git remote add origin <your forked incubator-nuttx project clone url>
+ $ git remote add upstream https://github.com/apache/incubator-nuttx.git
+
+ Do the same for your forked ``incubator-nuttx-apps`` project:
+
+ .. code-block:: bash
+
+ $ cd ../apps
+ $ git remote rm origin
+ $ git remote add origin <your forked incubator-nuttx-apps project clone url>
+ $ git remote add upstream https://github.com/apache/incubator-nuttx-apps.git
+
+
+#. Create a Local Git Branch
+
+ Now you can create local git branches and push them to GitHub:
+
+ .. code-block:: bash
+
+ $ git checkout -b test/my-new-branch
+ $ git push
+
+
+Git Workflow With an Upstream Repository
+----------------------------------------
+
+The main NuttX git repository is called an "upstream" repository - this is because it's the main source of truth, and
+its changes flow downstream to people who've forked that repository, like us.
+
+Working with an upstream repo is a bit more complex, but it's worth it since you can submit fixes and features
+to the main NuttX repos. One of the things you need to do regularly is keep your local repo in sync
+with the upstream. I work with a local branch, make changes, pull new software from the upstream and merge it in,
+maybe doing that several times. Then when everything works, I get my branch ready to do a Pull Request. Here's how:
+
+#. Fetch upstream changes and merge into my local master:
+
+ .. code-block:: bash
+
+ $ git checkout master
+ $ git fetch upstream
+ $ git merge upstream/master
+ $ git push
+
+#. Merge my local master with my local branch:
+
+ .. code-block:: bash
+
+ $ git checkout my-local-branch
+ $ git merge master
+ $ git push
Review comment:
I said a range _from the HEAD_. I didn't mean that HEAD~N is a range. HEAD~N is the Nth commit behind HEAD.
The current branch's top commit is HEAD.
When you are "checkedout" to master and you do `git rebase -i master`, that means you are trying to rebase from HEAD to HEAD, thus the "noop".
----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [incubator-nuttx] Ouss4 commented on a change in pull request #1677: Add Simulator and Drivers guides, and contributing instructions for new users
Posted by GitBox <gi...@apache.org>.
Ouss4 commented on a change in pull request #1677:
URL: https://github.com/apache/incubator-nuttx/pull/1677#discussion_r480230025
##########
File path: Documentation/contributing/making-changes.rst
##########
@@ -0,0 +1,256 @@
+.. include:: /substitutions.rst
+.. _making-changes:
+
+Making Changes
+==============
+
+If you want to make changes to NuttX, for your own personal use, or to submit them back to project to improve NuttX,
+that's easy. For the purposes of this guide, you'll need a `GitHub <https://www.github.com>`_ account, since
+the Apache NuttX team uses GitHub. (You could also use git locally, or save your changes to other sites like
+`GitLab <https://about.gitlab.com/>`_ or `BitBucket <https://bitbucket.org>`_, but that's beyond the scope of this
+guide).
+
+Here's how to do it:
+
+#. Set your git user name and email
+
+ .. code-block:: bash
+
+ $ cd nuttx/
+ $ git config --global user.name "Your Name"
+ $ git config --global user.email "yourname@somedomaincom"
+
+#. Sign in to GitHub
+
+ If you don't have a `GitHub <https://www.github.com>`_ account, it's free to
+ sign up.
+ |br|
+ |br|
+
+
+#. Fork the Project
+
+ Visit both these links and hit the Fork button in the upper right of the page:
+
+ * `NuttX <https://github.com/apache/incubator-nuttx/>`_
+ * `NuttX Apps <https://github.com/apache/incubator-nuttx-apps/>`_
+
+
+#. Change the Git Remotes
+
+ The git repositories in your project are currently connected to the official NuttX repositories, but you don't
+ have permission to push software there. But you can push them to your forks, and from there create Pull Requests
+ if you want to send them to the NuttX project.
+
+ First, remove the current remote, ``origin`` (we'll add it back later):
+
+ .. code-block:: bash
+
+ $ cd nuttx/
+ $ # display the remote
+ $ git remote -v
+
+ You should see something like this:
+
+ .. code-block:: bash
+
+ origin https://github.com/apache/incubator-nuttx.git
+
+ Now, on the GitHub web page for your forked ``incubator-nuttx`` project, copy the clone url – get it by hitting the
+ green ``Clone or Download`` button in the upper right. Then do this:
+
+ .. code-block:: bash
+
+ $ git remote rm origin
+ $ git remote add origin <your forked incubator-nuttx project clone url>
+ $ git remote add upstream https://github.com/apache/incubator-nuttx.git
+
+ Do the same for your forked ``incubator-nuttx-apps`` project:
+
+ .. code-block:: bash
+
+ $ cd ../apps
+ $ git remote rm origin
+ $ git remote add origin <your forked incubator-nuttx-apps project clone url>
+ $ git remote add upstream https://github.com/apache/incubator-nuttx-apps.git
+
+
+#. Create a Local Git Branch
+
+ Now you can create local git branches and push them to GitHub:
+
+ .. code-block:: bash
+
+ $ git checkout -b test/my-new-branch
+ $ git push
+
+
+Git Workflow With an Upstream Repository
+----------------------------------------
+
+The main NuttX git repository is called an "upstream" repository - this is because it's the main source of truth, and
+its changes flow downstream to people who've forked that repository, like us.
+
+Working with an upstream repo is a bit more complex, but it's worth it since you can submit fixes and features
+to the main NuttX repos. One of the things you need to do regularly is keep your local repo in sync
+with the upstream. I work with a local branch, make changes, pull new software from the upstream and merge it in,
+maybe doing that several times. Then when everything works, I get my branch ready to do a Pull Request. Here's how:
+
+#. Fetch upstream changes and merge into my local master:
+
+ .. code-block:: bash
+
+ $ git checkout master
+ $ git fetch upstream
+ $ git merge upstream/master
+ $ git push
+
+#. Merge my local master with my local branch:
+
+ .. code-block:: bash
+
+ $ git checkout my-local-branch
+ $ git merge master
+ $ git push
Review comment:
This also is better with a rebase, as merge could create merge commits.
----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [incubator-nuttx] adamfeuer commented on a change in pull request #1677: Add Simulator and Drivers guides, and contributing instructions for new users
Posted by GitBox <gi...@apache.org>.
adamfeuer commented on a change in pull request #1677:
URL: https://github.com/apache/incubator-nuttx/pull/1677#discussion_r483853614
##########
File path: Documentation/contributing/making-changes.rst
##########
@@ -202,6 +202,56 @@ squash before submitting the Pull Request:
$ git checkout my-branch
+#. Fetch the upstream code
+
+ .. code-block:: bash
+
+ $ git fetch upstream
+
+#. Rebase onto the upstream code
+
+ * Your favorite text editor will start and shows the commands for the interactive rebasing.
+ * Change the "pick" to "squash" for all the commits you want to squash.
+ * For the series of commits to squash, keep the first one with "pick".
+ * Once you save and exist your editor will start again to merge all the commit messages.
+ * Add a commit message that best describes your change then save and exit.
Review comment:
@v01d I'll delete this text.
----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [incubator-nuttx] adamfeuer commented on a change in pull request #1677: Add Simulator and Drivers guides, and contributing instructions for new users
Posted by GitBox <gi...@apache.org>.
adamfeuer commented on a change in pull request #1677:
URL: https://github.com/apache/incubator-nuttx/pull/1677#discussion_r483849878
##########
File path: Documentation/contributing/making-changes.rst
##########
@@ -0,0 +1,256 @@
+.. include:: /substitutions.rst
+.. _making-changes:
+
+Making Changes
+==============
+
+If you want to make changes to NuttX, for your own personal use, or to submit them back to project to improve NuttX,
+that's easy. For the purposes of this guide, you'll need a `GitHub <https://www.github.com>`_ account, since
+the Apache NuttX team uses GitHub. (You could also use git locally, or save your changes to other sites like
+`GitLab <https://about.gitlab.com/>`_ or `BitBucket <https://bitbucket.org>`_, but that's beyond the scope of this
+guide).
+
+Here's how to do it:
+
+#. Set your git user name and email
+
+ .. code-block:: bash
+
+ $ cd nuttx/
+ $ git config --global user.name "Your Name"
+ $ git config --global user.email "yourname@somedomaincom"
+
+#. Sign in to GitHub
+
+ If you don't have a `GitHub <https://www.github.com>`_ account, it's free to
+ sign up.
+ |br|
+ |br|
+
+
+#. Fork the Project
+
+ Visit both these links and hit the Fork button in the upper right of the page:
+
+ * `NuttX <https://github.com/apache/incubator-nuttx/>`_
+ * `NuttX Apps <https://github.com/apache/incubator-nuttx-apps/>`_
+
+
+#. Change the Git Remotes
+
+ The git repositories in your project are currently connected to the official NuttX repositories, but you don't
+ have permission to push software there. But you can push them to your forks, and from there create Pull Requests
+ if you want to send them to the NuttX project.
+
+ First, remove the current remote, ``origin`` (we'll add it back later):
+
+ .. code-block:: bash
+
+ $ cd nuttx/
+ $ # display the remote
+ $ git remote -v
+
+ You should see something like this:
+
+ .. code-block:: bash
+
+ origin https://github.com/apache/incubator-nuttx.git
+
+ Now, on the GitHub web page for your forked ``incubator-nuttx`` project, copy the clone url – get it by hitting the
+ green ``Clone or Download`` button in the upper right. Then do this:
+
+ .. code-block:: bash
+
+ $ git remote rm origin
+ $ git remote add origin <your forked incubator-nuttx project clone url>
+ $ git remote add upstream https://github.com/apache/incubator-nuttx.git
+
+ Do the same for your forked ``incubator-nuttx-apps`` project:
+
+ .. code-block:: bash
+
+ $ cd ../apps
+ $ git remote rm origin
+ $ git remote add origin <your forked incubator-nuttx-apps project clone url>
+ $ git remote add upstream https://github.com/apache/incubator-nuttx-apps.git
+
+
+#. Create a Local Git Branch
+
+ Now you can create local git branches and push them to GitHub:
+
+ .. code-block:: bash
+
+ $ git checkout -b test/my-new-branch
+ $ git push
+
+
+Git Workflow With an Upstream Repository
+----------------------------------------
+
+The main NuttX git repository is called an "upstream" repository - this is because it's the main source of truth, and
+its changes flow downstream to people who've forked that repository, like us.
+
+Working with an upstream repo is a bit more complex, but it's worth it since you can submit fixes and features
+to the main NuttX repos. One of the things you need to do regularly is keep your local repo in sync
+with the upstream. I work with a local branch, make changes, pull new software from the upstream and merge it in,
+maybe doing that several times. Then when everything works, I get my branch ready to do a Pull Request. Here's how:
+
+#. Fetch upstream changes and merge into my local master:
+
+ .. code-block:: bash
+
+ $ git checkout master
+ $ git fetch upstream
+ $ git merge upstream/master
+ $ git push
+
+#. Merge my local master with my local branch:
+
+ .. code-block:: bash
+
+ $ git checkout my-local-branch
+ $ git merge master
+ $ git push
+
+#. Make changes and push them to my fork
+
+ .. code-block:: bash
+
+ $ vim my-file.c
+ $ git add my-file.c
+ $ git commit my-file.c
+ $ git push
+
+#. Repeat 1-3 as necessary
+
+#. Run the ``tools/checkpatch.sh`` script on your files
+
+ When your code runs, then you're almost ready to submit it. But first you need to check the code to ensure
+ that it conforms to the NuttX :ref:`contributing/coding_style:C Coding Standard`.
+ The ``tools/checkpatch.sh`` script will do that. Here's the usage info:
+
+ .. code-block:: bash
+
+ $ ./tools/checkpatch.sh -h
+ USAGE: ./tools/checkpatch.sh [options] [list|-]
+
+ Options:
+ -h
+ -c spell check with codespell(install with: pip install codespell
+ -r range check only (used with -p and -g)
+ -p <patch list> (default)
+ -g <commit list>
+ -f <file list>
+ - read standard input mainly used by git pre-commit hook as below:
+ git diff --cached | ./tools/checkpatch.sh -
+
+ Run it against your files and correct all the errors in the code you added, so that
+ ``tools/checkpatch.sh`` reports no errors. Then commit the result.
+ For example:
+
+ .. code-block:: bash
+
+ $ ./tools/checkpatch.sh -f my-file.c
+ arch/arm/src/sama5/hardware/my-file.c:876:82: warning: Long line found
+ $ # fix errors
+ $ vim my-file.c
+ $ # run again
+ $ ./tools/checkpatch.sh -f my-file.c
+
+ If you have made a lot of changes, you can also use this bash commandline to see the errors for all the changed C
+ files in your branch (assumes you are currently on the branch that has the changed files):
+
+ .. code-block:: bash
+
+ $ git diff --name-only master | egrep "\.c|\.h" | xargs echo | xargs ./tools/checkpatch.sh -f | less
+
+ Note that there are some bugs in the ``nxstyle`` program that ``checkpatch.sh`` uses, so
+ it may report a few errors that are not actually errors. The committers will help you
+ find these. (Or view the
+ `nxstyle Issues <https://github.com/apache/incubator-nuttx/issues?q=is%3Aissue+is%3Aopen+nxstyle>`_.)
+ |br|
+ |br|
+
+#. Commit the fixed files
+
+ .. code-block:: bash
+
+ $ git add my-file.c
+ $ git commit my-file.c
+ $ git push
+
+
+Submitting Your Changes to NuttX
+--------------------------------
+
+ Pull requests let you tell others about changes you've pushed to a branch in a repository on GitHub. Once a pull
+ request is opened, you can discuss and review the potential changes with collaborators and add follow-up commits
+ before your changes are merged into the base branch.
+
+ (from GitHub's `About pull requests <https://docs.github.com/en/github/collaborating-with-issues-and-pull-requests/about-pull-requests>`_ page)
+
+Before you do a Pull Request, the NuttX team will usually want all the changes you made in your branch "squashed" into
+a single commit, so that when they review your changes, there's a clean view of the history. If there are changes
+after Pull Request review feedback, they can be separate commits. Here's the easiest way I found to do that initial
+squash before submitting the Pull Request:
+
+#. Check out my branch
+
+ .. code-block:: bash
+
+ $ git checkout my-branch
+
+#. Rename it to ``my-branch-old`` to save it, because we're going to create new clean branch to push:
+
+ .. code-block:: bash
+
+ $ git branch -m my-branch-old
Review comment:
@Ouss4 @btashton I got the rebase flow out of the other comment block, so you don't need to do anything.
----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [incubator-nuttx] Ouss4 commented on a change in pull request #1677: Add Simulator and Drivers guides, and contributing instructions for new users
Posted by GitBox <gi...@apache.org>.
Ouss4 commented on a change in pull request #1677:
URL: https://github.com/apache/incubator-nuttx/pull/1677#discussion_r480230025
##########
File path: Documentation/contributing/making-changes.rst
##########
@@ -0,0 +1,256 @@
+.. include:: /substitutions.rst
+.. _making-changes:
+
+Making Changes
+==============
+
+If you want to make changes to NuttX, for your own personal use, or to submit them back to project to improve NuttX,
+that's easy. For the purposes of this guide, you'll need a `GitHub <https://www.github.com>`_ account, since
+the Apache NuttX team uses GitHub. (You could also use git locally, or save your changes to other sites like
+`GitLab <https://about.gitlab.com/>`_ or `BitBucket <https://bitbucket.org>`_, but that's beyond the scope of this
+guide).
+
+Here's how to do it:
+
+#. Set your git user name and email
+
+ .. code-block:: bash
+
+ $ cd nuttx/
+ $ git config --global user.name "Your Name"
+ $ git config --global user.email "yourname@somedomaincom"
+
+#. Sign in to GitHub
+
+ If you don't have a `GitHub <https://www.github.com>`_ account, it's free to
+ sign up.
+ |br|
+ |br|
+
+
+#. Fork the Project
+
+ Visit both these links and hit the Fork button in the upper right of the page:
+
+ * `NuttX <https://github.com/apache/incubator-nuttx/>`_
+ * `NuttX Apps <https://github.com/apache/incubator-nuttx-apps/>`_
+
+
+#. Change the Git Remotes
+
+ The git repositories in your project are currently connected to the official NuttX repositories, but you don't
+ have permission to push software there. But you can push them to your forks, and from there create Pull Requests
+ if you want to send them to the NuttX project.
+
+ First, remove the current remote, ``origin`` (we'll add it back later):
+
+ .. code-block:: bash
+
+ $ cd nuttx/
+ $ # display the remote
+ $ git remote -v
+
+ You should see something like this:
+
+ .. code-block:: bash
+
+ origin https://github.com/apache/incubator-nuttx.git
+
+ Now, on the GitHub web page for your forked ``incubator-nuttx`` project, copy the clone url – get it by hitting the
+ green ``Clone or Download`` button in the upper right. Then do this:
+
+ .. code-block:: bash
+
+ $ git remote rm origin
+ $ git remote add origin <your forked incubator-nuttx project clone url>
+ $ git remote add upstream https://github.com/apache/incubator-nuttx.git
+
+ Do the same for your forked ``incubator-nuttx-apps`` project:
+
+ .. code-block:: bash
+
+ $ cd ../apps
+ $ git remote rm origin
+ $ git remote add origin <your forked incubator-nuttx-apps project clone url>
+ $ git remote add upstream https://github.com/apache/incubator-nuttx-apps.git
+
+
+#. Create a Local Git Branch
+
+ Now you can create local git branches and push them to GitHub:
+
+ .. code-block:: bash
+
+ $ git checkout -b test/my-new-branch
+ $ git push
+
+
+Git Workflow With an Upstream Repository
+----------------------------------------
+
+The main NuttX git repository is called an "upstream" repository - this is because it's the main source of truth, and
+its changes flow downstream to people who've forked that repository, like us.
+
+Working with an upstream repo is a bit more complex, but it's worth it since you can submit fixes and features
+to the main NuttX repos. One of the things you need to do regularly is keep your local repo in sync
+with the upstream. I work with a local branch, make changes, pull new software from the upstream and merge it in,
+maybe doing that several times. Then when everything works, I get my branch ready to do a Pull Request. Here's how:
+
+#. Fetch upstream changes and merge into my local master:
+
+ .. code-block:: bash
+
+ $ git checkout master
+ $ git fetch upstream
+ $ git merge upstream/master
+ $ git push
+
+#. Merge my local master with my local branch:
+
+ .. code-block:: bash
+
+ $ git checkout my-local-branch
+ $ git merge master
+ $ git push
Review comment:
This also is better with a rebase.
----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [incubator-nuttx] adamfeuer commented on pull request #1677: Add Simulator and Drivers guides, and contributing instructions for new users
Posted by GitBox <gi...@apache.org>.
adamfeuer commented on pull request #1677:
URL: https://github.com/apache/incubator-nuttx/pull/1677#issuecomment-687438418
@btashton Yeah, rich diff for rst is cool. Thanks, I didn't know about that.
----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [incubator-nuttx] adamfeuer commented on a change in pull request #1677: Add Simulator and Drivers guides, and contributing instructions for new users
Posted by GitBox <gi...@apache.org>.
adamfeuer commented on a change in pull request #1677:
URL: https://github.com/apache/incubator-nuttx/pull/1677#discussion_r483873851
##########
File path: Documentation/guides/drivers.rst
##########
@@ -0,0 +1,211 @@
+.. include:: /substitutions.rst
+.. _drivers:
+
+Drivers
+=======
+
+Some NuttX boards don't have full support for all the on-chip peripherals. If you need support for this hardware,
+you will either need to port a driver from another chip, or write one yourself. This section discusses how to do that.
+
+Porting a Driver
+----------------
+
+Often support for on-chip peripherals exists in a closely related chip, or even a different family or from a different
+manufacturer. Many chips are made up of different Intellectual Property (IP) blocks that are licensed from vendors like
+Cadence, Synopsys, and others. The IP blocks may be similar enough to use another chip's driver with little
+modification.
+
+* Find a similar driver in NuttX source code:
+
+ * Look at register names listed in the datasheet for the peripheral.
+ * Search the NuttX codebase for the register names (try several different ones).
+ * Note that you'll have to compare the datasheet to the header and code files to see if there are differences; there
+ will usually be some differences between architectures, and they can be significant.
+
+* Find a similar driver in U-Boot source code:
+
+ * Only for inspiration, you can't copy code because of license incompatibility.
+ * But you can debug to see how the driver works.
+ * `U-Boot <https://www.denx.de/wiki/U-Boot>`_ drivers are often easier to understand than BSD Unix drivers because
+ U-Boot is simpler.
+
+* Find a similar driver in Zephyr or BSD Unix (OpenBSD, FreeBSD, NetBSD):
+
+ * If you find one, you can borrow code directly (Apache 2.0 and BSD licenses are compatible).
Review comment:
@btashton Ok, took it out, and stated that code from other projects can only be used for inspiration, not copied, unless there is an SGA for it on file from the authors.
----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [incubator-nuttx] btashton commented on a change in pull request #1677: Add Simulator and Drivers guides, and contributing instructions for new users
Posted by GitBox <gi...@apache.org>.
btashton commented on a change in pull request #1677:
URL: https://github.com/apache/incubator-nuttx/pull/1677#discussion_r480273670
##########
File path: Documentation/contributing/making-changes.rst
##########
@@ -0,0 +1,256 @@
+.. include:: /substitutions.rst
+.. _making-changes:
+
+Making Changes
+==============
+
+If you want to make changes to NuttX, for your own personal use, or to submit them back to project to improve NuttX,
+that's easy. For the purposes of this guide, you'll need a `GitHub <https://www.github.com>`_ account, since
+the Apache NuttX team uses GitHub. (You could also use git locally, or save your changes to other sites like
+`GitLab <https://about.gitlab.com/>`_ or `BitBucket <https://bitbucket.org>`_, but that's beyond the scope of this
+guide).
+
+Here's how to do it:
+
+#. Set your git user name and email
+
+ .. code-block:: bash
+
+ $ cd nuttx/
+ $ git config --global user.name "Your Name"
+ $ git config --global user.email "yourname@somedomaincom"
+
+#. Sign in to GitHub
+
+ If you don't have a `GitHub <https://www.github.com>`_ account, it's free to
+ sign up.
+ |br|
+ |br|
+
+
+#. Fork the Project
+
+ Visit both these links and hit the Fork button in the upper right of the page:
+
+ * `NuttX <https://github.com/apache/incubator-nuttx/>`_
+ * `NuttX Apps <https://github.com/apache/incubator-nuttx-apps/>`_
+
+
+#. Change the Git Remotes
+
+ The git repositories in your project are currently connected to the official NuttX repositories, but you don't
+ have permission to push software there. But you can push them to your forks, and from there create Pull Requests
+ if you want to send them to the NuttX project.
+
+ First, remove the current remote, ``origin`` (we'll add it back later):
+
+ .. code-block:: bash
+
+ $ cd nuttx/
+ $ # display the remote
+ $ git remote -v
+
+ You should see something like this:
+
+ .. code-block:: bash
+
+ origin https://github.com/apache/incubator-nuttx.git
+
+ Now, on the GitHub web page for your forked ``incubator-nuttx`` project, copy the clone url – get it by hitting the
+ green ``Clone or Download`` button in the upper right. Then do this:
+
+ .. code-block:: bash
+
+ $ git remote rm origin
+ $ git remote add origin <your forked incubator-nuttx project clone url>
+ $ git remote add upstream https://github.com/apache/incubator-nuttx.git
+
+ Do the same for your forked ``incubator-nuttx-apps`` project:
+
+ .. code-block:: bash
+
+ $ cd ../apps
+ $ git remote rm origin
+ $ git remote add origin <your forked incubator-nuttx-apps project clone url>
+ $ git remote add upstream https://github.com/apache/incubator-nuttx-apps.git
+
+
+#. Create a Local Git Branch
+
+ Now you can create local git branches and push them to GitHub:
+
+ .. code-block:: bash
+
+ $ git checkout -b test/my-new-branch
+ $ git push
+
+
+Git Workflow With an Upstream Repository
+----------------------------------------
+
+The main NuttX git repository is called an "upstream" repository - this is because it's the main source of truth, and
+its changes flow downstream to people who've forked that repository, like us.
+
+Working with an upstream repo is a bit more complex, but it's worth it since you can submit fixes and features
+to the main NuttX repos. One of the things you need to do regularly is keep your local repo in sync
+with the upstream. I work with a local branch, make changes, pull new software from the upstream and merge it in,
+maybe doing that several times. Then when everything works, I get my branch ready to do a Pull Request. Here's how:
+
+#. Fetch upstream changes and merge into my local master:
+
+ .. code-block:: bash
+
+ $ git checkout master
+ $ git fetch upstream
+ $ git merge upstream/master
+ $ git push
+
+#. Merge my local master with my local branch:
+
+ .. code-block:: bash
+
+ $ git checkout my-local-branch
+ $ git merge master
+ $ git push
Review comment:
> `git rebase -i master` works the same. HEAD~N is just another way to reference a commit (it is not a range)
Exactly `rev-list` is doing what rebase it already doing when given a branch name.
----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [incubator-nuttx] v01d commented on a change in pull request #1677: Add Simulator and Drivers guides, and contributing instructions for new users
Posted by GitBox <gi...@apache.org>.
v01d commented on a change in pull request #1677:
URL: https://github.com/apache/incubator-nuttx/pull/1677#discussion_r480192528
##########
File path: Documentation/guides/simulator.rst
##########
@@ -0,0 +1,145 @@
+.. include:: /substitutions.rst
+.. _simulator:
+
+Simulator
+=========
+
+Apache NuttX has a simulator that can run as a regular program on Linux, Mac, and Windows computers.
+It's useful for debugging operating system features that aren't associated with particular
+device drivers— for instance the TCP/IP stack itself, a web interface or API for your
+application, or other communication protocols. It's also handy for trying out Apache NuttX without
+having a piece of embedded hardware.
+
+This guide assumes you're on Linux. It works on Windows and Mac too— if you know how,
+submit a PR the NuttX Companion to update this guide!
Review comment:
Reference to companion here. Use "todo" for missing instructions.
----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [incubator-nuttx] adamfeuer commented on a change in pull request #1677: Add Simulator and Drivers guides, and contributing instructions for new users
Posted by GitBox <gi...@apache.org>.
adamfeuer commented on a change in pull request #1677:
URL: https://github.com/apache/incubator-nuttx/pull/1677#discussion_r483840986
##########
File path: Documentation/guides/simulator.rst
##########
@@ -0,0 +1,145 @@
+.. include:: /substitutions.rst
+.. _simulator:
+
+Simulator
+=========
+
+Apache NuttX has a simulator that can run as a regular program on Linux, Mac, and Windows computers.
+It's useful for debugging operating system features that aren't associated with particular
+device drivers— for instance the TCP/IP stack itself, a web interface or API for your
+application, or other communication protocols. It's also handy for trying out Apache NuttX without
+having a piece of embedded hardware.
+
+This guide assumes you're on Linux. It works on Windows and Mac too— if you know how,
+submit a PR the NuttX Companion to update this guide!
+
+Compiling
+---------
+
+#. Configure the Simulator
+
+ There are a lot of simulator configurations available that set you up to test various
+ operating system features.
+
+ Here we'll use the ``sim:tcpblaster`` configuration because it comes with networking
+ that is ready to use.
+
+ .. code-block:: bash
+
+ $ cd nuttx
+ $ ./tools/configure.sh sim:tcpblaster
+
+#. Compile
+
+ .. code-block:: bash
+
+ $ make clean; make
+
+Running
+-------
+
+#. Give the Simulator Privileges
+
+ On recent Linux distributions, you need to give the ``nuttx`` program the capabilities
+ (similar to permissions) to access the network:
+
+ .. code-block:: bash
+
+ $ sudo setcap cap_net_admin+ep ./nuttx
+
+#. Run the simulator:
+
+ .. code-block:: bash
+
+ $ ./nuttx
+
+#. Bring Up the Network Interfaces
+
+ On Apache NuttX:
+
+ .. code-block:: bash
+
+ nsh> ifup eth0
+
+ On Linux, first you need to find your main network interface— this will usually either
+ be an ethernet or wireless network adapter. Do this:
+
+ .. code-block:: bash
+
+ $ ifconfig
+ lo: flags=73<UP,LOOPBACK,RUNNING> mtu 65536
+ inet 127.0.0.1 netmask 255.0.0.0
+ inet6 ::1 prefixlen 128 scopeid 0x10<host>
+ loop txqueuelen 1000 (Local Loopback)
+ RX packets 5846 bytes 614351 (614.3 KB)
+ RX errors 0 dropped 0 overruns 0 frame 0
+ TX packets 5846 bytes 614351 (614.3 KB)
+ TX errors 0 dropped 0 overruns 0 carrier 0 collisions 0
+
+ wlp0s20f3: flags=4163<UP,BROADCAST,RUNNING,MULTICAST> mtu 1500
+ inet 192.168.1.209 netmask 255.255.255.0 broadcast 192.168.1.255
+ inet6 fe80::1161:c26b:af05:d784 prefixlen 64 scopeid 0x20<link>
+ ether 24:41:8c:a8:30:d1 txqueuelen 1000 (Ethernet)
+ RX packets 219369 bytes 176416490 (176.4 MB)
+ RX errors 0 dropped 0 overruns 0 frame 0
+ TX packets 108399 bytes 27213617 (27.2 MB)
+ TX errors 0 dropped 0 overruns 0 carrier 0 collisions 0
+
+ ``lo0`` is the Loopback Interface, so ``wlp0s20f3`` is the wireless interface. Note
+ that it has an IP address on the local net. There may be other interfaces listed, you'll
+ need to pick the one that's right for your system.
+
+ Then, on Linux do this to set up the tap network interface and route that will let
+ the Apache Nuttx simulator access the network:
+
+ .. code-block:: bash
+
+ $ sudo ./tools/simhostroute.sh wlp0s20f3 on
+ $ ping -c 1 10.0.1.2 # nuttx system
+ PING 10.0.1.2 (10.0.1.2) 56(84) bytes of data.
+ 64 bytes from 10.0.1.2: icmp_seq=1 ttl=64 time=7.52 ms
+
+ --- 10.0.1.2 ping statistics ---
+ 1 packets transmitted, 1 received, 0% packet loss, time 0ms
+ rtt min/avg/max/mdev = 7.529/7.529/7.529/0.000 m
+
+#. Test that Apache NuttX can access the Internet
+
+ First let's ping the network interface of our Linux host to prove we can see the
+ gateway to the Internet:
+
+ .. code-block:: bash
+
+ nsh> ping -c 1 10.0.1.1
+ nsh> ping -c 1 10.0.1.1
+ PING 10.0.1.1 56 bytes of data
+ 56 bytes from 10.0.1.1: icmp_seq=0 time=0 ms
+ 1 packets transmitted, 1 received, 0% packet loss, time 1010 ms
+
+ Now let's ping one of Google's DNS servers to prove we can access the rest of the
+ Internet:
+
+ .. code-block:: bash
+
+ nsh> ping -c 1 8.8.8.8
+ PING 8.8.8.8 56 bytes of data
+ 56 bytes from 8.8.8.8: icmp_seq=0 time=10 ms
+ 1 packets transmitted, 1 received, 0% packet loss, time 1010 ms
+
+ Success!
+
+Stopping
+--------
+
+The only really effective way to stop the simulator is kill it from another terminal:
+
+ .. code-block:: bash
+
+ $ pkill nuttx
Review comment:
@v01d Added poweroff example.
----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [incubator-nuttx] v01d commented on pull request #1677: Add Simulator and Drivers guides, and contributing instructions for new users
Posted by GitBox <gi...@apache.org>.
v01d commented on pull request #1677:
URL: https://github.com/apache/incubator-nuttx/pull/1677#issuecomment-687423446
Whoa, cool tip.
----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [incubator-nuttx] Ouss4 commented on a change in pull request #1677: Add Simulator and Drivers guides, and contributing instructions for new users
Posted by GitBox <gi...@apache.org>.
Ouss4 commented on a change in pull request #1677:
URL: https://github.com/apache/incubator-nuttx/pull/1677#discussion_r480269447
##########
File path: Documentation/contributing/making-changes.rst
##########
@@ -0,0 +1,256 @@
+.. include:: /substitutions.rst
+.. _making-changes:
+
+Making Changes
+==============
+
+If you want to make changes to NuttX, for your own personal use, or to submit them back to project to improve NuttX,
+that's easy. For the purposes of this guide, you'll need a `GitHub <https://www.github.com>`_ account, since
+the Apache NuttX team uses GitHub. (You could also use git locally, or save your changes to other sites like
+`GitLab <https://about.gitlab.com/>`_ or `BitBucket <https://bitbucket.org>`_, but that's beyond the scope of this
+guide).
+
+Here's how to do it:
+
+#. Set your git user name and email
+
+ .. code-block:: bash
+
+ $ cd nuttx/
+ $ git config --global user.name "Your Name"
+ $ git config --global user.email "yourname@somedomaincom"
+
+#. Sign in to GitHub
+
+ If you don't have a `GitHub <https://www.github.com>`_ account, it's free to
+ sign up.
+ |br|
+ |br|
+
+
+#. Fork the Project
+
+ Visit both these links and hit the Fork button in the upper right of the page:
+
+ * `NuttX <https://github.com/apache/incubator-nuttx/>`_
+ * `NuttX Apps <https://github.com/apache/incubator-nuttx-apps/>`_
+
+
+#. Change the Git Remotes
+
+ The git repositories in your project are currently connected to the official NuttX repositories, but you don't
+ have permission to push software there. But you can push them to your forks, and from there create Pull Requests
+ if you want to send them to the NuttX project.
+
+ First, remove the current remote, ``origin`` (we'll add it back later):
+
+ .. code-block:: bash
+
+ $ cd nuttx/
+ $ # display the remote
+ $ git remote -v
+
+ You should see something like this:
+
+ .. code-block:: bash
+
+ origin https://github.com/apache/incubator-nuttx.git
+
+ Now, on the GitHub web page for your forked ``incubator-nuttx`` project, copy the clone url – get it by hitting the
+ green ``Clone or Download`` button in the upper right. Then do this:
+
+ .. code-block:: bash
+
+ $ git remote rm origin
+ $ git remote add origin <your forked incubator-nuttx project clone url>
+ $ git remote add upstream https://github.com/apache/incubator-nuttx.git
+
+ Do the same for your forked ``incubator-nuttx-apps`` project:
+
+ .. code-block:: bash
+
+ $ cd ../apps
+ $ git remote rm origin
+ $ git remote add origin <your forked incubator-nuttx-apps project clone url>
+ $ git remote add upstream https://github.com/apache/incubator-nuttx-apps.git
+
+
+#. Create a Local Git Branch
+
+ Now you can create local git branches and push them to GitHub:
+
+ .. code-block:: bash
+
+ $ git checkout -b test/my-new-branch
+ $ git push
+
+
+Git Workflow With an Upstream Repository
+----------------------------------------
+
+The main NuttX git repository is called an "upstream" repository - this is because it's the main source of truth, and
+its changes flow downstream to people who've forked that repository, like us.
+
+Working with an upstream repo is a bit more complex, but it's worth it since you can submit fixes and features
+to the main NuttX repos. One of the things you need to do regularly is keep your local repo in sync
+with the upstream. I work with a local branch, make changes, pull new software from the upstream and merge it in,
+maybe doing that several times. Then when everything works, I get my branch ready to do a Pull Request. Here's how:
+
+#. Fetch upstream changes and merge into my local master:
+
+ .. code-block:: bash
+
+ $ git checkout master
+ $ git fetch upstream
+ $ git merge upstream/master
+ $ git push
+
+#. Merge my local master with my local branch:
+
+ .. code-block:: bash
+
+ $ git checkout my-local-branch
+ $ git merge master
+ $ git push
Review comment:
I think we are not talking about the same thing.
For the "just" rebase part, we agree. You just supply the branch name. You rebase one branch ontop of the other.
Interactive rebasing is used to change to commits within the same branch. In the doc's example (here or in Confluence) is used to squash some commits. It can also be used to delete, change or re-word (change description of) commits.
To do so, we need a range of commits from the HEAD of the branch, thus the HEAD~N.
----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [incubator-nuttx] v01d commented on a change in pull request #1677: Add Simulator and Drivers guides, and contributing instructions for new users
Posted by GitBox <gi...@apache.org>.
v01d commented on a change in pull request #1677:
URL: https://github.com/apache/incubator-nuttx/pull/1677#discussion_r480251709
##########
File path: Documentation/contributing/making-changes.rst
##########
@@ -0,0 +1,256 @@
+.. include:: /substitutions.rst
+.. _making-changes:
+
+Making Changes
+==============
+
+If you want to make changes to NuttX, for your own personal use, or to submit them back to project to improve NuttX,
+that's easy. For the purposes of this guide, you'll need a `GitHub <https://www.github.com>`_ account, since
+the Apache NuttX team uses GitHub. (You could also use git locally, or save your changes to other sites like
+`GitLab <https://about.gitlab.com/>`_ or `BitBucket <https://bitbucket.org>`_, but that's beyond the scope of this
+guide).
+
+Here's how to do it:
+
+#. Set your git user name and email
+
+ .. code-block:: bash
+
+ $ cd nuttx/
+ $ git config --global user.name "Your Name"
+ $ git config --global user.email "yourname@somedomaincom"
+
+#. Sign in to GitHub
+
+ If you don't have a `GitHub <https://www.github.com>`_ account, it's free to
+ sign up.
+ |br|
+ |br|
+
+
+#. Fork the Project
+
+ Visit both these links and hit the Fork button in the upper right of the page:
+
+ * `NuttX <https://github.com/apache/incubator-nuttx/>`_
+ * `NuttX Apps <https://github.com/apache/incubator-nuttx-apps/>`_
+
+
+#. Change the Git Remotes
+
+ The git repositories in your project are currently connected to the official NuttX repositories, but you don't
+ have permission to push software there. But you can push them to your forks, and from there create Pull Requests
+ if you want to send them to the NuttX project.
+
+ First, remove the current remote, ``origin`` (we'll add it back later):
+
+ .. code-block:: bash
+
+ $ cd nuttx/
+ $ # display the remote
+ $ git remote -v
+
+ You should see something like this:
+
+ .. code-block:: bash
+
+ origin https://github.com/apache/incubator-nuttx.git
+
+ Now, on the GitHub web page for your forked ``incubator-nuttx`` project, copy the clone url – get it by hitting the
+ green ``Clone or Download`` button in the upper right. Then do this:
+
+ .. code-block:: bash
+
+ $ git remote rm origin
+ $ git remote add origin <your forked incubator-nuttx project clone url>
+ $ git remote add upstream https://github.com/apache/incubator-nuttx.git
+
+ Do the same for your forked ``incubator-nuttx-apps`` project:
+
+ .. code-block:: bash
+
+ $ cd ../apps
+ $ git remote rm origin
+ $ git remote add origin <your forked incubator-nuttx-apps project clone url>
+ $ git remote add upstream https://github.com/apache/incubator-nuttx-apps.git
+
+
+#. Create a Local Git Branch
+
+ Now you can create local git branches and push them to GitHub:
+
+ .. code-block:: bash
+
+ $ git checkout -b test/my-new-branch
+ $ git push
+
+
+Git Workflow With an Upstream Repository
+----------------------------------------
+
+The main NuttX git repository is called an "upstream" repository - this is because it's the main source of truth, and
+its changes flow downstream to people who've forked that repository, like us.
+
+Working with an upstream repo is a bit more complex, but it's worth it since you can submit fixes and features
+to the main NuttX repos. One of the things you need to do regularly is keep your local repo in sync
+with the upstream. I work with a local branch, make changes, pull new software from the upstream and merge it in,
+maybe doing that several times. Then when everything works, I get my branch ready to do a Pull Request. Here's how:
+
+#. Fetch upstream changes and merge into my local master:
+
+ .. code-block:: bash
+
+ $ git checkout master
+ $ git fetch upstream
+ $ git merge upstream/master
+ $ git push
+
+#. Merge my local master with my local branch:
+
+ .. code-block:: bash
+
+ $ git checkout my-local-branch
+ $ git merge master
+ $ git push
Review comment:
> Rebase is much better for this.
>
> I was wondering why we show
> `git rev-list` you can just supply the upstream branch to `git rebase`. We also list the super long form option for force. No one is going to type that.
The long version is not the same as the simple force. Supposeddly it is better practice to use the "with-lease" option when force pushing the result of rebase. But I'm not sure if there's a difference when there's only one person accessing a branch.
----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [incubator-nuttx] adamfeuer commented on pull request #1677: Add Simulator and Drivers guides, and contributing instructions for new users
Posted by GitBox <gi...@apache.org>.
adamfeuer commented on pull request #1677:
URL: https://github.com/apache/incubator-nuttx/pull/1677#issuecomment-687451314
@v01d @btashton Ok, I think I addressed everyone's comments and suggestions. I have rebased and force pushed. This should be good to merge now.
----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [incubator-nuttx] Ouss4 commented on pull request #1677: Add Simulator and Drivers guides, and contributing instructions for new users
Posted by GitBox <gi...@apache.org>.
Ouss4 commented on pull request #1677:
URL: https://github.com/apache/incubator-nuttx/pull/1677#issuecomment-683656862
I'm not sure about the "Contributing" part. The first time we had a massive discussion around that. It was so big that the current workflow is still a draft. What to do with that?
----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [incubator-nuttx] Ouss4 commented on a change in pull request #1677: Add Simulator and Drivers guides, and contributing instructions for new users
Posted by GitBox <gi...@apache.org>.
Ouss4 commented on a change in pull request #1677:
URL: https://github.com/apache/incubator-nuttx/pull/1677#discussion_r480211468
##########
File path: Documentation/contributing/making-changes.rst
##########
@@ -0,0 +1,256 @@
+.. include:: /substitutions.rst
+.. _making-changes:
+
+Making Changes
+==============
+
+If you want to make changes to NuttX, for your own personal use, or to submit them back to project to improve NuttX,
+that's easy. For the purposes of this guide, you'll need a `GitHub <https://www.github.com>`_ account, since
+the Apache NuttX team uses GitHub. (You could also use git locally, or save your changes to other sites like
+`GitLab <https://about.gitlab.com/>`_ or `BitBucket <https://bitbucket.org>`_, but that's beyond the scope of this
+guide).
+
+Here's how to do it:
+
+#. Set your git user name and email
+
+ .. code-block:: bash
+
+ $ cd nuttx/
+ $ git config --global user.name "Your Name"
+ $ git config --global user.email "yourname@somedomaincom"
+
+#. Sign in to GitHub
+
+ If you don't have a `GitHub <https://www.github.com>`_ account, it's free to
+ sign up.
+ |br|
+ |br|
+
+
+#. Fork the Project
+
+ Visit both these links and hit the Fork button in the upper right of the page:
+
+ * `NuttX <https://github.com/apache/incubator-nuttx/>`_
+ * `NuttX Apps <https://github.com/apache/incubator-nuttx-apps/>`_
+
+
+#. Change the Git Remotes
+
+ The git repositories in your project are currently connected to the official NuttX repositories, but you don't
+ have permission to push software there. But you can push them to your forks, and from there create Pull Requests
+ if you want to send them to the NuttX project.
+
+ First, remove the current remote, ``origin`` (we'll add it back later):
+
+ .. code-block:: bash
+
+ $ cd nuttx/
+ $ # display the remote
+ $ git remote -v
+
+ You should see something like this:
+
+ .. code-block:: bash
+
+ origin https://github.com/apache/incubator-nuttx.git
+
+ Now, on the GitHub web page for your forked ``incubator-nuttx`` project, copy the clone url – get it by hitting the
+ green ``Clone or Download`` button in the upper right. Then do this:
+
+ .. code-block:: bash
+
+ $ git remote rm origin
+ $ git remote add origin <your forked incubator-nuttx project clone url>
+ $ git remote add upstream https://github.com/apache/incubator-nuttx.git
Review comment:
Is this done because "upstream" is being cloned as "origin"? git clone has the -o option that allows to specify the name of the remote, instead of the default "origin".
----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [incubator-nuttx] btashton commented on a change in pull request #1677: Add Simulator and Drivers guides, and contributing instructions for new users
Posted by GitBox <gi...@apache.org>.
btashton commented on a change in pull request #1677:
URL: https://github.com/apache/incubator-nuttx/pull/1677#discussion_r483864850
##########
File path: Documentation/guides/drivers.rst
##########
@@ -0,0 +1,211 @@
+.. include:: /substitutions.rst
+.. _drivers:
+
+Drivers
+=======
+
+Some NuttX boards don't have full support for all the on-chip peripherals. If you need support for this hardware,
+you will either need to port a driver from another chip, or write one yourself. This section discusses how to do that.
+
+Porting a Driver
+----------------
+
+Often support for on-chip peripherals exists in a closely related chip, or even a different family or from a different
+manufacturer. Many chips are made up of different Intellectual Property (IP) blocks that are licensed from vendors like
+Cadence, Synopsys, and others. The IP blocks may be similar enough to use another chip's driver with little
+modification.
+
+* Find a similar driver in NuttX source code:
+
+ * Look at register names listed in the datasheet for the peripheral.
+ * Search the NuttX codebase for the register names (try several different ones).
+ * Note that you'll have to compare the datasheet to the header and code files to see if there are differences; there
+ will usually be some differences between architectures, and they can be significant.
+
+* Find a similar driver in U-Boot source code:
+
+ * Only for inspiration, you can't copy code because of license incompatibility.
+ * But you can debug to see how the driver works.
+ * `U-Boot <https://www.denx.de/wiki/U-Boot>`_ drivers are often easier to understand than BSD Unix drivers because
+ U-Boot is simpler.
+
+* Find a similar driver in Zephyr or BSD Unix (OpenBSD, FreeBSD, NetBSD):
+
+ * If you find one, you can borrow code directly (Apache 2.0 and BSD licenses are compatible).
+
+* Understanding how the driver works
+
+ Here are a couple of techniques that helped me.
+
+ * printf debugging
+
+ * Sprinkle ``custinfo()`` logging statements through your code to see execution paths and look at variables
+ while the code is running. The reason to use ``custinfo()`` as opposed to the other logging shortcuts
+ (``mcinfo()``, etc.) is that you can turn on and off other other logging and still see your custom debug
+ logging. Sometimes it's useful to quiet the flood of logging that comes from a particular debug logging
+ shortcut.
+ * Note that printing info to the console will affect timing.
+ * Keep a file with just your debug settings in it, like this (``debugsettings``):
+
+ .. code-block:: c
+
+ CONFIG_DEBUG_CUSTOM_INFO=y
+ (etc..)
+
+ * Add the settings to the end of your ``.config`` file after running ``make menuconfig`` (that will reorder
+ the file, making it harder to see and change the debug settings if you need to).
+
+ .. code-block:: bash
+
+ $ cat .config debugsettings > .config1 ; mv .config1 .config
+
+ * If you are using interrupts and threads (many things in NuttX run in different threads as a response to interrupts),
+ you can use printf debugging to see overlapping execution.
+
+ * Interrupts - here's how to inspect the C stack frame to see what execution environment is currently running:
+
+ .. code-block:: c
+
+ uint32_t frame = 0; /* MUST be the very first thing in the function */
+ uint32_t p_frame;
+ frame++; /* make sure that frame doesn't get optimized out */
+ p_frame = (uint32_t)(&frame);
+ custinfo("p_frame: %08x\n", p_frame);
+
+ * Threads - here's how to get the thread identifier to see which thread is currently executing:
+
+ .. code-block:: c
+
+ pthread_t thread_id = pthread_self();
+ custinfo("pthread_id: %08x\n", thread_id);
+
+ * stack frame printf
+ * thread printf
+
+ * `GDB — the Gnu Debugger <https://www.gnu.org/software/gdb/>`_
+
+ GDB is a great tool. In this guide we've already used it to load our program and run it. But it can do a lot
+ more. You can single-step through code, examine variables and memory, set breakpoints, and more. I generally use
+ it from the commandline, but have also used it from an IDE like JetBrains' Clion, where it's easier to see the
+ code context.
+
+ One add-on that I found to be essential is the ability to examine blocks of memory, like buffers that NuttX uses
+ for reading and writing to storage media or network adapters. This `Stack Overflow question on using GDB to
+ examine memory <https://stackoverflow.com/a/54784260/431222>`_ includes a GDB command that is very handy. Add
+ this to your ``.gdbinit`` file, and then use the ``xxd`` command to dump memory in an easy-to-read format:
+
+ .. code-block::
+
+ define xxd
+ if $argc < 2
+ set $size = sizeof(*$arg0)
+ else
+ set $size = $arg1
+ end
+ dump binary memory dump.bin $arg0 ((void *)$arg0)+$size
+ eval "shell xxd -o %d dump.bin; rm dump.bin", ((void *)$arg0)
+ end
+ document xxd
+ Dump memory with xxd command (keep the address as offset)
+
+ xxd addr [size]
+ addr -- expression resolvable as an address
+ size -- size (in byte) of memory to dump
+ sizeof(*addr) is used by default end
+
+ Here's a short GDB session that shows what this looks like in practice. Note that the memory location being
+ examined (``0x200aa9eo`` here) is a buffer being passed to ``mmcsd_readsingle``:
+
+ .. code-block::
+
+ Program received signal SIGTRAP, Trace/breakpoint trap.
+ 0x200166e8 in up_idle () at common/arm_idle.c:78
+ 78 }
+ (gdb) b mmcsd_readsingle
+ Breakpoint 1 at 0x2006ea70: file mmcsd/mmcsd_sdio.c, line 1371.
+ (gdb) c
+ Continuing.
+
+ Breakpoint 1, mmcsd_readsingle (priv=0x200aa8c0, buffer=0x200aa9e0 "WRTEST TXT \030", startblock=2432) at mmcsd/mmcsd_sdio.c:1371
+ 1371 finfo("startblock=%d\n", startblock);
+ (gdb) xxd 0x200aa9e0 200
+ 200aa9e0: 5752 5445 5354 2020 5458 5420 1800 0000 WRTEST TXT ....
+ 200aa9f0: 0000 0000 0000 0000 0000 5500 1100 0000 ..........U.....
+ 200aaa00: 5752 5445 5354 3520 5458 5420 1800 0000 WRTEST5 TXT ....
+ 200aaa10: 0000 0000 0000 0000 0000 5800 1500 0000 ..........X.....
+ 200aaa20: e552 5445 5854 3620 5458 5420 1800 0000 .RTEXT6 TXT ....
+ 200aaa30: 0000 0000 0000 0000 0000 5600 1200 0000 ..........V.....
+ 200aaa40: 5752 5445 5354 3620 5458 5420 1800 0000 WRTEST6 TXT ....
+ 200aaa50: 0000 0000 0000 0000 0000 5600 1200 0000 ..........V.....
+ 200aaa60: 0000 0000 0000 0000 0000 0000 0000 0000 ................
+ 200aaa70: 0000 0000 0000 0000 0000 0000 0000 0000 ................
+ 200aaa80: 0000 0000 0000 0000 0000 0000 0000 0000 ................
+ 200aaa90: 0000 0000 0000 0000 0000 0000 0000 0000 ................
+ 200aaaa0: 0000 0000 0000 0000 ........
+
+
+NuttX Drivers as a Reference
+----------------------------
+
+If you're not porting a NuttX driver from another architecture, it still helps to look at other similar NuttX
+drivers, if there are any. For instance, when implementing an Ethernet driver, look at other NuttX Ethernet drivers;
+for an SD Card driver, look at other NuttX Ethernet drivers. Even if the chip-specific code won't be the same, the
+structure to interface with NuttX can be used.
+
+Using Chip Datasheets
+---------------------
+
+To port or write a driver, you'll have to be familiar with the information in the chip datasheet. Definitely find
+the datasheet for your chip, and read the sections relevant to the peripheral you're working with. Doing so ahead
+of time will save a lot of time later.
+
+Another thing that's often helpful is to refer to sample code provided by the manufacturer, or driver code from
+another operating system (like U-Boot, Zephyr, or FreeBSD) while referring to the datasheet — seeing how working
+code implements the necessary algorithms often helps one understand how the driver needs to work.
+
+* How to use a datasheet
+
+ Key pieces of information in System-on-a-Chip (SoC) datasheets are usually:
+
+ * Chip Architecture Diagram — shows how the subsections of the chip (CPU, system bus, peripherals, I/O, etc.) connect
+ to each other.
+ * Memory Map — showing the location of peripheral registers in memory. This info usually goes into a header file.
+ * DMA Engine — if Direct Memory Access (DMA) is used, this may have info on how to use it.
+ * Peripheral — the datasheet usually has a section on how the peripheral works. Key parts of this include:
+
+ * Registers List — name and offset from the base memory address of the peripheral. This needs to go into a header
+ file.
+ * Register Map — what is the size of each register, and what do the bits mean? You will need to create ``#defines``
+ in a header file that your code will use to operate on the registers. Refer to other driver header files for
+ examples.
+
+`Logic analyzers <https://en.wikipedia.org/wiki/Logic_analyzer>`_
+-----------------------------------------------------------------
+
+For drivers that involve input and output (I/O), especially that involve complex protocols like SD Cards, SPI, I2C,
+etc., actually seeing the waveform that goes in and out the chip's pins is extremely helpful. Logic analyzers can
+capture that information and display it graphically, allowing you to see if the driver is doing the right thing
+on the wire.
+
+DMA Debugging
+-------------
+
+* Dump registers before, during, and after transfer. Some NuttX drivers (``sam_sdmmc.c`` or ``imxrt_sdmmc.c`` for
+ example) have built-in code for debugging register states, and can sample registers before, during, and
+ immediately after a DMA transfer, as well as code that can dump the peripheral registers in a nicely-formatted
+ way onto the console device (which can be a serial console, a network console, or memory). Consider using something
+ like this to see what's happening inside the chip if you're trying to debug DMA transfer code.
+* Compare register settings to expected settings determined from the datasheet or from dumping registers from working
+ code in another operating system (U-Boot, Zephyr, FreeBSD, etc.).
+* Use the ``xxd`` GDB tool mentioned above to dump NuttX memory buffers before, during, and after a transfer to see if
+ data is being transferred correctly, if there are over- or under-runs, or to diagnose data being stored in incorrect
+ locations.
+* printf debugging register states can also help here.
+* Remember that logging can change the timing of any algorithms you might be using, so things may start or stop
+ working when logging is added or removed. Definitely test with logging disabled.
+
Review comment:
Extra newlines
##########
File path: Documentation/guides/drivers.rst
##########
@@ -0,0 +1,211 @@
+.. include:: /substitutions.rst
+.. _drivers:
+
+Drivers
+=======
+
+Some NuttX boards don't have full support for all the on-chip peripherals. If you need support for this hardware,
+you will either need to port a driver from another chip, or write one yourself. This section discusses how to do that.
+
+Porting a Driver
+----------------
+
+Often support for on-chip peripherals exists in a closely related chip, or even a different family or from a different
+manufacturer. Many chips are made up of different Intellectual Property (IP) blocks that are licensed from vendors like
+Cadence, Synopsys, and others. The IP blocks may be similar enough to use another chip's driver with little
+modification.
+
+* Find a similar driver in NuttX source code:
+
+ * Look at register names listed in the datasheet for the peripheral.
+ * Search the NuttX codebase for the register names (try several different ones).
+ * Note that you'll have to compare the datasheet to the header and code files to see if there are differences; there
+ will usually be some differences between architectures, and they can be significant.
+
+* Find a similar driver in U-Boot source code:
+
+ * Only for inspiration, you can't copy code because of license incompatibility.
+ * But you can debug to see how the driver works.
+ * `U-Boot <https://www.denx.de/wiki/U-Boot>`_ drivers are often easier to understand than BSD Unix drivers because
+ U-Boot is simpler.
+
+* Find a similar driver in Zephyr or BSD Unix (OpenBSD, FreeBSD, NetBSD):
+
+ * If you find one, you can borrow code directly (Apache 2.0 and BSD licenses are compatible).
+
+* Understanding how the driver works
+
+ Here are a couple of techniques that helped me.
+
+ * printf debugging
+
+ * Sprinkle ``custinfo()`` logging statements through your code to see execution paths and look at variables
+ while the code is running. The reason to use ``custinfo()`` as opposed to the other logging shortcuts
+ (``mcinfo()``, etc.) is that you can turn on and off other other logging and still see your custom debug
+ logging. Sometimes it's useful to quiet the flood of logging that comes from a particular debug logging
+ shortcut.
+ * Note that printing info to the console will affect timing.
+ * Keep a file with just your debug settings in it, like this (``debugsettings``):
+
+ .. code-block:: c
+
+ CONFIG_DEBUG_CUSTOM_INFO=y
+ (etc..)
+
+ * Add the settings to the end of your ``.config`` file after running ``make menuconfig`` (that will reorder
+ the file, making it harder to see and change the debug settings if you need to).
+
+ .. code-block:: bash
+
+ $ cat .config debugsettings > .config1 ; mv .config1 .config
+
+ * If you are using interrupts and threads (many things in NuttX run in different threads as a response to interrupts),
+ you can use printf debugging to see overlapping execution.
+
+ * Interrupts - here's how to inspect the C stack frame to see what execution environment is currently running:
+
+ .. code-block:: c
+
+ uint32_t frame = 0; /* MUST be the very first thing in the function */
+ uint32_t p_frame;
+ frame++; /* make sure that frame doesn't get optimized out */
+ p_frame = (uint32_t)(&frame);
+ custinfo("p_frame: %08x\n", p_frame);
+
+ * Threads - here's how to get the thread identifier to see which thread is currently executing:
+
+ .. code-block:: c
+
+ pthread_t thread_id = pthread_self();
+ custinfo("pthread_id: %08x\n", thread_id);
+
+ * stack frame printf
+ * thread printf
+
+ * `GDB — the Gnu Debugger <https://www.gnu.org/software/gdb/>`_
+
+ GDB is a great tool. In this guide we've already used it to load our program and run it. But it can do a lot
+ more. You can single-step through code, examine variables and memory, set breakpoints, and more. I generally use
+ it from the commandline, but have also used it from an IDE like JetBrains' Clion, where it's easier to see the
+ code context.
+
+ One add-on that I found to be essential is the ability to examine blocks of memory, like buffers that NuttX uses
+ for reading and writing to storage media or network adapters. This `Stack Overflow question on using GDB to
+ examine memory <https://stackoverflow.com/a/54784260/431222>`_ includes a GDB command that is very handy. Add
+ this to your ``.gdbinit`` file, and then use the ``xxd`` command to dump memory in an easy-to-read format:
+
+ .. code-block::
+
+ define xxd
+ if $argc < 2
+ set $size = sizeof(*$arg0)
+ else
+ set $size = $arg1
+ end
+ dump binary memory dump.bin $arg0 ((void *)$arg0)+$size
+ eval "shell xxd -o %d dump.bin; rm dump.bin", ((void *)$arg0)
+ end
+ document xxd
+ Dump memory with xxd command (keep the address as offset)
+
+ xxd addr [size]
+ addr -- expression resolvable as an address
+ size -- size (in byte) of memory to dump
+ sizeof(*addr) is used by default end
+
+ Here's a short GDB session that shows what this looks like in practice. Note that the memory location being
+ examined (``0x200aa9eo`` here) is a buffer being passed to ``mmcsd_readsingle``:
+
+ .. code-block::
+
+ Program received signal SIGTRAP, Trace/breakpoint trap.
+ 0x200166e8 in up_idle () at common/arm_idle.c:78
+ 78 }
+ (gdb) b mmcsd_readsingle
+ Breakpoint 1 at 0x2006ea70: file mmcsd/mmcsd_sdio.c, line 1371.
+ (gdb) c
+ Continuing.
+
+ Breakpoint 1, mmcsd_readsingle (priv=0x200aa8c0, buffer=0x200aa9e0 "WRTEST TXT \030", startblock=2432) at mmcsd/mmcsd_sdio.c:1371
+ 1371 finfo("startblock=%d\n", startblock);
+ (gdb) xxd 0x200aa9e0 200
+ 200aa9e0: 5752 5445 5354 2020 5458 5420 1800 0000 WRTEST TXT ....
+ 200aa9f0: 0000 0000 0000 0000 0000 5500 1100 0000 ..........U.....
+ 200aaa00: 5752 5445 5354 3520 5458 5420 1800 0000 WRTEST5 TXT ....
+ 200aaa10: 0000 0000 0000 0000 0000 5800 1500 0000 ..........X.....
+ 200aaa20: e552 5445 5854 3620 5458 5420 1800 0000 .RTEXT6 TXT ....
+ 200aaa30: 0000 0000 0000 0000 0000 5600 1200 0000 ..........V.....
+ 200aaa40: 5752 5445 5354 3620 5458 5420 1800 0000 WRTEST6 TXT ....
+ 200aaa50: 0000 0000 0000 0000 0000 5600 1200 0000 ..........V.....
+ 200aaa60: 0000 0000 0000 0000 0000 0000 0000 0000 ................
+ 200aaa70: 0000 0000 0000 0000 0000 0000 0000 0000 ................
+ 200aaa80: 0000 0000 0000 0000 0000 0000 0000 0000 ................
+ 200aaa90: 0000 0000 0000 0000 0000 0000 0000 0000 ................
+ 200aaaa0: 0000 0000 0000 0000 ........
+
+
+NuttX Drivers as a Reference
+----------------------------
+
+If you're not porting a NuttX driver from another architecture, it still helps to look at other similar NuttX
+drivers, if there are any. For instance, when implementing an Ethernet driver, look at other NuttX Ethernet drivers;
+for an SD Card driver, look at other NuttX Ethernet drivers. Even if the chip-specific code won't be the same, the
+structure to interface with NuttX can be used.
+
+Using Chip Datasheets
+---------------------
+
+To port or write a driver, you'll have to be familiar with the information in the chip datasheet. Definitely find
+the datasheet for your chip, and read the sections relevant to the peripheral you're working with. Doing so ahead
+of time will save a lot of time later.
+
+Another thing that's often helpful is to refer to sample code provided by the manufacturer, or driver code from
+another operating system (like U-Boot, Zephyr, or FreeBSD) while referring to the datasheet — seeing how working
+code implements the necessary algorithms often helps one understand how the driver needs to work.
+
+* How to use a datasheet
+
+ Key pieces of information in System-on-a-Chip (SoC) datasheets are usually:
+
+ * Chip Architecture Diagram — shows how the subsections of the chip (CPU, system bus, peripherals, I/O, etc.) connect
+ to each other.
+ * Memory Map — showing the location of peripheral registers in memory. This info usually goes into a header file.
+ * DMA Engine — if Direct Memory Access (DMA) is used, this may have info on how to use it.
+ * Peripheral — the datasheet usually has a section on how the peripheral works. Key parts of this include:
+
+ * Registers List — name and offset from the base memory address of the peripheral. This needs to go into a header
+ file.
+ * Register Map — what is the size of each register, and what do the bits mean? You will need to create ``#defines``
+ in a header file that your code will use to operate on the registers. Refer to other driver header files for
+ examples.
+
+`Logic analyzers <https://en.wikipedia.org/wiki/Logic_analyzer>`_
Review comment:
Do we want this whole heading to be a link? It's a little jarring.
----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [incubator-nuttx] btashton commented on pull request #1677: Add Simulator and Drivers guides, and contributing instructions for new users
Posted by GitBox <gi...@apache.org>.
btashton commented on pull request #1677:
URL: https://github.com/apache/incubator-nuttx/pull/1677#issuecomment-687450513
I'm good with this. @v01d maybe you take a final look and merge?
----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [incubator-nuttx] adamfeuer commented on pull request #1677: Add Simulator and Drivers guides, and contributing instructions for new users
Posted by GitBox <gi...@apache.org>.
adamfeuer commented on pull request #1677:
URL: https://github.com/apache/incubator-nuttx/pull/1677#issuecomment-687386468
@v01d Re: the drivers section, it could be rewritten to be a general guide to developing on NuttX. As it is, there is a bunch of driver-specific advice in it. I'd like to leave as is for now, and it can be generalized in a future PR. Do you have objections to that?
----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [incubator-nuttx] v01d commented on a change in pull request #1677: Add Simulator and Drivers guides, and contributing instructions for new users
Posted by GitBox <gi...@apache.org>.
v01d commented on a change in pull request #1677:
URL: https://github.com/apache/incubator-nuttx/pull/1677#discussion_r480195721
##########
File path: Documentation/guides/simulator.rst
##########
@@ -0,0 +1,145 @@
+.. include:: /substitutions.rst
+.. _simulator:
+
+Simulator
+=========
+
+Apache NuttX has a simulator that can run as a regular program on Linux, Mac, and Windows computers.
+It's useful for debugging operating system features that aren't associated with particular
+device drivers— for instance the TCP/IP stack itself, a web interface or API for your
+application, or other communication protocols. It's also handy for trying out Apache NuttX without
+having a piece of embedded hardware.
+
+This guide assumes you're on Linux. It works on Windows and Mac too— if you know how,
+submit a PR the NuttX Companion to update this guide!
+
+Compiling
+---------
+
+#. Configure the Simulator
+
+ There are a lot of simulator configurations available that set you up to test various
+ operating system features.
+
+ Here we'll use the ``sim:tcpblaster`` configuration because it comes with networking
+ that is ready to use.
+
+ .. code-block:: bash
+
+ $ cd nuttx
+ $ ./tools/configure.sh sim:tcpblaster
+
+#. Compile
+
+ .. code-block:: bash
+
+ $ make clean; make
+
+Running
+-------
+
+#. Give the Simulator Privileges
+
+ On recent Linux distributions, you need to give the ``nuttx`` program the capabilities
+ (similar to permissions) to access the network:
+
+ .. code-block:: bash
+
+ $ sudo setcap cap_net_admin+ep ./nuttx
+
+#. Run the simulator:
+
+ .. code-block:: bash
+
+ $ ./nuttx
+
+#. Bring Up the Network Interfaces
+
+ On Apache NuttX:
+
+ .. code-block:: bash
+
+ nsh> ifup eth0
+
+ On Linux, first you need to find your main network interface— this will usually either
+ be an ethernet or wireless network adapter. Do this:
+
+ .. code-block:: bash
+
+ $ ifconfig
+ lo: flags=73<UP,LOOPBACK,RUNNING> mtu 65536
+ inet 127.0.0.1 netmask 255.0.0.0
+ inet6 ::1 prefixlen 128 scopeid 0x10<host>
+ loop txqueuelen 1000 (Local Loopback)
+ RX packets 5846 bytes 614351 (614.3 KB)
+ RX errors 0 dropped 0 overruns 0 frame 0
+ TX packets 5846 bytes 614351 (614.3 KB)
+ TX errors 0 dropped 0 overruns 0 carrier 0 collisions 0
+
+ wlp0s20f3: flags=4163<UP,BROADCAST,RUNNING,MULTICAST> mtu 1500
+ inet 192.168.1.209 netmask 255.255.255.0 broadcast 192.168.1.255
+ inet6 fe80::1161:c26b:af05:d784 prefixlen 64 scopeid 0x20<link>
+ ether 24:41:8c:a8:30:d1 txqueuelen 1000 (Ethernet)
+ RX packets 219369 bytes 176416490 (176.4 MB)
+ RX errors 0 dropped 0 overruns 0 frame 0
+ TX packets 108399 bytes 27213617 (27.2 MB)
+ TX errors 0 dropped 0 overruns 0 carrier 0 collisions 0
+
+ ``lo0`` is the Loopback Interface, so ``wlp0s20f3`` is the wireless interface. Note
+ that it has an IP address on the local net. There may be other interfaces listed, you'll
+ need to pick the one that's right for your system.
+
+ Then, on Linux do this to set up the tap network interface and route that will let
+ the Apache Nuttx simulator access the network:
+
+ .. code-block:: bash
+
+ $ sudo ./tools/simhostroute.sh wlp0s20f3 on
+ $ ping -c 1 10.0.1.2 # nuttx system
+ PING 10.0.1.2 (10.0.1.2) 56(84) bytes of data.
+ 64 bytes from 10.0.1.2: icmp_seq=1 ttl=64 time=7.52 ms
+
+ --- 10.0.1.2 ping statistics ---
+ 1 packets transmitted, 1 received, 0% packet loss, time 0ms
+ rtt min/avg/max/mdev = 7.529/7.529/7.529/0.000 m
+
+#. Test that Apache NuttX can access the Internet
+
+ First let's ping the network interface of our Linux host to prove we can see the
+ gateway to the Internet:
+
+ .. code-block:: bash
+
+ nsh> ping -c 1 10.0.1.1
+ nsh> ping -c 1 10.0.1.1
+ PING 10.0.1.1 56 bytes of data
+ 56 bytes from 10.0.1.1: icmp_seq=0 time=0 ms
+ 1 packets transmitted, 1 received, 0% packet loss, time 1010 ms
+
+ Now let's ping one of Google's DNS servers to prove we can access the rest of the
+ Internet:
+
+ .. code-block:: bash
+
+ nsh> ping -c 1 8.8.8.8
+ PING 8.8.8.8 56 bytes of data
+ 56 bytes from 8.8.8.8: icmp_seq=0 time=10 ms
+ 1 packets transmitted, 1 received, 0% packet loss, time 1010 ms
+
+ Success!
+
+Stopping
+--------
+
+The only really effective way to stop the simulator is kill it from another terminal:
+
+ .. code-block:: bash
+
+ $ pkill nuttx
+
+
+
+Debugging
+---------
+
+You can debug the simulator like any regular Linux program.
Review comment:
maybe a brief example with gdb?
----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [incubator-nuttx] adamfeuer commented on a change in pull request #1677: Add Simulator and Drivers guides, and contributing instructions for new users
Posted by GitBox <gi...@apache.org>.
adamfeuer commented on a change in pull request #1677:
URL: https://github.com/apache/incubator-nuttx/pull/1677#discussion_r483840067
##########
File path: Documentation/guides/simulator.rst
##########
@@ -0,0 +1,145 @@
+.. include:: /substitutions.rst
+.. _simulator:
+
+Simulator
+=========
+
+Apache NuttX has a simulator that can run as a regular program on Linux, Mac, and Windows computers.
+It's useful for debugging operating system features that aren't associated with particular
+device drivers— for instance the TCP/IP stack itself, a web interface or API for your
+application, or other communication protocols. It's also handy for trying out Apache NuttX without
+having a piece of embedded hardware.
+
+This guide assumes you're on Linux. It works on Windows and Mac too— if you know how,
+submit a PR the NuttX Companion to update this guide!
+
+Compiling
+---------
+
+#. Configure the Simulator
+
+ There are a lot of simulator configurations available that set you up to test various
+ operating system features.
+
+ Here we'll use the ``sim:tcpblaster`` configuration because it comes with networking
+ that is ready to use.
+
+ .. code-block:: bash
+
+ $ cd nuttx
+ $ ./tools/configure.sh sim:tcpblaster
+
+#. Compile
+
+ .. code-block:: bash
+
+ $ make clean; make
+
+Running
+-------
+
+#. Give the Simulator Privileges
+
+ On recent Linux distributions, you need to give the ``nuttx`` program the capabilities
+ (similar to permissions) to access the network:
+
+ .. code-block:: bash
+
+ $ sudo setcap cap_net_admin+ep ./nuttx
+
+#. Run the simulator:
+
+ .. code-block:: bash
+
+ $ ./nuttx
+
+#. Bring Up the Network Interfaces
+
+ On Apache NuttX:
+
+ .. code-block:: bash
+
+ nsh> ifup eth0
+
+ On Linux, first you need to find your main network interface— this will usually either
+ be an ethernet or wireless network adapter. Do this:
+
+ .. code-block:: bash
Review comment:
@v01d Will fix
----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [incubator-nuttx] adamfeuer commented on a change in pull request #1677: Add Simulator and Drivers guides, and contributing instructions for new users
Posted by GitBox <gi...@apache.org>.
adamfeuer commented on a change in pull request #1677:
URL: https://github.com/apache/incubator-nuttx/pull/1677#discussion_r483848789
##########
File path: Documentation/contributing/making-changes.rst
##########
@@ -0,0 +1,256 @@
+.. include:: /substitutions.rst
+.. _making-changes:
+
+Making Changes
+==============
+
+If you want to make changes to NuttX, for your own personal use, or to submit them back to project to improve NuttX,
+that's easy. For the purposes of this guide, you'll need a `GitHub <https://www.github.com>`_ account, since
+the Apache NuttX team uses GitHub. (You could also use git locally, or save your changes to other sites like
+`GitLab <https://about.gitlab.com/>`_ or `BitBucket <https://bitbucket.org>`_, but that's beyond the scope of this
+guide).
+
+Here's how to do it:
+
+#. Set your git user name and email
+
+ .. code-block:: bash
+
+ $ cd nuttx/
+ $ git config --global user.name "Your Name"
+ $ git config --global user.email "yourname@somedomaincom"
+
+#. Sign in to GitHub
+
+ If you don't have a `GitHub <https://www.github.com>`_ account, it's free to
+ sign up.
+ |br|
+ |br|
+
+
+#. Fork the Project
+
+ Visit both these links and hit the Fork button in the upper right of the page:
+
+ * `NuttX <https://github.com/apache/incubator-nuttx/>`_
+ * `NuttX Apps <https://github.com/apache/incubator-nuttx-apps/>`_
+
+
+#. Change the Git Remotes
+
+ The git repositories in your project are currently connected to the official NuttX repositories, but you don't
+ have permission to push software there. But you can push them to your forks, and from there create Pull Requests
+ if you want to send them to the NuttX project.
+
+ First, remove the current remote, ``origin`` (we'll add it back later):
+
+ .. code-block:: bash
+
+ $ cd nuttx/
+ $ # display the remote
+ $ git remote -v
+
+ You should see something like this:
+
+ .. code-block:: bash
+
+ origin https://github.com/apache/incubator-nuttx.git
+
+ Now, on the GitHub web page for your forked ``incubator-nuttx`` project, copy the clone url – get it by hitting the
+ green ``Clone or Download`` button in the upper right. Then do this:
+
+ .. code-block:: bash
+
+ $ git remote rm origin
+ $ git remote add origin <your forked incubator-nuttx project clone url>
+ $ git remote add upstream https://github.com/apache/incubator-nuttx.git
+
+ Do the same for your forked ``incubator-nuttx-apps`` project:
+
+ .. code-block:: bash
+
+ $ cd ../apps
+ $ git remote rm origin
+ $ git remote add origin <your forked incubator-nuttx-apps project clone url>
+ $ git remote add upstream https://github.com/apache/incubator-nuttx-apps.git
+
+
+#. Create a Local Git Branch
+
+ Now you can create local git branches and push them to GitHub:
+
+ .. code-block:: bash
+
+ $ git checkout -b test/my-new-branch
+ $ git push
+
+
+Git Workflow With an Upstream Repository
+----------------------------------------
+
+The main NuttX git repository is called an "upstream" repository - this is because it's the main source of truth, and
+its changes flow downstream to people who've forked that repository, like us.
+
+Working with an upstream repo is a bit more complex, but it's worth it since you can submit fixes and features
+to the main NuttX repos. One of the things you need to do regularly is keep your local repo in sync
+with the upstream. I work with a local branch, make changes, pull new software from the upstream and merge it in,
+maybe doing that several times. Then when everything works, I get my branch ready to do a Pull Request. Here's how:
+
+#. Fetch upstream changes and merge into my local master:
+
+ .. code-block:: bash
+
+ $ git checkout master
+ $ git fetch upstream
+ $ git merge upstream/master
+ $ git push
+
+#. Merge my local master with my local branch:
+
+ .. code-block:: bash
+
+ $ git checkout my-local-branch
+ $ git merge master
+ $ git push
Review comment:
@Ouss4 @btashton I added the rebase flow listed by @btashton as the first option. I left the other way as a second option. Do you have objections to leaving it in?
----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [incubator-nuttx] adamfeuer commented on a change in pull request #1677: Add Simulator and Drivers guides, and contributing instructions for new users
Posted by GitBox <gi...@apache.org>.
adamfeuer commented on a change in pull request #1677:
URL: https://github.com/apache/incubator-nuttx/pull/1677#discussion_r483843983
##########
File path: Documentation/contributing/making-changes.rst
##########
@@ -0,0 +1,256 @@
+.. include:: /substitutions.rst
+.. _making-changes:
+
+Making Changes
+==============
+
+If you want to make changes to NuttX, for your own personal use, or to submit them back to project to improve NuttX,
+that's easy. For the purposes of this guide, you'll need a `GitHub <https://www.github.com>`_ account, since
+the Apache NuttX team uses GitHub. (You could also use git locally, or save your changes to other sites like
+`GitLab <https://about.gitlab.com/>`_ or `BitBucket <https://bitbucket.org>`_, but that's beyond the scope of this
+guide).
+
+Here's how to do it:
+
+#. Set your git user name and email
+
+ .. code-block:: bash
+
+ $ cd nuttx/
+ $ git config --global user.name "Your Name"
+ $ git config --global user.email "yourname@somedomaincom"
+
+#. Sign in to GitHub
+
+ If you don't have a `GitHub <https://www.github.com>`_ account, it's free to
+ sign up.
+ |br|
+ |br|
+
+
+#. Fork the Project
+
+ Visit both these links and hit the Fork button in the upper right of the page:
+
+ * `NuttX <https://github.com/apache/incubator-nuttx/>`_
+ * `NuttX Apps <https://github.com/apache/incubator-nuttx-apps/>`_
+
+
+#. Change the Git Remotes
+
+ The git repositories in your project are currently connected to the official NuttX repositories, but you don't
+ have permission to push software there. But you can push them to your forks, and from there create Pull Requests
+ if you want to send them to the NuttX project.
+
+ First, remove the current remote, ``origin`` (we'll add it back later):
+
+ .. code-block:: bash
+
+ $ cd nuttx/
+ $ # display the remote
+ $ git remote -v
+
+ You should see something like this:
+
+ .. code-block:: bash
+
+ origin https://github.com/apache/incubator-nuttx.git
+
+ Now, on the GitHub web page for your forked ``incubator-nuttx`` project, copy the clone url – get it by hitting the
+ green ``Clone or Download`` button in the upper right. Then do this:
+
+ .. code-block:: bash
+
+ $ git remote rm origin
+ $ git remote add origin <your forked incubator-nuttx project clone url>
+ $ git remote add upstream https://github.com/apache/incubator-nuttx.git
+
+ Do the same for your forked ``incubator-nuttx-apps`` project:
+
+ .. code-block:: bash
+
+ $ cd ../apps
+ $ git remote rm origin
+ $ git remote add origin <your forked incubator-nuttx-apps project clone url>
+ $ git remote add upstream https://github.com/apache/incubator-nuttx-apps.git
+
+
+#. Create a Local Git Branch
+
+ Now you can create local git branches and push them to GitHub:
+
+ .. code-block:: bash
+
+ $ git checkout -b test/my-new-branch
+ $ git push
+
+
+Git Workflow With an Upstream Repository
+----------------------------------------
+
+The main NuttX git repository is called an "upstream" repository - this is because it's the main source of truth, and
+its changes flow downstream to people who've forked that repository, like us.
+
+Working with an upstream repo is a bit more complex, but it's worth it since you can submit fixes and features
+to the main NuttX repos. One of the things you need to do regularly is keep your local repo in sync
+with the upstream. I work with a local branch, make changes, pull new software from the upstream and merge it in,
+maybe doing that several times. Then when everything works, I get my branch ready to do a Pull Request. Here's how:
+
+#. Fetch upstream changes and merge into my local master:
+
+ .. code-block:: bash
+
+ $ git checkout master
+ $ git fetch upstream
+ $ git merge upstream/master
+ $ git push
+
+#. Merge my local master with my local branch:
+
+ .. code-block:: bash
+
+ $ git checkout my-local-branch
+ $ git merge master
+ $ git push
+
+#. Make changes and push them to my fork
+
+ .. code-block:: bash
+
+ $ vim my-file.c
+ $ git add my-file.c
+ $ git commit my-file.c
+ $ git push
+
+#. Repeat 1-3 as necessary
+
+#. Run the ``tools/checkpatch.sh`` script on your files
+
+ When your code runs, then you're almost ready to submit it. But first you need to check the code to ensure
+ that it conforms to the NuttX :ref:`contributing/coding_style:C Coding Standard`.
+ The ``tools/checkpatch.sh`` script will do that. Here's the usage info:
+
+ .. code-block:: bash
+
+ $ ./tools/checkpatch.sh -h
+ USAGE: ./tools/checkpatch.sh [options] [list|-]
+
+ Options:
+ -h
+ -c spell check with codespell(install with: pip install codespell
+ -r range check only (used with -p and -g)
+ -p <patch list> (default)
+ -g <commit list>
+ -f <file list>
+ - read standard input mainly used by git pre-commit hook as below:
+ git diff --cached | ./tools/checkpatch.sh -
+
+ Run it against your files and correct all the errors in the code you added, so that
+ ``tools/checkpatch.sh`` reports no errors. Then commit the result.
+ For example:
+
+ .. code-block:: bash
+
+ $ ./tools/checkpatch.sh -f my-file.c
+ arch/arm/src/sama5/hardware/my-file.c:876:82: warning: Long line found
+ $ # fix errors
+ $ vim my-file.c
+ $ # run again
+ $ ./tools/checkpatch.sh -f my-file.c
+
+ If you have made a lot of changes, you can also use this bash commandline to see the errors for all the changed C
+ files in your branch (assumes you are currently on the branch that has the changed files):
+
+ .. code-block:: bash
+
+ $ git diff --name-only master | egrep "\.c|\.h" | xargs echo | xargs ./tools/checkpatch.sh -f | less
+
+ Note that there are some bugs in the ``nxstyle`` program that ``checkpatch.sh`` uses, so
+ it may report a few errors that are not actually errors. The committers will help you
+ find these. (Or view the
+ `nxstyle Issues <https://github.com/apache/incubator-nuttx/issues?q=is%3Aissue+is%3Aopen+nxstyle>`_.)
+ |br|
+ |br|
+
+#. Commit the fixed files
+
+ .. code-block:: bash
+
+ $ git add my-file.c
+ $ git commit my-file.c
+ $ git push
+
+
+Submitting Your Changes to NuttX
+--------------------------------
+
+ Pull requests let you tell others about changes you've pushed to a branch in a repository on GitHub. Once a pull
+ request is opened, you can discuss and review the potential changes with collaborators and add follow-up commits
+ before your changes are merged into the base branch.
+
+ (from GitHub's `About pull requests <https://docs.github.com/en/github/collaborating-with-issues-and-pull-requests/about-pull-requests>`_ page)
+
+Before you do a Pull Request, the NuttX team will usually want all the changes you made in your branch "squashed" into
+a single commit, so that when they review your changes, there's a clean view of the history. If there are changes
+after Pull Request review feedback, they can be separate commits. Here's the easiest way I found to do that initial
+squash before submitting the Pull Request:
+
+#. Check out my branch
+
+ .. code-block:: bash
+
+ $ git checkout my-branch
+
+#. Rename it to ``my-branch-old`` to save it, because we're going to create new clean branch to push:
+
+ .. code-block:: bash
+
+ $ git branch -m my-branch-old
+
+#. Create a new clean branch with the same name you were using before the last step:
+
+ .. code-block:: bash
+
+ $ git checkout master
+ $ git checkout -b my-branch
+
+#. Merge your saved old branch into the new one, telling git to "squash" all your commits into one (note this will
+ not commit the result; the changed files will be in your staging area, ready to be committed):
+
+ .. code-block:: bash
+
+ $ git merge --squash my-branch-old
+
+#. Commit the result
+
+ .. code-block:: bash
+
+ $ git commit
+
+#. Force-push your new clean branch to the remote— this will overwrite all your previous changes in that branch:
+
+ .. code-block:: bash
+
+ $ git push -f --set-upstream origin my-branch
+
+#. Create a GitHub Pull Request
+
+ A Pull Request is how you ask your upstream to review and merge your changes.
+
+ Here's `GitHub's instructions for creating a Pull Request <https://help.github.com/en/github/collaborating-with-issues-and-pull-requests/creating-a-pull-request>`_.
+
+ |br|
+
+#. Get Pull Request feedback and implement changes
+
+ Get suggestions for improvements from reviewers, make changes, and push them to the branch. Once the reviewers are
+ happy, they may suggest squashing and merging again to make a single commit. In this case you would repeat steps
+ 1 through 6.
+
+Git Resources
+-------------
+
+* `Git Cheat Sheet (by GitHub) <https://github.github.com/training-kit/downloads/github-git-cheat-sheet.pdf>`_
+* `Git Book (online) <https://git-scm.com/book/en/v2>`_
+* `NuttX Code Contribution Workflow <https://cwiki.apache.org/confluence/display/NUTTX/Code+Contribution+Workflow>`_ –
Review comment:
@v01d I'll change the name to "Contribution Workflow Draft". The wiki is public on the Internet, though, so what about it isn't fit for public consumption?
----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [incubator-nuttx] v01d commented on a change in pull request #1677: Add Simulator and Drivers guides, and contributing instructions for new users
Posted by GitBox <gi...@apache.org>.
v01d commented on a change in pull request #1677:
URL: https://github.com/apache/incubator-nuttx/pull/1677#discussion_r480195487
##########
File path: Documentation/guides/simulator.rst
##########
@@ -0,0 +1,145 @@
+.. include:: /substitutions.rst
+.. _simulator:
+
+Simulator
+=========
+
+Apache NuttX has a simulator that can run as a regular program on Linux, Mac, and Windows computers.
+It's useful for debugging operating system features that aren't associated with particular
+device drivers— for instance the TCP/IP stack itself, a web interface or API for your
+application, or other communication protocols. It's also handy for trying out Apache NuttX without
+having a piece of embedded hardware.
+
+This guide assumes you're on Linux. It works on Windows and Mac too— if you know how,
+submit a PR the NuttX Companion to update this guide!
+
+Compiling
+---------
+
+#. Configure the Simulator
+
+ There are a lot of simulator configurations available that set you up to test various
+ operating system features.
+
+ Here we'll use the ``sim:tcpblaster`` configuration because it comes with networking
+ that is ready to use.
+
+ .. code-block:: bash
+
+ $ cd nuttx
+ $ ./tools/configure.sh sim:tcpblaster
+
+#. Compile
+
+ .. code-block:: bash
+
+ $ make clean; make
+
+Running
+-------
+
+#. Give the Simulator Privileges
+
+ On recent Linux distributions, you need to give the ``nuttx`` program the capabilities
+ (similar to permissions) to access the network:
+
+ .. code-block:: bash
+
+ $ sudo setcap cap_net_admin+ep ./nuttx
+
+#. Run the simulator:
+
+ .. code-block:: bash
+
+ $ ./nuttx
+
+#. Bring Up the Network Interfaces
+
+ On Apache NuttX:
+
+ .. code-block:: bash
+
+ nsh> ifup eth0
+
+ On Linux, first you need to find your main network interface— this will usually either
+ be an ethernet or wireless network adapter. Do this:
+
+ .. code-block:: bash
+
+ $ ifconfig
+ lo: flags=73<UP,LOOPBACK,RUNNING> mtu 65536
+ inet 127.0.0.1 netmask 255.0.0.0
+ inet6 ::1 prefixlen 128 scopeid 0x10<host>
+ loop txqueuelen 1000 (Local Loopback)
+ RX packets 5846 bytes 614351 (614.3 KB)
+ RX errors 0 dropped 0 overruns 0 frame 0
+ TX packets 5846 bytes 614351 (614.3 KB)
+ TX errors 0 dropped 0 overruns 0 carrier 0 collisions 0
+
+ wlp0s20f3: flags=4163<UP,BROADCAST,RUNNING,MULTICAST> mtu 1500
+ inet 192.168.1.209 netmask 255.255.255.0 broadcast 192.168.1.255
+ inet6 fe80::1161:c26b:af05:d784 prefixlen 64 scopeid 0x20<link>
+ ether 24:41:8c:a8:30:d1 txqueuelen 1000 (Ethernet)
+ RX packets 219369 bytes 176416490 (176.4 MB)
+ RX errors 0 dropped 0 overruns 0 frame 0
+ TX packets 108399 bytes 27213617 (27.2 MB)
+ TX errors 0 dropped 0 overruns 0 carrier 0 collisions 0
+
+ ``lo0`` is the Loopback Interface, so ``wlp0s20f3`` is the wireless interface. Note
+ that it has an IP address on the local net. There may be other interfaces listed, you'll
+ need to pick the one that's right for your system.
+
+ Then, on Linux do this to set up the tap network interface and route that will let
+ the Apache Nuttx simulator access the network:
+
+ .. code-block:: bash
+
+ $ sudo ./tools/simhostroute.sh wlp0s20f3 on
+ $ ping -c 1 10.0.1.2 # nuttx system
+ PING 10.0.1.2 (10.0.1.2) 56(84) bytes of data.
+ 64 bytes from 10.0.1.2: icmp_seq=1 ttl=64 time=7.52 ms
+
+ --- 10.0.1.2 ping statistics ---
+ 1 packets transmitted, 1 received, 0% packet loss, time 0ms
+ rtt min/avg/max/mdev = 7.529/7.529/7.529/0.000 m
+
+#. Test that Apache NuttX can access the Internet
+
+ First let's ping the network interface of our Linux host to prove we can see the
+ gateway to the Internet:
+
+ .. code-block:: bash
+
+ nsh> ping -c 1 10.0.1.1
+ nsh> ping -c 1 10.0.1.1
+ PING 10.0.1.1 56 bytes of data
+ 56 bytes from 10.0.1.1: icmp_seq=0 time=0 ms
+ 1 packets transmitted, 1 received, 0% packet loss, time 1010 ms
+
+ Now let's ping one of Google's DNS servers to prove we can access the rest of the
+ Internet:
+
+ .. code-block:: bash
+
+ nsh> ping -c 1 8.8.8.8
+ PING 8.8.8.8 56 bytes of data
+ 56 bytes from 8.8.8.8: icmp_seq=0 time=10 ms
+ 1 packets transmitted, 1 received, 0% packet loss, time 1010 ms
+
+ Success!
+
+Stopping
+--------
+
+The only really effective way to stop the simulator is kill it from another terminal:
+
+ .. code-block:: bash
+
+ $ pkill nuttx
Review comment:
The most direct way is to call "poweroff" within nuttx. But if you don't have a prompt, you need to kill as you shown so this can be a second instruction.
----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [incubator-nuttx] Ouss4 commented on a change in pull request #1677: Add Simulator and Drivers guides, and contributing instructions for new users
Posted by GitBox <gi...@apache.org>.
Ouss4 commented on a change in pull request #1677:
URL: https://github.com/apache/incubator-nuttx/pull/1677#discussion_r480255016
##########
File path: Documentation/contributing/making-changes.rst
##########
@@ -0,0 +1,256 @@
+.. include:: /substitutions.rst
+.. _making-changes:
+
+Making Changes
+==============
+
+If you want to make changes to NuttX, for your own personal use, or to submit them back to project to improve NuttX,
+that's easy. For the purposes of this guide, you'll need a `GitHub <https://www.github.com>`_ account, since
+the Apache NuttX team uses GitHub. (You could also use git locally, or save your changes to other sites like
+`GitLab <https://about.gitlab.com/>`_ or `BitBucket <https://bitbucket.org>`_, but that's beyond the scope of this
+guide).
+
+Here's how to do it:
+
+#. Set your git user name and email
+
+ .. code-block:: bash
+
+ $ cd nuttx/
+ $ git config --global user.name "Your Name"
+ $ git config --global user.email "yourname@somedomaincom"
+
+#. Sign in to GitHub
+
+ If you don't have a `GitHub <https://www.github.com>`_ account, it's free to
+ sign up.
+ |br|
+ |br|
+
+
+#. Fork the Project
+
+ Visit both these links and hit the Fork button in the upper right of the page:
+
+ * `NuttX <https://github.com/apache/incubator-nuttx/>`_
+ * `NuttX Apps <https://github.com/apache/incubator-nuttx-apps/>`_
+
+
+#. Change the Git Remotes
+
+ The git repositories in your project are currently connected to the official NuttX repositories, but you don't
+ have permission to push software there. But you can push them to your forks, and from there create Pull Requests
+ if you want to send them to the NuttX project.
+
+ First, remove the current remote, ``origin`` (we'll add it back later):
+
+ .. code-block:: bash
+
+ $ cd nuttx/
+ $ # display the remote
+ $ git remote -v
+
+ You should see something like this:
+
+ .. code-block:: bash
+
+ origin https://github.com/apache/incubator-nuttx.git
+
+ Now, on the GitHub web page for your forked ``incubator-nuttx`` project, copy the clone url – get it by hitting the
+ green ``Clone or Download`` button in the upper right. Then do this:
+
+ .. code-block:: bash
+
+ $ git remote rm origin
+ $ git remote add origin <your forked incubator-nuttx project clone url>
+ $ git remote add upstream https://github.com/apache/incubator-nuttx.git
+
+ Do the same for your forked ``incubator-nuttx-apps`` project:
+
+ .. code-block:: bash
+
+ $ cd ../apps
+ $ git remote rm origin
+ $ git remote add origin <your forked incubator-nuttx-apps project clone url>
+ $ git remote add upstream https://github.com/apache/incubator-nuttx-apps.git
+
+
+#. Create a Local Git Branch
+
+ Now you can create local git branches and push them to GitHub:
+
+ .. code-block:: bash
+
+ $ git checkout -b test/my-new-branch
+ $ git push
+
+
+Git Workflow With an Upstream Repository
+----------------------------------------
+
+The main NuttX git repository is called an "upstream" repository - this is because it's the main source of truth, and
+its changes flow downstream to people who've forked that repository, like us.
+
+Working with an upstream repo is a bit more complex, but it's worth it since you can submit fixes and features
+to the main NuttX repos. One of the things you need to do regularly is keep your local repo in sync
+with the upstream. I work with a local branch, make changes, pull new software from the upstream and merge it in,
+maybe doing that several times. Then when everything works, I get my branch ready to do a Pull Request. Here's how:
+
+#. Fetch upstream changes and merge into my local master:
+
+ .. code-block:: bash
+
+ $ git checkout master
+ $ git fetch upstream
+ $ git merge upstream/master
+ $ git push
+
+#. Merge my local master with my local branch:
+
+ .. code-block:: bash
+
+ $ git checkout my-local-branch
+ $ git merge master
+ $ git push
Review comment:
>I was wondering why we show
git rev-list
rev-list or any other count gives the number of commits the branch has. That number is then used for interactive (-i) rebasing.
> We also list the super long form option for force. No one is going to type that.
Maybe no one is going to type that, but that's not another form of -f. It's different from -f. --force-with-lease won't let you force push if there are commits upstream that you are going to delete.
----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [incubator-nuttx] v01d commented on a change in pull request #1677: Add Simulator and Drivers guides, and contributing instructions for new users
Posted by GitBox <gi...@apache.org>.
v01d commented on a change in pull request #1677:
URL: https://github.com/apache/incubator-nuttx/pull/1677#discussion_r480193404
##########
File path: Documentation/guides/simulator.rst
##########
@@ -0,0 +1,145 @@
+.. include:: /substitutions.rst
+.. _simulator:
+
+Simulator
+=========
+
+Apache NuttX has a simulator that can run as a regular program on Linux, Mac, and Windows computers.
+It's useful for debugging operating system features that aren't associated with particular
+device drivers— for instance the TCP/IP stack itself, a web interface or API for your
+application, or other communication protocols. It's also handy for trying out Apache NuttX without
+having a piece of embedded hardware.
+
+This guide assumes you're on Linux. It works on Windows and Mac too— if you know how,
+submit a PR the NuttX Companion to update this guide!
+
+Compiling
+---------
+
+#. Configure the Simulator
+
+ There are a lot of simulator configurations available that set you up to test various
+ operating system features.
+
+ Here we'll use the ``sim:tcpblaster`` configuration because it comes with networking
+ that is ready to use.
+
+ .. code-block:: bash
+
+ $ cd nuttx
+ $ ./tools/configure.sh sim:tcpblaster
Review comment:
Could we start with the simpler nsh config case? A second example can be this one with networking.
----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [incubator-nuttx] adamfeuer commented on a change in pull request #1677: Add Simulator and Drivers guides, and contributing instructions for new users
Posted by GitBox <gi...@apache.org>.
adamfeuer commented on a change in pull request #1677:
URL: https://github.com/apache/incubator-nuttx/pull/1677#discussion_r483853378
##########
File path: Documentation/contributing/making-changes.rst
##########
@@ -202,6 +202,56 @@ squash before submitting the Pull Request:
$ git checkout my-branch
+#. Fetch the upstream code
+
+ .. code-block:: bash
+
+ $ git fetch upstream
+
+#. Rebase onto the upstream code
+
+ * Your favorite text editor will start and shows the commands for the interactive rebasing.
+ * Change the "pick" to "squash" for all the commits you want to squash.
+ * For the series of commits to squash, keep the first one with "pick".
+ * Once you save and exist your editor will start again to merge all the commit messages.
+ * Add a commit message that best describes your change then save and exit.
+
+ .. code-block:: bash
+
+ $ git rebase upstream/master
+
+#. Push to your remote
+
+ This needs to a force push with ``-f``.
Review comment:
@v01d I do this flow all the time, and yes ``-f`` is needed, since you have an existing branch on the server with the same name.
----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [incubator-nuttx] btashton commented on pull request #1677: Add Simulator and Drivers guides, and contributing instructions for new users
Posted by GitBox <gi...@apache.org>.
btashton commented on pull request #1677:
URL: https://github.com/apache/incubator-nuttx/pull/1677#issuecomment-687426531
A couple minor comments, but I think this is in a good spot.
----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [incubator-nuttx] adamfeuer commented on a change in pull request #1677: Add Simulator and Drivers guides, and contributing instructions for new users
Posted by GitBox <gi...@apache.org>.
adamfeuer commented on a change in pull request #1677:
URL: https://github.com/apache/incubator-nuttx/pull/1677#discussion_r483863251
##########
File path: Documentation/guides/drivers.rst
##########
@@ -0,0 +1,211 @@
+.. include:: /substitutions.rst
+.. _drivers:
+
+Drivers
+=======
+
+Some NuttX boards don't have full support for all the on-chip peripherals. If you need support for this hardware,
+you will either need to port a driver from another chip, or write one yourself. This section discusses how to do that.
+
+Porting a Driver
+----------------
+
+Often support for on-chip peripherals exists in a closely related chip, or even a different family or from a different
+manufacturer. Many chips are made up of different Intellectual Property (IP) blocks that are licensed from vendors like
+Cadence, Synopsys, and others. The IP blocks may be similar enough to use another chip's driver with little
+modification.
+
+* Find a similar driver in NuttX source code:
+
+ * Look at register names listed in the datasheet for the peripheral.
+ * Search the NuttX codebase for the register names (try several different ones).
+ * Note that you'll have to compare the datasheet to the header and code files to see if there are differences; there
+ will usually be some differences between architectures, and they can be significant.
+
+* Find a similar driver in U-Boot source code:
+
+ * Only for inspiration, you can't copy code because of license incompatibility.
+ * But you can debug to see how the driver works.
+ * `U-Boot <https://www.denx.de/wiki/U-Boot>`_ drivers are often easier to understand than BSD Unix drivers because
+ U-Boot is simpler.
+
+* Find a similar driver in Zephyr or BSD Unix (OpenBSD, FreeBSD, NetBSD):
+
+ * If you find one, you can borrow code directly (Apache 2.0 and BSD licenses are compatible).
Review comment:
@btashton Even Apache License 2.0 code?
----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [incubator-nuttx] v01d commented on a change in pull request #1677: Add Simulator and Drivers guides, and contributing instructions for new users
Posted by GitBox <gi...@apache.org>.
v01d commented on a change in pull request #1677:
URL: https://github.com/apache/incubator-nuttx/pull/1677#discussion_r483852732
##########
File path: Documentation/contributing/making-changes.rst
##########
@@ -202,6 +202,56 @@ squash before submitting the Pull Request:
$ git checkout my-branch
+#. Fetch the upstream code
+
+ .. code-block:: bash
+
+ $ git fetch upstream
+
+#. Rebase onto the upstream code
+
+ * Your favorite text editor will start and shows the commands for the interactive rebasing.
+ * Change the "pick" to "squash" for all the commits you want to squash.
+ * For the series of commits to squash, keep the first one with "pick".
+ * Once you save and exist your editor will start again to merge all the commit messages.
+ * Add a commit message that best describes your change then save and exit.
+
+ .. code-block:: bash
+
+ $ git rebase upstream/master
+
+#. Push to your remote
+
+ This needs to a force push with ``-f``.
Review comment:
Force is not needed here since this would be the first push which creates the remote branch. The force will only be needed if you squash, for example, or if during reviews you are requested to rebase.
----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [incubator-nuttx] v01d commented on a change in pull request #1677: Add Simulator and Drivers guides, and contributing instructions for new users
Posted by GitBox <gi...@apache.org>.
v01d commented on a change in pull request #1677:
URL: https://github.com/apache/incubator-nuttx/pull/1677#discussion_r480194813
##########
File path: Documentation/guides/simulator.rst
##########
@@ -0,0 +1,145 @@
+.. include:: /substitutions.rst
+.. _simulator:
+
+Simulator
+=========
+
+Apache NuttX has a simulator that can run as a regular program on Linux, Mac, and Windows computers.
+It's useful for debugging operating system features that aren't associated with particular
+device drivers— for instance the TCP/IP stack itself, a web interface or API for your
+application, or other communication protocols. It's also handy for trying out Apache NuttX without
+having a piece of embedded hardware.
+
+This guide assumes you're on Linux. It works on Windows and Mac too— if you know how,
+submit a PR the NuttX Companion to update this guide!
+
+Compiling
+---------
+
+#. Configure the Simulator
+
+ There are a lot of simulator configurations available that set you up to test various
+ operating system features.
+
+ Here we'll use the ``sim:tcpblaster`` configuration because it comes with networking
+ that is ready to use.
+
+ .. code-block:: bash
+
+ $ cd nuttx
+ $ ./tools/configure.sh sim:tcpblaster
+
+#. Compile
+
+ .. code-block:: bash
+
+ $ make clean; make
+
+Running
+-------
+
+#. Give the Simulator Privileges
+
+ On recent Linux distributions, you need to give the ``nuttx`` program the capabilities
+ (similar to permissions) to access the network:
+
+ .. code-block:: bash
+
+ $ sudo setcap cap_net_admin+ep ./nuttx
+
+#. Run the simulator:
+
+ .. code-block:: bash
+
+ $ ./nuttx
+
+#. Bring Up the Network Interfaces
+
+ On Apache NuttX:
+
+ .. code-block:: bash
+
+ nsh> ifup eth0
+
+ On Linux, first you need to find your main network interface— this will usually either
+ be an ethernet or wireless network adapter. Do this:
+
+ .. code-block:: bash
Review comment:
remember to change these into "console"
----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [incubator-nuttx] Ouss4 commented on pull request #1677: Add Simulator and Drivers guides, and contributing instructions for new users
Posted by GitBox <gi...@apache.org>.
Ouss4 commented on pull request #1677:
URL: https://github.com/apache/incubator-nuttx/pull/1677#issuecomment-683865045
> Could you point out what are these differences? Maybe we can include something here
I'm trying to put them in comments as I'm reviewing.
----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [incubator-nuttx] v01d commented on a change in pull request #1677: Add Simulator and Drivers guides, and contributing instructions for new users
Posted by GitBox <gi...@apache.org>.
v01d commented on a change in pull request #1677:
URL: https://github.com/apache/incubator-nuttx/pull/1677#discussion_r480172765
##########
File path: Documentation/contributing/making-changes.rst
##########
@@ -0,0 +1,256 @@
+.. include:: /substitutions.rst
+.. _making-changes:
+
+Making Changes
+==============
+
+If you want to make changes to NuttX, for your own personal use, or to submit them back to project to improve NuttX,
+that's easy. For the purposes of this guide, you'll need a `GitHub <https://www.github.com>`_ account, since
+the Apache NuttX team uses GitHub. (You could also use git locally, or save your changes to other sites like
+`GitLab <https://about.gitlab.com/>`_ or `BitBucket <https://bitbucket.org>`_, but that's beyond the scope of this
+guide).
+
+Here's how to do it:
+
+#. Set your git user name and email
+
+ .. code-block:: bash
+
+ $ cd nuttx/
+ $ git config --global user.name "Your Name"
+ $ git config --global user.email "yourname@somedomaincom"
+
+#. Sign in to GitHub
+
+ If you don't have a `GitHub <https://www.github.com>`_ account, it's free to
+ sign up.
+ |br|
+ |br|
+
+
+#. Fork the Project
+
+ Visit both these links and hit the Fork button in the upper right of the page:
+
+ * `NuttX <https://github.com/apache/incubator-nuttx/>`_
+ * `NuttX Apps <https://github.com/apache/incubator-nuttx-apps/>`_
+
+
+#. Change the Git Remotes
+
+ The git repositories in your project are currently connected to the official NuttX repositories, but you don't
+ have permission to push software there. But you can push them to your forks, and from there create Pull Requests
+ if you want to send them to the NuttX project.
+
+ First, remove the current remote, ``origin`` (we'll add it back later):
+
+ .. code-block:: bash
+
+ $ cd nuttx/
+ $ # display the remote
+ $ git remote -v
+
+ You should see something like this:
+
+ .. code-block:: bash
+
+ origin https://github.com/apache/incubator-nuttx.git
+
+ Now, on the GitHub web page for your forked ``incubator-nuttx`` project, copy the clone url – get it by hitting the
+ green ``Clone or Download`` button in the upper right. Then do this:
+
+ .. code-block:: bash
+
+ $ git remote rm origin
+ $ git remote add origin <your forked incubator-nuttx project clone url>
+ $ git remote add upstream https://github.com/apache/incubator-nuttx.git
+
+ Do the same for your forked ``incubator-nuttx-apps`` project:
+
+ .. code-block:: bash
+
+ $ cd ../apps
+ $ git remote rm origin
+ $ git remote add origin <your forked incubator-nuttx-apps project clone url>
+ $ git remote add upstream https://github.com/apache/incubator-nuttx-apps.git
+
+
+#. Create a Local Git Branch
+
+ Now you can create local git branches and push them to GitHub:
+
+ .. code-block:: bash
+
+ $ git checkout -b test/my-new-branch
+ $ git push
+
+
+Git Workflow With an Upstream Repository
+----------------------------------------
+
+The main NuttX git repository is called an "upstream" repository - this is because it's the main source of truth, and
+its changes flow downstream to people who've forked that repository, like us.
+
+Working with an upstream repo is a bit more complex, but it's worth it since you can submit fixes and features
+to the main NuttX repos. One of the things you need to do regularly is keep your local repo in sync
+with the upstream. I work with a local branch, make changes, pull new software from the upstream and merge it in,
+maybe doing that several times. Then when everything works, I get my branch ready to do a Pull Request. Here's how:
+
+#. Fetch upstream changes and merge into my local master:
+
+ .. code-block:: bash
+
+ $ git checkout master
+ $ git fetch upstream
+ $ git merge upstream/master
+ $ git push
+
+#. Merge my local master with my local branch:
+
+ .. code-block:: bash
+
+ $ git checkout my-local-branch
+ $ git merge master
+ $ git push
+
+#. Make changes and push them to my fork
+
+ .. code-block:: bash
+
+ $ vim my-file.c
+ $ git add my-file.c
+ $ git commit my-file.c
+ $ git push
+
+#. Repeat 1-3 as necessary
+
+#. Run the ``tools/checkpatch.sh`` script on your files
+
+ When your code runs, then you're almost ready to submit it. But first you need to check the code to ensure
+ that it conforms to the NuttX :ref:`contributing/coding_style:C Coding Standard`.
+ The ``tools/checkpatch.sh`` script will do that. Here's the usage info:
+
+ .. code-block:: bash
+
+ $ ./tools/checkpatch.sh -h
+ USAGE: ./tools/checkpatch.sh [options] [list|-]
+
+ Options:
+ -h
+ -c spell check with codespell(install with: pip install codespell
+ -r range check only (used with -p and -g)
+ -p <patch list> (default)
+ -g <commit list>
+ -f <file list>
+ - read standard input mainly used by git pre-commit hook as below:
+ git diff --cached | ./tools/checkpatch.sh -
+
+ Run it against your files and correct all the errors in the code you added, so that
+ ``tools/checkpatch.sh`` reports no errors. Then commit the result.
+ For example:
+
+ .. code-block:: bash
+
+ $ ./tools/checkpatch.sh -f my-file.c
+ arch/arm/src/sama5/hardware/my-file.c:876:82: warning: Long line found
+ $ # fix errors
+ $ vim my-file.c
+ $ # run again
+ $ ./tools/checkpatch.sh -f my-file.c
+
+ If you have made a lot of changes, you can also use this bash commandline to see the errors for all the changed C
+ files in your branch (assumes you are currently on the branch that has the changed files):
+
+ .. code-block:: bash
+
+ $ git diff --name-only master | egrep "\.c|\.h" | xargs echo | xargs ./tools/checkpatch.sh -f | less
+
+ Note that there are some bugs in the ``nxstyle`` program that ``checkpatch.sh`` uses, so
+ it may report a few errors that are not actually errors. The committers will help you
+ find these. (Or view the
+ `nxstyle Issues <https://github.com/apache/incubator-nuttx/issues?q=is%3Aissue+is%3Aopen+nxstyle>`_.)
+ |br|
+ |br|
+
+#. Commit the fixed files
+
+ .. code-block:: bash
+
+ $ git add my-file.c
+ $ git commit my-file.c
+ $ git push
+
+
+Submitting Your Changes to NuttX
+--------------------------------
+
+ Pull requests let you tell others about changes you've pushed to a branch in a repository on GitHub. Once a pull
+ request is opened, you can discuss and review the potential changes with collaborators and add follow-up commits
+ before your changes are merged into the base branch.
+
+ (from GitHub's `About pull requests <https://docs.github.com/en/github/collaborating-with-issues-and-pull-requests/about-pull-requests>`_ page)
+
+Before you do a Pull Request, the NuttX team will usually want all the changes you made in your branch "squashed" into
+a single commit, so that when they review your changes, there's a clean view of the history. If there are changes
+after Pull Request review feedback, they can be separate commits. Here's the easiest way I found to do that initial
+squash before submitting the Pull Request:
+
+#. Check out my branch
+
+ .. code-block:: bash
+
+ $ git checkout my-branch
+
+#. Rename it to ``my-branch-old`` to save it, because we're going to create new clean branch to push:
+
+ .. code-block:: bash
+
+ $ git branch -m my-branch-old
Review comment:
I agree
----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [incubator-nuttx] adamfeuer commented on a change in pull request #1677: Add Simulator and Drivers guides, and contributing instructions for new users
Posted by GitBox <gi...@apache.org>.
adamfeuer commented on a change in pull request #1677:
URL: https://github.com/apache/incubator-nuttx/pull/1677#discussion_r483841079
##########
File path: Documentation/guides/simulator.rst
##########
@@ -0,0 +1,145 @@
+.. include:: /substitutions.rst
+.. _simulator:
+
+Simulator
+=========
+
+Apache NuttX has a simulator that can run as a regular program on Linux, Mac, and Windows computers.
+It's useful for debugging operating system features that aren't associated with particular
+device drivers— for instance the TCP/IP stack itself, a web interface or API for your
+application, or other communication protocols. It's also handy for trying out Apache NuttX without
+having a piece of embedded hardware.
+
+This guide assumes you're on Linux. It works on Windows and Mac too— if you know how,
+submit a PR the NuttX Companion to update this guide!
+
+Compiling
+---------
+
+#. Configure the Simulator
+
+ There are a lot of simulator configurations available that set you up to test various
+ operating system features.
+
+ Here we'll use the ``sim:tcpblaster`` configuration because it comes with networking
+ that is ready to use.
+
+ .. code-block:: bash
+
+ $ cd nuttx
+ $ ./tools/configure.sh sim:tcpblaster
+
+#. Compile
+
+ .. code-block:: bash
+
+ $ make clean; make
+
+Running
+-------
+
+#. Give the Simulator Privileges
+
+ On recent Linux distributions, you need to give the ``nuttx`` program the capabilities
+ (similar to permissions) to access the network:
+
+ .. code-block:: bash
+
+ $ sudo setcap cap_net_admin+ep ./nuttx
+
+#. Run the simulator:
+
+ .. code-block:: bash
+
+ $ ./nuttx
+
+#. Bring Up the Network Interfaces
+
+ On Apache NuttX:
+
+ .. code-block:: bash
+
+ nsh> ifup eth0
+
+ On Linux, first you need to find your main network interface— this will usually either
+ be an ethernet or wireless network adapter. Do this:
+
+ .. code-block:: bash
+
+ $ ifconfig
+ lo: flags=73<UP,LOOPBACK,RUNNING> mtu 65536
+ inet 127.0.0.1 netmask 255.0.0.0
+ inet6 ::1 prefixlen 128 scopeid 0x10<host>
+ loop txqueuelen 1000 (Local Loopback)
+ RX packets 5846 bytes 614351 (614.3 KB)
+ RX errors 0 dropped 0 overruns 0 frame 0
+ TX packets 5846 bytes 614351 (614.3 KB)
+ TX errors 0 dropped 0 overruns 0 carrier 0 collisions 0
+
+ wlp0s20f3: flags=4163<UP,BROADCAST,RUNNING,MULTICAST> mtu 1500
+ inet 192.168.1.209 netmask 255.255.255.0 broadcast 192.168.1.255
+ inet6 fe80::1161:c26b:af05:d784 prefixlen 64 scopeid 0x20<link>
+ ether 24:41:8c:a8:30:d1 txqueuelen 1000 (Ethernet)
+ RX packets 219369 bytes 176416490 (176.4 MB)
+ RX errors 0 dropped 0 overruns 0 frame 0
+ TX packets 108399 bytes 27213617 (27.2 MB)
+ TX errors 0 dropped 0 overruns 0 carrier 0 collisions 0
+
+ ``lo0`` is the Loopback Interface, so ``wlp0s20f3`` is the wireless interface. Note
+ that it has an IP address on the local net. There may be other interfaces listed, you'll
+ need to pick the one that's right for your system.
+
+ Then, on Linux do this to set up the tap network interface and route that will let
+ the Apache Nuttx simulator access the network:
+
+ .. code-block:: bash
+
+ $ sudo ./tools/simhostroute.sh wlp0s20f3 on
+ $ ping -c 1 10.0.1.2 # nuttx system
+ PING 10.0.1.2 (10.0.1.2) 56(84) bytes of data.
+ 64 bytes from 10.0.1.2: icmp_seq=1 ttl=64 time=7.52 ms
+
+ --- 10.0.1.2 ping statistics ---
+ 1 packets transmitted, 1 received, 0% packet loss, time 0ms
+ rtt min/avg/max/mdev = 7.529/7.529/7.529/0.000 m
+
+#. Test that Apache NuttX can access the Internet
+
+ First let's ping the network interface of our Linux host to prove we can see the
+ gateway to the Internet:
+
+ .. code-block:: bash
+
+ nsh> ping -c 1 10.0.1.1
+ nsh> ping -c 1 10.0.1.1
+ PING 10.0.1.1 56 bytes of data
+ 56 bytes from 10.0.1.1: icmp_seq=0 time=0 ms
+ 1 packets transmitted, 1 received, 0% packet loss, time 1010 ms
+
+ Now let's ping one of Google's DNS servers to prove we can access the rest of the
+ Internet:
+
+ .. code-block:: bash
+
+ nsh> ping -c 1 8.8.8.8
+ PING 8.8.8.8 56 bytes of data
+ 56 bytes from 8.8.8.8: icmp_seq=0 time=10 ms
+ 1 packets transmitted, 1 received, 0% packet loss, time 1010 ms
+
+ Success!
+
+Stopping
+--------
+
+The only really effective way to stop the simulator is kill it from another terminal:
+
+ .. code-block:: bash
+
+ $ pkill nuttx
+
+
+
+Debugging
+---------
+
+You can debug the simulator like any regular Linux program.
Review comment:
@v01d Let's do this in another PR.
----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [incubator-nuttx] btashton commented on a change in pull request #1677: Add Simulator and Drivers guides, and contributing instructions for new users
Posted by GitBox <gi...@apache.org>.
btashton commented on a change in pull request #1677:
URL: https://github.com/apache/incubator-nuttx/pull/1677#discussion_r480247495
##########
File path: Documentation/contributing/making-changes.rst
##########
@@ -0,0 +1,256 @@
+.. include:: /substitutions.rst
+.. _making-changes:
+
+Making Changes
+==============
+
+If you want to make changes to NuttX, for your own personal use, or to submit them back to project to improve NuttX,
+that's easy. For the purposes of this guide, you'll need a `GitHub <https://www.github.com>`_ account, since
+the Apache NuttX team uses GitHub. (You could also use git locally, or save your changes to other sites like
+`GitLab <https://about.gitlab.com/>`_ or `BitBucket <https://bitbucket.org>`_, but that's beyond the scope of this
+guide).
+
+Here's how to do it:
+
+#. Set your git user name and email
+
+ .. code-block:: bash
+
+ $ cd nuttx/
+ $ git config --global user.name "Your Name"
+ $ git config --global user.email "yourname@somedomaincom"
+
+#. Sign in to GitHub
+
+ If you don't have a `GitHub <https://www.github.com>`_ account, it's free to
+ sign up.
+ |br|
+ |br|
+
+
+#. Fork the Project
+
+ Visit both these links and hit the Fork button in the upper right of the page:
+
+ * `NuttX <https://github.com/apache/incubator-nuttx/>`_
+ * `NuttX Apps <https://github.com/apache/incubator-nuttx-apps/>`_
+
+
+#. Change the Git Remotes
+
+ The git repositories in your project are currently connected to the official NuttX repositories, but you don't
+ have permission to push software there. But you can push them to your forks, and from there create Pull Requests
+ if you want to send them to the NuttX project.
+
+ First, remove the current remote, ``origin`` (we'll add it back later):
+
+ .. code-block:: bash
+
+ $ cd nuttx/
+ $ # display the remote
+ $ git remote -v
+
+ You should see something like this:
+
+ .. code-block:: bash
+
+ origin https://github.com/apache/incubator-nuttx.git
+
+ Now, on the GitHub web page for your forked ``incubator-nuttx`` project, copy the clone url – get it by hitting the
+ green ``Clone or Download`` button in the upper right. Then do this:
+
+ .. code-block:: bash
+
+ $ git remote rm origin
+ $ git remote add origin <your forked incubator-nuttx project clone url>
+ $ git remote add upstream https://github.com/apache/incubator-nuttx.git
+
+ Do the same for your forked ``incubator-nuttx-apps`` project:
+
+ .. code-block:: bash
+
+ $ cd ../apps
+ $ git remote rm origin
+ $ git remote add origin <your forked incubator-nuttx-apps project clone url>
+ $ git remote add upstream https://github.com/apache/incubator-nuttx-apps.git
+
+
+#. Create a Local Git Branch
+
+ Now you can create local git branches and push them to GitHub:
+
+ .. code-block:: bash
+
+ $ git checkout -b test/my-new-branch
+ $ git push
+
+
+Git Workflow With an Upstream Repository
+----------------------------------------
+
+The main NuttX git repository is called an "upstream" repository - this is because it's the main source of truth, and
+its changes flow downstream to people who've forked that repository, like us.
+
+Working with an upstream repo is a bit more complex, but it's worth it since you can submit fixes and features
+to the main NuttX repos. One of the things you need to do regularly is keep your local repo in sync
+with the upstream. I work with a local branch, make changes, pull new software from the upstream and merge it in,
+maybe doing that several times. Then when everything works, I get my branch ready to do a Pull Request. Here's how:
+
+#. Fetch upstream changes and merge into my local master:
+
+ .. code-block:: bash
+
+ $ git checkout master
+ $ git fetch upstream
+ $ git merge upstream/master
+ $ git push
+
+#. Merge my local master with my local branch:
+
+ .. code-block:: bash
+
+ $ git checkout my-local-branch
+ $ git merge master
+ $ git push
Review comment:
```
git fetch upstream
git rebase upstream/master
git push -u <your remote> -f
```
The `-u` is optional if you already have the tracking branch configured, I just do it to not make the mistake of pushing to upstream where I have permissions.
----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [incubator-nuttx] v01d commented on a change in pull request #1677: Add Simulator and Drivers guides, and contributing instructions for new users
Posted by GitBox <gi...@apache.org>.
v01d commented on a change in pull request #1677:
URL: https://github.com/apache/incubator-nuttx/pull/1677#discussion_r480194558
##########
File path: Documentation/guides/simulator.rst
##########
@@ -0,0 +1,145 @@
+.. include:: /substitutions.rst
+.. _simulator:
+
+Simulator
+=========
+
+Apache NuttX has a simulator that can run as a regular program on Linux, Mac, and Windows computers.
+It's useful for debugging operating system features that aren't associated with particular
+device drivers— for instance the TCP/IP stack itself, a web interface or API for your
+application, or other communication protocols. It's also handy for trying out Apache NuttX without
+having a piece of embedded hardware.
+
+This guide assumes you're on Linux. It works on Windows and Mac too— if you know how,
+submit a PR the NuttX Companion to update this guide!
+
+Compiling
+---------
+
+#. Configure the Simulator
+
+ There are a lot of simulator configurations available that set you up to test various
+ operating system features.
+
+ Here we'll use the ``sim:tcpblaster`` configuration because it comes with networking
+ that is ready to use.
+
+ .. code-block:: bash
+
+ $ cd nuttx
+ $ ./tools/configure.sh sim:tcpblaster
+
+#. Compile
+
+ .. code-block:: bash
+
+ $ make clean; make
+
+Running
+-------
+
+#. Give the Simulator Privileges
+
+ On recent Linux distributions, you need to give the ``nuttx`` program the capabilities
+ (similar to permissions) to access the network:
+
+ .. code-block:: bash
+
+ $ sudo setcap cap_net_admin+ep ./nuttx
+
+#. Run the simulator:
+
+ .. code-block:: bash
+
+ $ ./nuttx
Review comment:
I would add a nsh "help" call showing available applications and then running "hello"
----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [incubator-nuttx] adamfeuer commented on a change in pull request #1677: Add Simulator and Drivers guides, and contributing instructions for new users
Posted by GitBox <gi...@apache.org>.
adamfeuer commented on a change in pull request #1677:
URL: https://github.com/apache/incubator-nuttx/pull/1677#discussion_r483830347
##########
File path: Documentation/contributing/making-changes.rst
##########
@@ -0,0 +1,256 @@
+.. include:: /substitutions.rst
+.. _making-changes:
+
+Making Changes
+==============
+
+If you want to make changes to NuttX, for your own personal use, or to submit them back to project to improve NuttX,
+that's easy. For the purposes of this guide, you'll need a `GitHub <https://www.github.com>`_ account, since
+the Apache NuttX team uses GitHub. (You could also use git locally, or save your changes to other sites like
+`GitLab <https://about.gitlab.com/>`_ or `BitBucket <https://bitbucket.org>`_, but that's beyond the scope of this
+guide).
+
+Here's how to do it:
+
+#. Set your git user name and email
+
+ .. code-block:: bash
+
+ $ cd nuttx/
+ $ git config --global user.name "Your Name"
+ $ git config --global user.email "yourname@somedomaincom"
+
+#. Sign in to GitHub
+
+ If you don't have a `GitHub <https://www.github.com>`_ account, it's free to
+ sign up.
+ |br|
+ |br|
+
+
+#. Fork the Project
+
+ Visit both these links and hit the Fork button in the upper right of the page:
+
+ * `NuttX <https://github.com/apache/incubator-nuttx/>`_
+ * `NuttX Apps <https://github.com/apache/incubator-nuttx-apps/>`_
+
+
+#. Change the Git Remotes
+
+ The git repositories in your project are currently connected to the official NuttX repositories, but you don't
+ have permission to push software there. But you can push them to your forks, and from there create Pull Requests
+ if you want to send them to the NuttX project.
+
+ First, remove the current remote, ``origin`` (we'll add it back later):
+
+ .. code-block:: bash
+
+ $ cd nuttx/
+ $ # display the remote
+ $ git remote -v
+
+ You should see something like this:
+
+ .. code-block:: bash
+
+ origin https://github.com/apache/incubator-nuttx.git
+
+ Now, on the GitHub web page for your forked ``incubator-nuttx`` project, copy the clone url – get it by hitting the
+ green ``Clone or Download`` button in the upper right. Then do this:
+
+ .. code-block:: bash
+
+ $ git remote rm origin
+ $ git remote add origin <your forked incubator-nuttx project clone url>
+ $ git remote add upstream https://github.com/apache/incubator-nuttx.git
+
+ Do the same for your forked ``incubator-nuttx-apps`` project:
+
+ .. code-block:: bash
+
+ $ cd ../apps
+ $ git remote rm origin
+ $ git remote add origin <your forked incubator-nuttx-apps project clone url>
+ $ git remote add upstream https://github.com/apache/incubator-nuttx-apps.git
+
+
+#. Create a Local Git Branch
+
+ Now you can create local git branches and push them to GitHub:
+
+ .. code-block:: bash
+
+ $ git checkout -b test/my-new-branch
+ $ git push
+
+
+Git Workflow With an Upstream Repository
+----------------------------------------
+
+The main NuttX git repository is called an "upstream" repository - this is because it's the main source of truth, and
+its changes flow downstream to people who've forked that repository, like us.
+
+Working with an upstream repo is a bit more complex, but it's worth it since you can submit fixes and features
+to the main NuttX repos. One of the things you need to do regularly is keep your local repo in sync
+with the upstream. I work with a local branch, make changes, pull new software from the upstream and merge it in,
+maybe doing that several times. Then when everything works, I get my branch ready to do a Pull Request. Here's how:
+
+#. Fetch upstream changes and merge into my local master:
+
+ .. code-block:: bash
+
+ $ git checkout master
+ $ git fetch upstream
+ $ git merge upstream/master
+ $ git push
+
+#. Merge my local master with my local branch:
+
+ .. code-block:: bash
+
+ $ git checkout my-local-branch
+ $ git merge master
+ $ git push
+
+#. Make changes and push them to my fork
+
+ .. code-block:: bash
+
+ $ vim my-file.c
+ $ git add my-file.c
+ $ git commit my-file.c
+ $ git push
+
+#. Repeat 1-3 as necessary
+
+#. Run the ``tools/checkpatch.sh`` script on your files
+
+ When your code runs, then you're almost ready to submit it. But first you need to check the code to ensure
+ that it conforms to the NuttX :ref:`contributing/coding_style:C Coding Standard`.
+ The ``tools/checkpatch.sh`` script will do that. Here's the usage info:
+
+ .. code-block:: bash
+
+ $ ./tools/checkpatch.sh -h
+ USAGE: ./tools/checkpatch.sh [options] [list|-]
+
+ Options:
+ -h
+ -c spell check with codespell(install with: pip install codespell
+ -r range check only (used with -p and -g)
+ -p <patch list> (default)
+ -g <commit list>
+ -f <file list>
+ - read standard input mainly used by git pre-commit hook as below:
+ git diff --cached | ./tools/checkpatch.sh -
+
+ Run it against your files and correct all the errors in the code you added, so that
+ ``tools/checkpatch.sh`` reports no errors. Then commit the result.
+ For example:
+
+ .. code-block:: bash
+
+ $ ./tools/checkpatch.sh -f my-file.c
+ arch/arm/src/sama5/hardware/my-file.c:876:82: warning: Long line found
+ $ # fix errors
+ $ vim my-file.c
+ $ # run again
+ $ ./tools/checkpatch.sh -f my-file.c
+
+ If you have made a lot of changes, you can also use this bash commandline to see the errors for all the changed C
+ files in your branch (assumes you are currently on the branch that has the changed files):
+
+ .. code-block:: bash
+
+ $ git diff --name-only master | egrep "\.c|\.h" | xargs echo | xargs ./tools/checkpatch.sh -f | less
+
+ Note that there are some bugs in the ``nxstyle`` program that ``checkpatch.sh`` uses, so
+ it may report a few errors that are not actually errors. The committers will help you
+ find these. (Or view the
+ `nxstyle Issues <https://github.com/apache/incubator-nuttx/issues?q=is%3Aissue+is%3Aopen+nxstyle>`_.)
+ |br|
+ |br|
+
+#. Commit the fixed files
+
+ .. code-block:: bash
+
+ $ git add my-file.c
+ $ git commit my-file.c
+ $ git push
+
+
+Submitting Your Changes to NuttX
+--------------------------------
+
+ Pull requests let you tell others about changes you've pushed to a branch in a repository on GitHub. Once a pull
+ request is opened, you can discuss and review the potential changes with collaborators and add follow-up commits
+ before your changes are merged into the base branch.
+
+ (from GitHub's `About pull requests <https://docs.github.com/en/github/collaborating-with-issues-and-pull-requests/about-pull-requests>`_ page)
+
+Before you do a Pull Request, the NuttX team will usually want all the changes you made in your branch "squashed" into
+a single commit, so that when they review your changes, there's a clean view of the history. If there are changes
+after Pull Request review feedback, they can be separate commits. Here's the easiest way I found to do that initial
+squash before submitting the Pull Request:
+
+#. Check out my branch
+
+ .. code-block:: bash
+
+ $ git checkout my-branch
+
+#. Rename it to ``my-branch-old`` to save it, because we're going to create new clean branch to push:
+
+ .. code-block:: bash
+
+ $ git branch -m my-branch-old
Review comment:
@Ouss4 @v01d Will you post a rebase flow in reply to this comment, and I'll update the docs to have this flow as the first option.
I use the flow that's shown here, and it seems to be equivalent, so I'd like to leave it in as a second option. Do you have objections to that?
----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [incubator-nuttx] btashton commented on pull request #1677: Add Simulator and Drivers guides, and contributing instructions for new users
Posted by GitBox <gi...@apache.org>.
btashton commented on pull request #1677:
URL: https://github.com/apache/incubator-nuttx/pull/1677#issuecomment-687422706
Did you guys know when you look at the diff you can switch to the rich diff view by clicking the "page" icon in the corner. I guess I had seen this for markdown but not rst.
----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [incubator-nuttx] v01d commented on a change in pull request #1677: Add Simulator and Drivers guides, and contributing instructions for new users
Posted by GitBox <gi...@apache.org>.
v01d commented on a change in pull request #1677:
URL: https://github.com/apache/incubator-nuttx/pull/1677#discussion_r483856080
##########
File path: Documentation/contributing/making-changes.rst
##########
@@ -202,6 +202,56 @@ squash before submitting the Pull Request:
$ git checkout my-branch
+#. Fetch the upstream code
+
+ .. code-block:: bash
+
+ $ git fetch upstream
+
+#. Rebase onto the upstream code
+
+ * Your favorite text editor will start and shows the commands for the interactive rebasing.
+ * Change the "pick" to "squash" for all the commits you want to squash.
+ * For the series of commits to squash, keep the first one with "pick".
+ * Once you save and exist your editor will start again to merge all the commit messages.
+ * Add a commit message that best describes your change then save and exit.
+
+ .. code-block:: bash
+
+ $ git rebase upstream/master
+
+#. Push to your remote
+
+ This needs to a force push with ``-f``.
Review comment:
Ah, I didn't see the previous git push to the fork, sorry.
----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org