>> Documentation/driver-api/soundwire/bra.rst | 478 ++++++++++++++++++ > > Can we split the cadence parts of this to bra-cadence.rst that way this > file documents the core parts only Yes, we can split the Cadence parts out. >> +Error handling >> +~~~~~~~~~~~~~~ >> + >> +The expected response to a 'bra_message' and follow-up behavior may >> +vary: >> + >> + (1) A Peripheral driver may want to receive an immediate -EBUSY >> + response if the BRA protocol is not available at a given time. >> + >> + (2) A Peripheral driver may want to wait until a timeout for the >> + on-going transfer to be handled >> + >> + (3) A Peripheral driver may want to wait until existing BRA >> + transfers complete or deal with BRA as a background task when >> + audio transfers stop. In this case, there would be no timeout, >> + and the operation may not happen if the platform is suspended. > > Is this runtime suspend or S3/S4 case? System suspend (which can also mean S0i1). I don't think we can have a case where a peripheral driver waits on something without having done a pm_runtime_get_sync() to prevent runtime_pm suspend. > >> +BTP/BRA API available to peripheral drivers >> +------------------------------------------- >> + >> +ASoC Peripheral drivers may use >> + >> + - sdw_bpt_stream_open(mode) >> + >> + This function verifies that the BPT protocol with the >> + 'mode'. For now only BRA is accepted as a mode. This function >> + allocates a work buffer internally. This buffer is not exposed >> + to the caller. >> + >> + errors: >> + -ENODEV: BPT/BRA is not supported by the Manager. >> + >> + -EBUSY: another agent is already using the audio payload for >> + audio transfers. There is no way to predict when the audio >> + streams might stop, this will require the Peripheral driver >> + to fall back to the regular (slow) command channel. >> + >> + -EAGAIN: another agent is already transferring data using the >> + BPT/BRA protocol. Since the transfers will typically last >> + 10s or 100s of ms, the Peripheral driver may wait and retry >> + later. >> + >> + - sdw_bpt_message_send_async(bpt_message) > > why not have a single API that does both? First check if it is supported > and then allocate buffers and do the transfer.. What are the advantages > of using this two step process Symmetry is the only thing that comes to my mind. Open - close and send - wait are natural matches, aren't they? We do need a wait(), so bundling open() and send() would be odd. But you have a point that the open() is not generic in that it also prepares the DMA buffers for transmission. Maybe it's more natural to follow the traditional open(), hw_params(), hw_free, close() from ALSA.
