From ca2926f595afde4c6ad1f87996a17c1556fa6e02 Mon Sep 17 00:00:00 2001
From: Joel Sherrill <joel@rtems.org>
Date: Fri, 10 Mar 2017 15:01:36 -0600
Subject: POSIX Users: Add posix_devctl()

---
 posix-users/devctl.rst | 75 ++++++++++++++++++++++++++++++++++++++++++++++++++
 posix-users/index.rst  |  1 +
 2 files changed, 76 insertions(+)
 create mode 100644 posix-users/devctl.rst

(limited to 'posix-users')

diff --git a/posix-users/devctl.rst b/posix-users/devctl.rst
new file mode 100644
index 0000000..1282bdd
--- /dev/null
+++ b/posix-users/devctl.rst
@@ -0,0 +1,75 @@
+.. comment SPDX-License-Identifier: CC-BY-SA-4.0
+
+.. COMMENT: COPYRIGHT(c) 2017.
+.. COMMENT: On-Line Applications Research Corporation(OAR).
+.. COMMENT: All rights reserved.
+
+Device Control
+##############
+
+Introduction
+============
+
+The POSIX Device Control API is defined by POSIX 1003.26 and attempts
+to provides a portable alternative to the ioctl() service which is
+not standardized across POSIX implementations.  Support for this
+standard is required by the Open Group's FACE Technical Standard
+:cits:"FACE:2012:FTS".  Unfortunately, this part of the POSIX standard
+is not widely implemented.
+
+The services provided by the timer manager are:
+
+- posix_devctl_ - Control a Device
+
+Background
+==========
+
+Operations
+==========
+
+System Calls
+============
+
+This section details the POSIX device control's services.  A subsection
+is dedicated to each of this manager's services and describes the calling
+sequence, related constants, usage, and status codes.
+
+.. COMMENT: posix_devctl
+
+.. _posix_devctl
+
+posix_devctl - Control a Device
+-------------------------------
+
+**CALLING SEQUENCE:**
+
+.. code-block:: c
+
+    #include <devctl.h>
+    int posix_devctl(
+      int            fd,
+      int            dcmd,
+      void *restrict dev_data_ptr,
+      size_t         nbyte,
+      int *restrict  dev_info_ptr
+    );
+
+**STATUS CODES:**
+
+The status codes returned reflect those returned by the ``ioctl()`` service
+and the underlying device drivers.
+
+**DESCRIPTION:**
+
+This method is intended to be a portable alternative to the ``ioctl()``
+method. The RTEMS implementation follows what is referred to as a library
+implementation which is a simple wrapper for the ``ioctl()`` method.
+The fd, fcmd, dev_data_ptr, and nbyte parameters are passed unmodified
+to the ``ioctl()`` method.
+
+If the dev_info_ptr parameter is not NULL, then the location pointed
+to by dev_info_ptr is set to 0.
+
+**NOTES:**
+
+NONE
diff --git a/posix-users/index.rst b/posix-users/index.rst
index b2e2154..9731702 100644
--- a/posix-users/index.rst
+++ b/posix-users/index.rst
@@ -60,6 +60,7 @@ to the Community Project hosted at http://www.rtems.org/.
 	thread_cancellation
 	services_provided_by_c
 	services_provided_by_math
+	devctl
 	status_of_implementation
 	command
 
-- 
cgit v1.2.3