[docs][syscalls] Add TODOs about documenting system call rights

ZX-2399 #comment

Test: no functional change
Change-Id: I1f285c677e2444fcf1d720d7ecbd9f490c303962

[docs][syscalls] Clarify ZX_ERR_NO_MEMORY as eventually going away

Not touched:
vmo_op_range.md
vmo_set_size.md
vmo_write.md
The current text is ok for these.

ZX-2303 #comment patch

Tested: Just doc changes, read before/after.

Change-Id: I2c6e1039e2b205e9cc377b9888755fa7ac676c78

[docs] Clarify level-triggered nature of signals

Previously, the docs were unclear if you read them with a pre-conceived
notion that signals were edge-triggered (as "signals" are in POSIX).

Change-Id: I52bbd7eb652002ecd5479926a6fa1c6c677a4985

[syscalls] Update parameter types and names

This CL updates the parameter types and names for a number of syscalls
to match the Zircon System API rubric. There's more work to do to make
all the syscalls conform to the rubric, but this change is a start.

Change-Id: I218ac5e7e0cbd80a8c69fef7891ad40b78b6b407

[docs][syscalls] improve object_wait_many() docs

Change-Id: I9575906b059c72cae9089bc3228892ccde0047e2

[rights][syscalls] introduce ZX_RIGHT_WAIT

This right governs the ability to wait_one(), wait_many(),
or wait_async() on an object. Previously ZX_RIGHT_READ
governed this.

Adjusts userspace and test code to include ZX_RIGHT_WAIT in
various zx_handle_duplicate() and zx_handle_replace() calls.

Change-Id: I92ff9f976150d17f81bf4f3d2a36781e37833060

[docs][wait] Tweak object_wait_many doc

- Add a link to port.md
- Remove erroneous reference to ERR_INVALID_ARGS return value
- Clear up one sentence

Change-Id: I5d9c0f9e150a795fcf3d78f0bde4e103a6622e06

[zircon][abi] limit wait_many to eight handles

For larger wait sets, ports are the correct tool for the job.
Wait Many is intended to cover the "I need to wait for 2 or 3 things"
case.

Introduced the ZX_WAIT_MANY_MAX_ITEMS constant and updated the manual page.

This avoids heap allocations in the kernel for wait many (which could
be as large as 50k with the old 1024 handle limit), and will allow us
to move to an always-inline strategy.

It discourages users of wait many from using large sets which, even
ignoring the allocation issue, are highly inefficient (having to create
and register a wait state observer for every handle and deregister
after).

This will impact poll(), ppoll(), and select() which will fail for
more than eight items now. Slow-path versions could be provided,
but better would be to reintroduce epoll() on top of ports.

Change-Id: Ib8874a8880ac285441789c5f69abaf00a92976cb

[zx] Magenta -> Zircon

The Great Renaming is here!

Change-Id: I3229bdeb2a3d0e40fb4db6fec8ca7d971fbffb94

[docs][errors] Rename all the errors in docs/ to MX_OK and MX_ERR_*

Change-Id: I62451456a83145760c6454a619d4c699ce8e9017

[syscalls] Switch all syscall interfaces to deadlines

Change-Id: If1c2540b7aa3d16e8080551100b19fb1a067be8c

[errors] stop using deprecated ERR_HANDLE_CLOSED

Instead use ERR_CANCELED, its new name.

Change-Id: I2671a6eded761b6b06737c93b3289c2b8a46d8bd

[docs][syscalls] Fix all the manpages

Change-Id: Ie9ba25060f3331de8d9c178caf6332fb48fc80f5

[syscalls] rename mx_handle_wait_*() to mx_object_wait_*()

These act on the object the handle refers to, not the handle itself.

Compatibility wrappers are provided to ensure existing code
continues to compile, link, and run. Later we will deprecate
the wrappers and eventually remove them.

Change-Id: Icf69e75f7e0c060ba6026343f9d26ff9da4317d9