ChibiOS/os/xhal/codegen/hal_buffered_serial.xml

<?xml version="1.0" encoding="UTF-8"?>
<module xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:noNamespaceSchemaLocation="http://www.chibios.org/xml/schema/ccode/modules.xsd"
  name="hal_buffered_serial" descr="Buffered Serial Driver" editcode="false">
  <brief>Common ancestor of drivers based on circular I/O buffers.</brief>
  <details><![CDATA[This class implements a channel interface and links
    it to two circular I/O queues.]]></details>
  <imports>
    <import>hal_base_driver.xml</import>
    <import>hal_channels.xml</import>
  </imports>
  <public>
    <types>
      <class type="abstract" name="hal_buffered_serial" namespace="bs"
        ancestorname="hal_base_driver" descr="HAL buffered serial driver">
        <brief>Ancestor class of serial buffered drivers.</brief>
        <implements>
          <if name="asynchronous_channel">
            <method shortname="write">
              <implementation><![CDATA[

return oqWriteTimeout(&self->oqueue, bp, n, TIME_INFINITE);]]></implementation>
            </method>
            <method shortname="read">
              <implementation><![CDATA[

return iqReadTimeout(&self->iqueue, bp, n, TIME_INFINITE);]]></implementation>
            </method>
            <method shortname="put">
              <implementation><![CDATA[

return oqPutTimeout(&self->oqueue, b, TIME_INFINITE);]]></implementation>
            </method>
            <method shortname="get">
              <implementation><![CDATA[

return iqGetTimeout(&self->iqueue, TIME_INFINITE);]]></implementation>
            </method>
              <method shortname="unget">
                <implementation><![CDATA[

(void)self;
(void)b;

return STM_RESET;]]></implementation>
              </method>
            <method shortname="writet">
              <implementation><![CDATA[

return oqWriteTimeout(&self->oqueue, bp, n, timeout);]]></implementation>
            </method>
            <method shortname="readt">
              <implementation><![CDATA[

return iqReadTimeout(&self->iqueue, bp, n, timeout);]]></implementation>
            </method>
            <method shortname="putt">
              <implementation><![CDATA[

return oqPutTimeout(&self->oqueue, b, timeout);]]></implementation>
            </method>
            <method shortname="gett">
              <implementation><![CDATA[

return iqGetTimeout(&self->iqueue, timeout);]]></implementation>
            </method>
            <method shortname="getclr">
              <implementation><![CDATA[

(void)self;
(void)mask;

return 0;]]></implementation>
            </method>
            <method shortname="ctl">
              <implementation><![CDATA[

(void)self;
(void)operation;
(void)arg;

return 0;]]></implementation>
            </method>
          </if>
        </implements>
        <fields>
          <field name="iqueue" ctype="input_queue_t">
            <brief>Input queue.</brief>
          </field>
          <field name="oqueue" ctype="output_queue_t">
            <brief>Output queue.</brief>
          </field>
          <field name="event" ctype="event_source_t">
            <brief>I/O condition event source.</brief>
          </field>
        </fields>
        <methods>
          <objinit callsuper="true">
            <param name="ib" ctype="uint8_t *" dir="in">
              pointer to the input
              buffer
            </param>
            <param name="ibsize" ctype="size_t" dir="in">
              size of the input
              buffer
            </param>
            <param name="inotify" ctype="qnotify_t" dir="in"><![CDATA[pointer
              to a callback function that is invoked when some data is read
              from the input queue. The value can be @p NULL]]></param>
            <param name="iarg" ctype="void *" dir="in">
              parameter for the input
              notification callback
            </param>
            <param name="ob" ctype="uint8_t *" dir="in">
              pointer to the output
              buffer
            </param>
            <param name="obsize" ctype="size_t" dir="in">
              size of the output
              buffer
            </param>
            <param name="onotify" ctype="qnotify_t" dir="in"><![CDATA[pointer
              to a callback function that is invoked when some data is written
              to the output queue. The value can be @p NULL]]></param>
            <param name="oarg" ctype="void *" dir="in">
              parameter for the output
              notification callback
            </param>
            <implementation><![CDATA[

osalEventObjectInit(&self->event);
iqObjectInit(&self->iqueue, ib, ibsize, inotify, iarg);
oqObjectInit(&self->oqueue, ob, obsize, onotify, oarg);]]></implementation>
          </objinit>
          <dispose>
            <implementation><![CDATA[ ]]></implementation>
          </dispose>
          <regular>
            <method name="bsIncomingDataI" ctype="void">
              <brief>Handles incoming data.</brief>
              <details><![CDATA[This function must be called from the input
                interrupt service routine in order to enqueue incoming data
                and generate the related events.]]></details>
              <note><![CDATA[The incoming data event is only generated when
                the input queue becomes non-empty.]]></note>
              <param name="b" ctype="uint8_t" dir="in"> the byte to be written
                to the driver's Input Queue
              </param>
              <implementation><![CDATA[

osalDbgCheckClassI();
osalDbgCheck(self != NULL);

if (iqIsEmptyI(&self->iqueue)) {
  bsAddFlagsI(self, CHN_FL_RX_NOTEMPTY);
}

if (iqPutI(&self->iqueue, b) < MSG_OK) {
  bsAddFlagsI(self, CHN_FL_BUFFER_FULL_ERR);
}]]></implementation>
            </method>
            <method name="bsRequestDataI" ctype="msg_t">
              <brief>Handles outgoing data.</brief>
              <details><![CDATA[Must be called from the output interrupt
                service routine in order to get the next byte to be
                transmitted.]]></details>
              <return> The byte value read from the driver's output queue.
              </return>
              <retval value="MSG_TIMEOUT">If the queue is empty.</retval>
              <implementation><![CDATA[
msg_t  b;

osalDbgCheckClassI();
osalDbgCheck(self != NULL);

b = oqGetI(&self->oqueue);
if (b < MSG_OK) {
  /* Note, this event is only added when the buffer becomes fully empty in
     order to avoid continuous reporting.*/
  bsAddFlagsI(self, CHN_FL_TX_NOTFULL);
}

return b;]]></implementation>
            </method>
          </regular>
          <inline>
            <method name="bsAddFlagsI" ctype="void">
              <brief>Adds status flags to the flags mask.</brief>
              <details><![CDATA[This function is usually called from the I/O
                ISRs in order to notify I/O conditions such as data events,
                errors, signal changes etc.]]></details>
              <param name="flags" ctype="eventflags_t" dir="in">Event flags to
                be added.
              </param>
              <implementation><![CDATA[

osalEventBroadcastFlagsI(&self->event, flags);]]></implementation>
            </method>
          </inline>
        </methods>
      </class>
    </types>
  </public>
  <private>
    <includes>
      <include style="regular">hal.h</include>
    </includes>
  </private>
</module>