Changeset 87b490e3 in mainline for uspace/lib/pcap/src


Ignore:
Timestamp:
2024-12-13T08:44:05Z (10 months ago)
Author:
Nataliia Korop <n.corop08@…>
Children:
420b13d
Parents:
fb31682
git-author:
Nataliia Korop <n.corop08@…> (2024-11-30 19:08:32)
git-committer:
Nataliia Korop <n.corop08@…> (2024-12-13 08:44:05)
Message:

docs comments

Location:
uspace/lib/pcap/src
Files:
5 edited

Legend:

Unmodified
Added
Removed

  • uspace/lib/pcap/src/pcap.c

    rfb31682 r87b490e3  
    11/*
    2  * Copyright (c) 2023 Nataliia Korop
     2 * Copyright (c) 2024 Nataliia Korop
    33 * All rights reserved.
    44 *
    … …  
    5353/** Add pcap file header to the new .pcap file.
    5454 *
    55  * @param writer writer that has destination buffer and ops to write to destination buffer.
    56  *
     55 * @param writer        Writer that has destination buffer and ops to write to destination buffer.
     56 * @param linktype      Linktype for the file header.
     57 * @param nano          True for nanoseconds, false for microseconds in timestamp.
    5758 */
    5859void pcap_writer_add_header(pcap_writer_t *writer, uint32_t linktype, bool nano)
    … …  
    6970/** Add packet to the .pcap file.
    7071 *
    71  * @param writer
    72  * @param captured_packet Packet to be dumped
    73  * @param size Size of the captured packet
     72 * @param writer                        Writer that has destination buffer and ops to write to destination buffer.
     73 * @param captured_packet       Packet to be dumped
     74 * @param size                          Size of the captured packet
    7475 *
    7576 */

  • uspace/lib/pcap/src/pcap_dumper.c

    rfb31682 r87b490e3  
    3030 * @{
    3131 */
    32 /** @file
    33  *  @brief pcap inteface: Dumping interface for the device which packets we want to dump
     32/** @file Pcap dumper. Structure is a part of every device that is in category PCAP and can dump packets.
    3433 */
    3534
    … …  
    4342/** Initialize writing to .pcap file.
    4443 *
    45  * @param writer    Interface for working with .pcap file.
     44 * @param writer    Interface for writing data.
    4645 * @param filename  Name of the file for dumping packets.
    47  * @return          EOK on success or an error code.
     46 * @return          EOK on success, otherwise an error code.
    4847 *
    4948 */
    … …  
    6665}
    6766
     67/** Open file for appending to the end of it.
     68 *  @param writer       Interface for writing data.
     69 *  @param filename Path to the file.
     70 *  @return             EOK on success, error code otherwise.
     71 */
    6872static errno_t pcap_writer_to_file_init_append(pcap_writer_t *writer, const char *filename)
    6973{
    … …  
    7680}
    7781
     82/** Initialize file for dumping usb packets.
     83 *  @param writer       Interface for writing data.
     84 *  @param filename Path to the file.
     85 *  @return             EOK on success, error code otherwise.
     86 */
    7887static errno_t pcap_writer_to_file_usb_init(pcap_writer_t *writer, const char *filename)
    7988{
    … …  
    94103}
    95104
     105/** Write 4B to the file.
     106 *  @param writer       Interface for writing data.
     107 *  @param data         Bytes to write.
     108 *  @return             Size of successfully witten data.
     109 */
    96110static size_t pcap_file_w32(pcap_writer_t *writer, uint32_t data)
    97111{
    … …  
    99113}
    100114
     115/** Write 2B to the file.
     116 *  @param writer       Interface for writing data.
     117 *  @param data         Bytes to write.
     118 *  @return             Size of successfully witten data.
     119 */
    101120static size_t pcap_file_w16(pcap_writer_t *writer, uint16_t data)
    102121{
    … …  
    104123}
    105124
     125/** Write block of bytes to the file.
     126 *  @param writer       Interface for writing data.
     127 *  @param data         Bytes to write.
     128 *  @param size         Size of block of bytes.
     129 *  @return             Size of successfully witten data.
     130 */
    106131static size_t pcap_file_wbuffer(pcap_writer_t *writer, const void *data, size_t size)
    107132{
    … …  
    110135}
    111136
     137/** Close file for writing.
     138 *  @param writer       Interaface for writing data.
     139 */
    112140static void pcap_file_close(pcap_writer_t *writer)
    113141{
    … …  
    116144}
    117145
     146/** Write <= 60B of block of bytes.
     147 *  @param writer       Interface for writing data.
     148 *  @param data         Bytes to write.
     149 *  @param size         Size of block of bytes.
     150 *  @return             Size of successfully witten data.
     151 */
    118152static size_t pcap_short_file_wbuffer(pcap_writer_t *writer, const void *data, size_t size)
    119153{
    … …  
    121155}
    122156
     157/** Standard writer operations for writing data to a newly created file. */
    123158static const pcap_writer_ops_t file_ops = {
    124159        .open = &pcap_writer_to_file_init,
    … …  
    129164};
    130165
     166/** Truncated writer operations. Only first 60 bytes of the packet are written. */
    131167static const pcap_writer_ops_t short_file_ops = {
    132168        .open = &pcap_writer_to_file_init,
    … …  
    138174};
    139175
     176/** Append writer operations. Instead of creating new file open existing file and append packets. */
    140177static const pcap_writer_ops_t append_file_ops = {
    141178        .open = &pcap_writer_to_file_init_append,
    … …  
    146183};
    147184
     185/** USB writer operations. Writing USB packets to the file. */
    148186static const pcap_writer_ops_t usb_file_ops = {
    149187        .open = &pcap_writer_to_file_usb_init,
    … …  
    154192};
    155193
     194/** Default array of operations. Must be consistens with constants in /uspace/app/pcapctl/main.c */
    156195static pcap_writer_ops_t ops[4] = { file_ops, short_file_ops, append_file_ops, usb_file_ops };
    157196
     197/** Get number of writer operations in @ref ops */
    158198int pcap_dumper_get_ops_number(void)
    159199{
    … …  
    161201}
    162202
     203/** Open destination buffer for writing and set flag for dumping.
     204 *  @param dumper       Structure responsible for dumping packets. Part of the driver.
     205 *  @param name         Name of the destination buffer to dump packets to.
     206 *  @return             EOK if successful, erro code otherwise.
     207 */
    163208errno_t pcap_dumper_start(pcap_dumper_t *dumper, const char *name)
    164209{
    … …  
    174219}
    175220
     221/** Set writer options for the writer.
     222 *  @param dumper       Structure responsible for dumping packets. Part of the driver.
     223 *  @param index        Index of the writer operations from array @ref ops.
     224 *  @return             EOK if successful, erro code otherwise.
     225 */
    176226errno_t pcap_dumper_set_ops(pcap_dumper_t *dumper, int index)
    177227{
    … …  
    183233}
    184234
     235/** Write packet to destination buffer.
     236 *  @param dumper       Structure responsible for dumping packets. Part of the driver.
     237 *  @param data         Packet data to write.
     238 *  @param size         Size of the packet.
     239 */
    185240void pcap_dumper_add_packet(pcap_dumper_t *dumper, const void *data, size_t size)
    186241{
    … …  
    196251}
    197252
     253/** Close destination buffer for writing and unset flag for dumping.
     254 *  @param dumper       Structure responsible for dumping packets. Part of the driver.
     255 */
    198256void pcap_dumper_stop(pcap_dumper_t *dumper)
    199257{

  • uspace/lib/pcap/src/pcapdump_client.c

    rfb31682 r87b490e3  
    3030 * @{
    3131 */
    32 /** @file
    33  * @brief Client side of the pcapctl. Functions are called from the app pcapctl
     32/** @file Client side of the pcapctl. Functions are called from the app pcapctl.
    3433 */
    3534
    … …  
    5251}
    5352
     53/** Get service based on the index of the device.
     54 *  @param index of the device.
     55 *  @param svc placeholder for service ide.
     56 *  @return EOK if successful, error code otherwise.
     57 */
    5458static errno_t pcapctl_cat_get_svc(int *index, service_id_t *svc)
    5559{
    … …  
    8084}
    8185
     86/** Check if the index is an index of valid device.
     87 *  @param index to check.
     88 *  @return EOK if device is valid, error code otherwise.
     89 */
    8290errno_t pcapctl_is_valid_device(int *index)
    8391{
    … …  
    105113}
    106114
     115/** Check if the index is an index of valid writer operations.
     116 * @param index to check.
     117 * @param sess  pcapctl session for IPC communictaion.
     118 */
    107119errno_t pcapctl_is_valid_ops_number(int *index, pcapctl_sess_t *sess)
    108120{
    … …  
    127139}
    128140
    129 /**
    130  *
    131  */
     141/** Get all devices that can dump packets. */
    132142errno_t pcapctl_list(void)
    133143{
    … …  
    160170}
    161171
    162 /**
    163  *
     172/** Start pcapctl IPC session.
     173 *  @param index        index of the device which can dump packets.
     174 *  @param rsess        placeholder for the session.
     175 *  @return                     EOK if successful, error code otherwise.
    164176 */
    165177errno_t pcapctl_dump_open(int *index, pcapctl_sess_t **rsess)
    … …  
    196208}
    197209
    198 /**
    199  *
     210/** Close pcapctl IPC session.
     211 *  @param sess Session to close.
     212 *  @return EOK if successful, error code otherwise.
    200213 */
    201214errno_t pcapctl_dump_close(pcapctl_sess_t *sess)
    … …  
    205218}
    206219
    207 /** Starting a new session for pcapctl
    208  *
    209  * @param name Name of the file to dump packets to
    210  * @param sess session to start
    211  * @return EOK on success or an error code
     220/** Send start request via IPC to start dumping.
     221 *
     222 * @param name  Name of the destination buffer to dump packets to.
     223 * @param sess  Session that is used for communication.
     224 * @return              EOK on success or an error code.
    212225 */
    213226errno_t pcapctl_dump_start(const char *name, int *ops_index, pcapctl_sess_t *sess)
    … …  
    233246}
    234247
    235 /** Finish current session for pcapctl
    236  *
    237  * @param sess Session to finish
    238  * @return EOK on success or an error code
     248/** Send stop request via IPC to start dumping.
     249 *
     250 * @param sess  Session that is used for communication.
     251 * @return              EOK on success or an error code.
    239252 */
    240253errno_t pcapctl_dump_stop(pcapctl_sess_t *sess)

  • uspace/lib/pcap/src/pcapdump_drv_iface.c

    rfb31682 r87b490e3  
    4848#define NAME "pcap"
    4949
    50 /** Initialize interface for dumping packets
    51  *
    52  * @param dumper Device dumping interface
    53  *
     50/** Initialize interface for dumping packets.
     51 * @param dumper        Device dumping interface.
     52 * @return                      EOK if successful, error code otherwise.
    5453 */
    5554static errno_t pcapdump_drv_dumper_init(pcap_dumper_t *dumper)
    … …  
    6766}
    6867
     68/** Initialize driver dumping functionality.
     69 *  @param dumper       Dumping interface of the driver.
     70 *      @return                 EOK if successful, error code otherwise.
     71 */
    6972errno_t pcapdump_init(pcap_dumper_t *dumper)
    7073{
    … …  
    8689}
    8790
    88 /** Dumping function for driver
     91/** Dumping function for driver.
    8992 *
    90  * Called every time, the packet is sent/recieved by the device
     93 * Called every time, the packet is sent/recieved by the device.
    9194 *
    92  * @param dumper Dumping interface
    93  * @param data The packet
    94  * @param size Size of the packet
     95 * @param dumper        Dumping interface.
     96 * @param data          The packet
     97 * @param size          Size of the packet.
    9598 *
    9699 */

  • uspace/lib/pcap/src/pcapdump_srv.c

    rfb31682 r87b490e3  
    4747#include "pcapdump_ipc.h"
    4848
     49/** Start dumping.
     50 *      @param icall    IPC call with request to start.
     51 *  @param dumper       Dumping interface of the driver.
     52 */
    4953static void pcapdump_start_srv(ipc_call_t *icall, pcap_dumper_t *dumper)
    5054{
    … …  
    8488}
    8589
     90/** Stop dumping
     91 *      @param icall    IPC call with request to stop.
     92 *  @param dumper       Dumping interface of the driver.
     93 */
    8694static void pcapdump_stop_srv(ipc_call_t *icall, pcap_dumper_t *dumper)
    8795{
    … …  
    9098}
    9199
     100/** Get number of accessibke writer operations.
     101 *      @param icall    IPC call with request to get number of accessible writer operations.
     102 */
    92103static void pcapdump_get_ops_num_srv(ipc_call_t *icall)
    93104{
    … …  
    99110}
    100111
     112/** Callback connection function. Accepts requests and processes them.
     113 *      @param icall    IPC call with request.
     114 *  @param arg          Dumping interface of the driver.
     115 */
    101116void pcapdump_conn(ipc_call_t *icall, void *arg)
    102117{
Note: See TracChangeset for help on using the changeset viewer.