lkml.org 
[lkml]   [2020]   [Sep]   [30]   [last100]   RSS Feed
Views: [wrap][no wrap]   [headers]  [forward] 
 
Messages in this thread
    Patch in this message
    /
    From
    Subject[PATCH v4 37/52] docs: sound: writing-an-alsa-driver.rst: get rid of :c:type
    Date
    the :c:type shouldn't be used with structs with Sphinx 3,
    as the C domain there uses .. c:struct for structs.

    As we have the automarkup extension, let's just get rid of
    all :c:type as a hole, as those will be automagically
    marked as such.

    This solves a bunch of warnings with Sphinx 3, like those:

    .../Documentation/sound/kernel-api/writing-an-alsa-driver.rst:490: WARNING: Unparseable C cross-reference: 'calling snd_card_free'
    Invalid C declaration: Expected end of definition. [error at 8]
    calling snd_card_free
    --------^
    .../Documentation/sound/kernel-api/writing-an-alsa-driver.rst:3328: WARNING: Unparseable C cross-reference: 'snd_rawmidi_transmit*'
    Invalid C declaration: Expected end of definition. [error at 20]
    snd_rawmidi_transmit*
    --------------------^
    .../Documentation/sound/kernel-api/writing-an-alsa-driver.rst:3928: WARNING: Unparseable C cross-reference: 'copy_from/to_user'
    Invalid C declaration: Expected end of definition. [error at 9]
    copy_from/to_user
    ---------^

    Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
    ---
    .../kernel-api/writing-an-alsa-driver.rst | 105 ++++++++----------
    1 file changed, 47 insertions(+), 58 deletions(-)

    diff --git a/Documentation/sound/kernel-api/writing-an-alsa-driver.rst b/Documentation/sound/kernel-api/writing-an-alsa-driver.rst
    index aa9d5ab183d2..85d6e9c643ef 100644
    --- a/Documentation/sound/kernel-api/writing-an-alsa-driver.rst
    +++ b/Documentation/sound/kernel-api/writing-an-alsa-driver.rst
    @@ -194,7 +194,7 @@ The minimum flow for PCI soundcards is as follows:

    - create ``remove`` callback.

    -- create a :c:type:`struct pci_driver <pci_driver>` structure
    +- create a struct pci_driver structure
    containing the three pointers above.

    - create an ``init`` function just calling the
    @@ -487,7 +487,7 @@ The destructor, remove callback, simply releases the card instance. Then
    the ALSA middle layer will release all the attached components
    automatically.

    -It would be typically just :c:func:`calling snd_card_free()`:
    +It would be typically just calling :c:func:`snd_card_free()`:

    ::

    @@ -560,16 +560,15 @@ return the card instance. The extra_size argument is used to allocate
    card->private_data for the chip-specific data. Note that these data are
    allocated by :c:func:`snd_card_new()`.

    -The first argument, the pointer of struct :c:type:`struct device
    -<device>`, specifies the parent device. For PCI devices, typically
    -``&pci->`` is passed there.
    +The first argument, the pointer of struct device, specifies the parent
    +device. For PCI devices, typically ``&pci->`` is passed there.

    Components
    ----------

    After the card is created, you can attach the components (devices) to
    the card instance. In an ALSA driver, a component is represented as a
    -:c:type:`struct snd_device <snd_device>` object. A component
    +struct snd_device object. A component
    can be a PCM instance, a control interface, a raw MIDI interface, etc.
    Each such instance has one component entry.

    @@ -628,7 +627,7 @@ argument of :c:func:`snd_card_new()`, i.e.
    err = snd_card_new(&pci->dev, index[dev], id[dev], THIS_MODULE,
    sizeof(struct mychip), &card);

    -:c:type:`struct mychip <mychip>` is the type of the chip record.
    +struct mychip is the type of the chip record.

    In return, the allocated record can be accessed as

    @@ -890,7 +889,7 @@ functions. These resources must be released in the destructor
    function (see below).

    Now assume that the PCI device has an I/O port with 8 bytes and an
    -interrupt. Then :c:type:`struct mychip <mychip>` will have the
    +interrupt. Then struct mychip will have the
    following fields:

    ::
    @@ -1094,7 +1093,7 @@ PCI Entries
    -----------

    So far, so good. Let's finish the missing PCI stuff. At first, we need a
    -:c:type:`struct pci_device_id <pci_device_id>` table for
    +struct pci_device_id table for
    this chipset. It's a table of PCI vendor/device ID number, and some
    masks.

    @@ -1110,19 +1109,17 @@ For example,
    };
    MODULE_DEVICE_TABLE(pci, snd_mychip_ids);

    -The first and second fields of the :c:type:`struct pci_device_id
    -<pci_device_id>` structure are the vendor and device IDs. If you
    -have no reason to filter the matching devices, you can leave the
    -remaining fields as above. The last field of the :c:type:`struct
    -pci_device_id <pci_device_id>` struct contains private data
    -for this entry. You can specify any value here, for example, to define
    -specific operations for supported device IDs. Such an example is found
    -in the intel8x0 driver.
    +The first and second fields of the struct pci_device_id are the vendor
    +and device IDs. If you have no reason to filter the matching devices, you can
    +leave the remaining fields as above. The last field of the
    +struct pci_device_id contains private data for this entry. You can specify
    +any value here, for example, to define specific operations for supported
    +device IDs. Such an example is found in the intel8x0 driver.

    The last entry of this list is the terminator. You must specify this
    all-zero entry.

    -Then, prepare the :c:type:`struct pci_driver <pci_driver>`
    +Then, prepare the struct pci_driver
    record:

    ::
    @@ -1439,8 +1436,8 @@ corresponding argument.
    If a chip supports multiple playbacks or captures, you can specify more
    numbers, but they must be handled properly in open/close, etc.
    callbacks. When you need to know which substream you are referring to,
    -then it can be obtained from :c:type:`struct snd_pcm_substream
    -<snd_pcm_substream>` data passed to each callback as follows:
    +then it can be obtained from struct snd_pcm_substream data passed to each
    +callback as follows:

    ::

    @@ -1639,10 +1636,9 @@ In the sections below, important records are explained.
    Hardware Description
    ~~~~~~~~~~~~~~~~~~~~

    -The hardware descriptor (:c:type:`struct snd_pcm_hardware
    -<snd_pcm_hardware>`) contains the definitions of the fundamental
    -hardware configuration. Above all, you'll need to define this in the
    -`PCM open callback`_. Note that the runtime instance holds the copy of
    +The hardware descriptor (struct snd_pcm_hardware) contains the definitions of
    +the fundamental hardware configuration. Above all, you'll need to define this
    +in the `PCM open callback`_. Note that the runtime instance holds the copy of
    the descriptor, not the pointer to the existing descriptor. That is,
    in the open callback, you can modify the copied descriptor
    (``runtime->hw``) as you need. For example, if the maximum number of
    @@ -1800,14 +1796,13 @@ Running Status
    ~~~~~~~~~~~~~~

    The running status can be referred via ``runtime->status``. This is
    -the pointer to the :c:type:`struct snd_pcm_mmap_status
    -<snd_pcm_mmap_status>` record. For example, you can get the current
    +the pointer to the struct snd_pcm_mmap_status record.
    +For example, you can get the current
    DMA hardware pointer via ``runtime->status->hw_ptr``.

    The DMA application pointer can be referred via ``runtime->control``,
    -which points to the :c:type:`struct snd_pcm_mmap_control
    -<snd_pcm_mmap_control>` record. However, accessing directly to
    -this value is not recommended.
    +which points to the struct snd_pcm_mmap_control record.
    +However, accessing directly to this value is not recommended.

    Private Data
    ~~~~~~~~~~~~
    @@ -1843,8 +1838,8 @@ error number such as ``-EINVAL``. To choose an appropriate error
    number, it is advised to check what value other parts of the kernel
    return when the same kind of request fails.

    -The callback function takes at least the argument with :c:type:`struct
    -snd_pcm_substream <snd_pcm_substream>` pointer. To retrieve the chip
    +The callback function takes at least the argument with
    +struct snd_pcm_substream pointer. To retrieve the chip
    record from the given substream instance, you can use the following
    macro.

    @@ -2313,10 +2308,10 @@ non-atomic contexts. For example, the function
    :c:func:`snd_pcm_period_elapsed()` is called typically from the
    interrupt handler. But, if you set up the driver to use a threaded
    interrupt handler, this call can be in non-atomic context, too. In such
    -a case, you can set ``nonatomic`` filed of :c:type:`struct snd_pcm
    -<snd_pcm>` object after creating it. When this flag is set, mutex
    -and rwsem are used internally in the PCM core instead of spin and
    -rwlocks, so that you can call all PCM functions safely in a non-atomic
    +a case, you can set ``nonatomic`` filed of struct snd_pcm object
    +after creating it. When this flag is set, mutex and rwsem are used internally
    +in the PCM core instead of spin and rwlocks, so that you can call all PCM
    +functions safely in a non-atomic
    context.

    Constraints
    @@ -2357,8 +2352,7 @@ There are many different constraints. Look at ``sound/pcm.h`` for a
    complete list. You can even define your own constraint rules. For
    example, let's suppose my_chip can manage a substream of 1 channel if
    and only if the format is ``S16_LE``, otherwise it supports any format
    -specified in the :c:type:`struct snd_pcm_hardware
    -<snd_pcm_hardware>` structure (or in any other
    +specified in struct snd_pcm_hardware> (or in any other
    constraint_list). You can build a rule like this:

    ::
    @@ -2467,7 +2461,7 @@ Definition of Controls

    To create a new control, you need to define the following three
    callbacks: ``info``, ``get`` and ``put``. Then, define a
    -:c:type:`struct snd_kcontrol_new <snd_kcontrol_new>` record, such as:
    +struct snd_kcontrol_new record, such as:

    ::

    @@ -2602,8 +2596,8 @@ info callback
    ~~~~~~~~~~~~~

    The ``info`` callback is used to get detailed information on this
    -control. This must store the values of the given :c:type:`struct
    -snd_ctl_elem_info <snd_ctl_elem_info>` object. For example,
    +control. This must store the values of the given
    +struct snd_ctl_elem_info object. For example,
    for a boolean control with a single element:

    ::
    @@ -2774,13 +2768,11 @@ In the simplest way, you can do like this:
    if (err < 0)
    return err;

    -where ``my_control`` is the :c:type:`struct snd_kcontrol_new
    -<snd_kcontrol_new>` object defined above, and chip is the object
    -pointer to be passed to kcontrol->private_data which can be referred
    -to in callbacks.
    +where ``my_control`` is the struct snd_kcontrol_new object defined above,
    +and chip is the object pointer to be passed to kcontrol->private_data which
    +can be referred to in callbacks.

    -:c:func:`snd_ctl_new1()` allocates a new :c:type:`struct
    -snd_kcontrol <snd_kcontrol>` instance, and
    +:c:func:`snd_ctl_new1()` allocates a new struct snd_kcontrol instance, and
    :c:func:`snd_ctl_add()` assigns the given control component to the
    card.

    @@ -2797,10 +2789,9 @@ can call :c:func:`snd_ctl_notify()`. For example,
    This function takes the card pointer, the event-mask, and the control id
    pointer for the notification. The event-mask specifies the types of
    notification, for example, in the above example, the change of control
    -values is notified. The id pointer is the pointer of :c:type:`struct
    -snd_ctl_elem_id <snd_ctl_elem_id>` to be notified. You can
    -find some examples in ``es1938.c`` or ``es1968.c`` for hardware volume
    -interrupts.
    +values is notified. The id pointer is the pointer of struct snd_ctl_elem_id
    +to be notified. You can find some examples in ``es1938.c`` or ``es1968.c``
    +for hardware volume interrupts.

    Metadata
    --------
    @@ -2915,9 +2906,8 @@ with an ``ac97_bus_ops_t`` record with callback functions.

    The bus record is shared among all belonging ac97 instances.

    -And then call :c:func:`snd_ac97_mixer()` with an :c:type:`struct
    -snd_ac97_template <snd_ac97_template>` record together with
    -the bus pointer created above.
    +And then call :c:func:`snd_ac97_mixer()` with an struct snd_ac97_template
    +record together with the bus pointer created above.

    ::

    @@ -3118,11 +3108,10 @@ devices on the card, set ``MPU401_INFO_IRQ_HOOK`` (see

    Usually, the port address corresponds to the command port and port + 1
    corresponds to the data port. If not, you may change the ``cport``
    -field of :c:type:`struct snd_mpu401 <snd_mpu401>` manually afterward.
    -However, :c:type:`struct snd_mpu401 <snd_mpu401>` pointer is
    +field of struct snd_mpu401 manually afterward.
    +However, struct snd_mpu401 pointer is
    not returned explicitly by :c:func:`snd_mpu401_uart_new()`. You
    -need to cast ``rmidi->private_data`` to :c:type:`struct snd_mpu401
    -<snd_mpu401>` explicitly,
    +need to cast ``rmidi->private_data`` to struct snd_mpu401 explicitly,

    ::

    @@ -3772,7 +3761,7 @@ For creating the SG-buffer handler, call
    :c:func:`snd_pcm_set_managed_buffer_all()` with
    ``SNDRV_DMA_TYPE_DEV_SG`` in the PCM constructor like other PCI
    pre-allocator. You need to pass ``&pci->dev``, where pci is
    -the :c:type:`struct pci_dev <pci_dev>` pointer of the chip as
    +the struct pci_dev pointer of the chip as
    well.

    ::
    --
    2.26.2
    \
     
     \ /
      Last update: 2020-09-30 15:27    [W:3.289 / U:0.048 seconds]
    ©2003-2020 Jasper Spaans|hosted at Digital Ocean and TransIP|Read the blog|Advertise on this site